Adding documentation

[adamnovak]

I've added a doc folder with the Dia file for my ever-popular UML diagram.

I'm also adding a contrib folder with the Doxyfile and Python filter script I used to make the UML (via import of Doxygen XML files).

I'm updating GeneratingDocumentation.md to describe how to do this.

While I'm at it, I liked the simple build process of Doxygen, so I've put in a script contrib/make_avrodoc.sh to do all the steps specified in the markdown file, and documented its use.

[adamnovak]

I know people in #243 want more documentation. Is this the right way to structure it?

[fnothaft]

This is great but I would really (strenuously?) like to see a few simple queries written out using the new API. E.g., what does a SNP/short INDEL look like in each representation? How do I walk the graph to find all variants within 10kbp of a specific site? etc.

[adamnovak]

OK, I have added a "Graph Mode FAQ" markdown file, with the answers to these questions. I know it's incomplete, but if we throw it in, people can start making pull requests with questions they want answered, and we can keep all the answers in one place that's under revision control, instead of having them scattered across many issues and e-mail threads.

[jeromekelleher]

I like the idea of a graph mode FAQ, but please rename it to remove the spaces in the file name.

[pgrosu]

+1, the docs looks great and feel free to use images too instead of just ASCII-text figures. Not sure how many people will find generating the doc easy, but can you include a premade image of the UML diagram as well as the doxygen html outputs for the schemas/API?

[adamnovak]

I'm reluctant to include the Doxygen HTML output, because I don't want to compete with Avrodoc. In fact, I told Doxygen not to generate HTML output, only the XML that Dia needs.

I have put the GeneratingDocumentation.md file in the doc folder now, and removed the spaces from the FAQ filename. I've also included an SVG of the UML, which more than just Dia can read.

[adamnovak]

Any other comments on this? Any more questions for the FAQ?

[macieksmuga]

Amend this to allow for inclusion of .vsdx (Visio XML) diagrams as well as .dia?

[adamnovak]

I'm not disallowing those, but I don't really have the right software to make one. I could throw in an exported .vdx from Dia if you would like.

[macieksmuga]

Nah, that wasn't my intention. I think it makes perfect sense to include both the source file and the resulting SVG, as you did here. My only suggestion (perhaps better aimed at the CONTRIBUTING.md, now that I think about it) was to allow for optional future inclusion of .vsdx files if the creator had used a tool that natively supports them.

[delagoya]

+1

Any other comments or suggestions?

[adamnovak]

I think this is mergable, since it has two +1s and I've addressed (to my own satisfaction) the other comments.

I've updated the Markdown files to reflect the side graph changes and rebased against master. The UML needs to be updated for side graphs, but I figure I (or someone else who has a better version of my UML-making process) can do that after this is in.