-
Notifications
You must be signed in to change notification settings - Fork 10
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
replacing the way Typegraphs are generated #430
Comments
I'm wondering how this would look, potentially. Can you paste an example, even a speculative one. |
@dontlaugh I have this for
|
That does look pretty good for smaller graphs. I say go for it. It will also let us experiment with other diagram DSLs. I've used Mermaid way more than dot+Graphviz. We still need to solve the problem of keeping these definitioned sync'd with upstream Rakudo. Relying on the fact that most types don't change that often is no good. We should be able to derive these class/type relationships from Rakudo source code, but I'm not aware of any script that does that, currently. |
I can work on the derivation from Rakudo source to a (e.g.) file we can check in - we can regen them as needed (occasionally) and the the dates can be used in the build system to determine if a page needs to be regen'd. |
@coke not sure if you agree to including the graph definitions within the rakudoc sources or not. |
@coke @dontlaugh tl;dr asking for ideas
Currently the build process (and by consequence in particular the way typegraphs are generated) is suboptimal.
Currently (using Collection), changes to sources (the rakudoc files in the
Raku/docs/doc/
directory) are detected and new ones are re-cached (good).All cached sources are re-rendered to HTML (bad). In Elucid8 (the Collection re-write), a record is kept of when html files are generated, and only those that are older than sources are re-rendered. (good). So on a rebuild, only new files are generated.
Currently, pre-generated typegraphs svgs are attached to documentation by matching the name of the typegraph svg to the name of the source. Not all Types have svgs. I'm not sure whether the opposite is true.
Typegraph svgs are independently generated in three stages
Since the first step hasnt changed for years, nor should the last, but it gets done every build. This is a waste of time and what I would like to change now.
I dont know how the definition file was generated, but it should be done programaticallly. Is anyone sure that the type definitions have not been modified?
Coleman and I have tried to ensure a single build rather than re-generating the svgs each time the htmls are generated. But its been difficult to hook them together. Also, it is not easy to arrange for the Table of Contents to have a reference to the image.
We could adopt other strategies:
a) keep the current situation. Have a pool of svgs and connect the svg to the html at the html build time. I don't like this idea as it depends on the software to keep two pools of files in sync with each other based on file names.
b) have a pool of svgs in some fixed directory, but include a link to the image in a normal way.
advantages:
disadvantage:
c) have the dot digraph definition in the body of the source, and arrange for it to be generated with the html. (The custom block to do this is already a part of both Collection and Elucid8)
advantages (in addition to the above):
disadvantage:
I think the source of the documentation and the source of the graphs should be united, whether in svg form, dot form, or a link to an image.
This will need a change to the rakudoc source, but I think this can be done programatically relatively easily.
However there is a cost / benefit to each of the strategies.
Any thoughts?
The text was updated successfully, but these errors were encountered: