documentation

[charlesdaniels]

Documentation should be built automatically using Breathe + Doxygen. This is especially important for NocsimTCL, since it is user-facing. You can find an example here. Based on my experience with that project, I would suggest creating a self-contained doc/ folder with all scripts and supplemental docs (such as the stand-alone scripting manual, which will continue to be it's own thing, but should show up as a page within the Breathe output. A Dockerfile should probably be used, and for the convenience of users and other people who want to hack on the project, it should be scripted so that build_docs.sh (or whatever) uses the Dockerfile automatically. This is because the toolchain for using Breathe and Doxygen together is very complex and has many transient dependencies.

• generate HTML
• generate PDF
• generate docs as part of CI

[charlesdaniels]

In retrospect, I think keeping everything in doc/ as plain markdown files is a fine solution for now.