Various improvements to the tutorials framework.

[apsabelhaus]

It's currently unclear how to build the tutorials: my students and I had to dig around to figure out that we needed to install python-sphinx in our ubuntu environments. We should include these dependencies in our install instructions, and provide a guide on how to build them and use them,

Also, we should consider having the tutorials build automatically when the simulator is compiled. Maybe build.sh can have a flag to call make in the tutorials directory.

Also, the location and purpose of our tutorials, as well as the differentiation between tutorials and code documentation, should be better described: for example, the "doc" folder has the tutorials in it, while the src/DoxyDocs folder has the code documentation in it (?!?!)

[brtietz]

Do you have thoughts on how to differentiate these two resources, or at least clarify what is where? The original theory behind the doc folder was that format was easier to write than doxygen. What do you prefer?

[apsabelhaus]

Hey Brian! First, apologies for asking for changes without proposing anything.

The idea of a "doc" folder is a solid one in my mind at least, and I agree that the sphinx documentation is easier to write than Doxygen documentation.

How about the following infrastructure:

• Migrate all documentation to doc. No more doxydocs build in the src folder. Doxygen gets built under doc/api, since that's really what we're using doxygen for right now (just info about classes and methods.) Any thoughts on how to make this clean? Moving the doxydocs file?

• Tutorials have source in doc/tutorials/src, and built docs go in doc/tutorials/html etc. Or some other structure that keeps everything in doc/tutorials.

• We now refer to "NTRTsim documentation" as API + tutorials.

• Remove the old 2014 documentation from doxygen and migrate it into sphinx/tutorials, which is where it probably belongs now. Now on the main doxygen index.html page, there would be a short message explaining that the doxygen is for the API only, and that all other documentation is in tutorials. Describe the difference between an application programming interface vs. other documentation, for new developers.

• Have a unified way to build all of this. For example, flags in build.sh to build (a) api (b) tutorials (c) both. To-do: decide if we want this to happen automatically with compilation (e.g. what's the default behavior in build.sh?)

• We could have information in README.md about where the "introduction to NTRTsim documentation" is located, which would probably be in the sphinx tutorials.

• Tutorials have a page about how to write comments in the code itself so that the doxygen api is all nice and pretty.

• Tutorials have a more fleshed-out page on "how to contribute tutorials" so that our developers don't have to go rooting through the sphinx webpage for basics like formatting of .rst files.

I'm happy to do some of this after my qualifying exam in early April. Anyone else interested in helping?

"repeal and replace NTRTsim documentation!" (to soon?)