Automate documentation creation

[JamesOwers]

We want to solve 3 problems regarding documentation:

1. We don't want to have to rerun the ipynb files in ./docs after each change by hand, this is an issue because: a. this is easily forgotten/new contributors wouldn't know to do this, and it is and long! b. version control is made hard: output data saved in the files is always different, so diffs on the files are very large and not representative of the code which was changed (if any)
2. The evaluated ipynb files are very large, this is a problem because: a. they're difficult to version control (see above) b. pulling the repo takes a long time
3. We would like an easy way to browse documentation of the package

Looked into readthedocs (#97 ) and propose the following:

• [ ] As a temporary solution for points 1 & 2:
  • [ ] configure binder to operate on the existing notebooks, follow instructions here
  • [ ] check this works, then remove the evaluated ipython notebooks from history (to reduce the size of the repo)
  • at this point, we would only ever commit changes to the code in the notebooks, and documentation would automatically be generated by binder
• [ ] As a better solution to issues 1 and 2:
  • [ ] Convert the ipython notebooks to markdown with code cells runnable by codebraid
    • [ ] Quickly check out the pandas way of making docs - and play off against using codebraid. Think about whether this would allow us to keep the ipynb files too, and whether that's important.
  • [ ] Install codebraid (which runs code cells in markdown files) and add this to the makefile for sphinx. Pweave does something similar here
  • Now we have documentation which autogenerates on readthedocs servers!
  • [ ] Remove binder? Or move the example notebooks? My preference will be that we only ever have one copy of the code so, if codebraid allows, keep either the .md or .ipynb, as the 'base' file to edit code from, and autogen the rest. If this cant be done, I'd vote to remove the ipynb files and binder.
• [ ] As a solution to 3:
  • [ ] configure sphinx with autodoc to generate documentation for the package
  • [ ] add the documentation generation step to Travis CI (example)

[JamesOwers]

Actually- look into NBDev in place of binder, just quickly! https://github.com/fastai/nbdev https://www.youtube.com/watch?v=9Q6sLbz37gk&ab_channel=JeremyHoward

[JamesOwers]

This also looks awesome! https://github.com/mwouts/jupytext