Build and host documentation

[mphoward]

The documentation will likely be hosted on readthedocs. A few things need to be

• [x] Add sphinx boilerplate to make documentation.
• [x] Check that there are no typos in the documentation and that it can compile.
• [x] Figure out a way to compile the documentation within a conda environment (so that a hoomd package can be found) or else hope that automock works well enough.
• [ ] Consider adding an internal bibliography using HOOMD's cite module to support important references.

[astatt]

I know it is some amount of work but I would be interested in writing short tutorials/examples for

1. using the some components of the plugin. Along the lines of "this is how you do a explicit evaporation simulation, example LJ spheres + solvent. this is how you do an implicit evaporation simulation" or this is how you "set up mpcd+ reverse perturbation flow+ a single polymer chain".

2. implementing new features, simplest example could be bond or pair potential. We already have bits of this in the headers anyway.

I've found that people have a much easier time to use new software if there are step by step tutorials. This might help to attract more users who might not know us or our groups personally. It would happen as I get students and have time.

I'm not sure if this is of interest and if this has to be in the github. What do you think?

[mphoward]

This would be great. I think that these are essentially two types of examples.

The example usage ones could be either scripts or jupyter notebooks. The advantage of the latter is that they can be displayed as html in a browser, including figures, but they are not so easy to look at if you don't have jupyter installed locally. The scripts are also fine by me if they are well commented. Either way, these could probably go in a tutorial directory that is included with this repo. If there are a few "prototypical" examples, we could also consider including these in static compiled documentation.

The tutorials for implementing new features would be excellent developer docs that would be implemented as standalone restructred text files included by sphinx. These would then be hosted on RTD alongside the docs for the existing API.

I would very much welcome this as a public contribution to the repo if you are interested.

[mphoward]

Docs now build, but we need to expand some of the concept pages and connect them to readthedocs.

[astatt]

There is a package for integrating Jupyter notebooks into sphinx: https://nbsphinx.readthedocs.io/en/0.7.1/index.html. I also needed to install pandoc separately to make it work: https://pandoc.org/installing.html The notebooks appear to need to be in the 'doc/source/tutorial' subfolder for it to work, or any doc subfolder, but they make the most sense there. There is a way around it with json link files, external ..include:: paths do not appear to work correctly. I haven't tested it yet, requires more additional packages: https://github.com/vidartf/nbsphinx-link

There is also concern about git repro sizes depending on how the Jupiter notebooks are saved, their output can be large. See: https://github.com/PyPSA/atlite/issues/38

Otherwise straightforward and easy, see commit e894f88 on the tutorials branch.

If we are fine with the tutorials living in 'doc/source/tutorial' I can clean them up, titles etc.

[mphoward]

This is an excellent start. Have you tried setting the nbsphinx_execute option to never in conf.py so that it doesn't run the notebooks when sphinx builds? I think this would be a good idea so that the notebooks display as we have prepared them.

How much output do your tutorial notebooks include? If it isn't too much, we probably don't need to worry about bulky size, unless there are alot of figures or something.

[astatt]

The tutorials I have right now are 636K total (all files, 3 pngs so far) so I don't think that's going to be a problem. we just should keep it in mind for the future. nbsphinix doesn't run the notebooks (at least not for me on my mac) but setting the option is a good idea since that is the desired behavior.

[mphoward]

Great! Supposedly nbsphinx will try to run the notebook if there is output in it. The execution would likely fail (as an error) if a compiled version of azplugins is not on the path, but I can imagine someone accidentally checking in output if they have it saved. Forcing it off would not raise this error, but it would potentially allow someone to save output. Which do you think is better?

[astatt]

I'm not sure. Saving output is "only" bad because it increases the git unnecessarily, so forcing off is probably the better option. I still also need to fix the latexpdf doc build and then all the typos/formatting issues with equations etc. Would you prefer to have similar tutorials (e.g. explicit and implicit evaporation) on one page (=same notebook) or as two separate notebooks like they are now? That changes how the TOC looks like etc.

[mphoward]

If there's alot of duplication between them (in that case, it looks like you're recycling alot of the setup & analysis code), it might be nice to have both in the same page.

[astatt]

I've merged the evaporation and the reverse perturbation tutorials into one notebook each, but kept the hoomd run script *.py files separate. I also tried to find and fix all formatting issues to make it compile ( make html and make latexpdf are both working now). Most issues are coming from equations: Equations with $...$ can't have line breaks in them, and they can't have stray whitespaces at the beginning of the line. I've also fixed some links pointing to the wrong spot.

I did not modify the content too much, we can still edit and refine as we go if we want to. Are there any other topics for documentation or tutorials we should work on?

[mphoward]

Great! Could you open a PR with the tutorials so that I can see what's there now?

[mphoward]

Close via #55