Decide on a technology for documentation

[jcfreeman2]

Since early in the summer, official DUNE DAQ software documentation has been based in the appfwk package's wiki. This isn't a long term solution, so we're looking into other approaches for organizing and presenting the DUNE DAQ software documentation. I believe the following are reasonable requirements:

1. It should be possible to write documentation in markdown as is done on github, rather than being required to use another approach (e.g., rst)
2. It should be relatively easy for documenters to see the output of their edits before committing a change, at the very least to the extent that they should be able to determine if there's a syntax error in their markdown file
3. There should be documentation specific to each DUNE DAQ software release, and while we can archive documentation for older versions, the last couple of versions should be available
4. The build process for documentation should be straightforward for a given package (e.g., adding a --builddoc option to dbt-build.sh), but typically shouldn't need to be done by the user but rather handled behind-the-scenes (e.g., through a CI approach)
5. Only markdown documents directly written by developers and fed into a generator, and not the html output of the generator, should be committed

I've already thought a bit about the technologies to use. For document generators, the candidates have been MkDocs, Sphinx and Jekyll. For document display, GitHub Pages and ReadTheDocs.

Jekyll's ruby-based and at the last software coordination meeting it was agreed that the hassle of having this dependency on the stack was effectively disqualifying.

GitHub Pages expects the html to be on the git branch, which violates (5.) above.

This leaves us with ReadTheDocs for hosting/presentation, and a choice between MkDocs and Sphinx. I'm leaning toward MkDocs, since its root directory is docs/ and GitHub is capable of automatically displaying a README.md in a docs/ subdirectory of a repo. For Sphinx, README.md would need to be in source/docs/, and therefore couldn't get displayed by GitHub. This relates to (2), above.

I've forked this repo into my own GitHub account (https://github.com/jcfreeman2/dont-readme/) and been playing around with MkDocs and Sphinx. With the caveat that the actual information shown on the websites isn't the same, an example of a MkDocs-generated website can be found here and an example of a Sphinx-generated website can be found here

[alessandrothea]

Thanks for the neat summary. I just have one comment

GitHub Pages expects the html to be on the git branch, which violates (5.) above.

Yes and no. Whether the HTML sits on a branch of the source repo or on the master of a separate repo is a choice for us to make. The former is incompatible with (5), as you say, the latter could work.

[jcfreeman2]

We went with ReadTheDocs + MkDocs (see my talk from this morning, https://indico.fnal.gov/event/47549/contributions/211739/attachments/141619/178393/dunedaq-documentation.pdf)