wires
wires copied to clipboard
esoeylemez
documentation: add a visual API overview
Thanks for your contribution!
I would very much prefer if we don't have source and output files within the repo, especially not PDF, which is impossible to audit. Is there a way to build SVG instead? And if yes, could you move the wires-overview.graphml file into a docs subdirectory and write a short Makefile that builds the SVG from it? Then we could do something similar to the lens library and just link to the wiki from the README.md.
Ertugrul, the problem is that the PDF/SVG would have to be produced using yEd[1], which is a free-as-in-beer Java application download -- interactively.
Even if it was produced with something like VUE[2] (which is a similar application), which is free-as-in-speech, the automation would be still impossible, since it, too, cannot be run in batch mode.
- http://www.yworks.com/products/yed
- http://vue.tufts.edu/
Okay, for now I have merged the latter commit into a separate branch called graphml. One option to make this work in batch mode is to use an XSLT transform.
Ertugrul, even if you don't agree on merging the non-batch-derived PDF files, you still may consider linking to them.
The GraphML/yEd-by-XSLT-to-SVG path might take a long way, and still look less appealing, than the tailor-produced direct rendering by the native GraphML/yEd exporter -- and here it's important to note, that GraphML doesn't specify a whole lot, and yEd takes a lot of liberty to extend the format, to make it appealing/useful.
Yeah, that I don't mind doing.
But your PR got me thinking. What's your opinion on using GraphViz together with a DOT file instead? It's similarly powerful, but can be updated using a regular text editor, so I could keep it updated as I add/merge changes into the code base (not overly fond of using a separate non-free GUI tool, as you might imagine). That's also something a CI like Hydra could build by itself, so consistently linking to the most up-to-date version would be effortless.
If that sounds like a good idea to you, I wouldn't mind doing the initial revision of that.
The automation & updateability is a good thing.
The unavoidable loss of visual fidelity & semantic nuances -- since you hardly can match automated output with manually-crafted output -- well, it's arguably a downside.
Visual impact is important to attract users (pretty pictures can be powerful to a subset of population..) Automation is important to ease maintenance. Although, I guess it's important to note, that the API isn't large (yet).
The relative importance of those factors is something that only you can decide! : -)