This PR adds cleanups to the documentation, reorganizes its structure to be more user-friendly, and adds testing for the code snippets to ensure that they remain accurate.
There is now an environment.yml file so that we can build the docs and test them within a conda env. I also wrote a convenience script called autoreload_docs.py which aids documentation development by watching the doc sources for changes and automatically rebuilding the Sphinx output when an rst file is modified.
Code snippet testing uses the doctest extension for Sphinx: http://www.sphinx-doc.org/en/stable/ext/doctest.html . Currently doctests are only written for the "Quick Start" section, but tests can be added to other sections in a similar manner. I put off adding tests for all code blocks because some rely on files being downloaded, or are slightly more involved to test. However we can always add them later on (time permitting).
@PeterDSteinberg if you get the chance, could you please read over some of my wording changes for describing elm's functionality, and confirm that they're accurate?
This PR adds cleanups to the documentation, reorganizes its structure to be more user-friendly, and adds testing for the code snippets to ensure that they remain accurate.
There is now an
environment.yml
file so that we can build the docs and test them within a conda env. I also wrote a convenience script calledautoreload_docs.py
which aids documentation development by watching the doc sources for changes and automatically rebuilding the Sphinx output when an rst file is modified.Code snippet testing uses the
doctest
extension for Sphinx: http://www.sphinx-doc.org/en/stable/ext/doctest.html . Currently doctests are only written for the "Quick Start" section, but tests can be added to other sections in a similar manner. I put off adding tests for all code blocks because some rely on files being downloaded, or are slightly more involved to test. However we can always add them later on (time permitting).@PeterDSteinberg if you get the chance, could you please read over some of my wording changes for describing
elm
's functionality, and confirm that they're accurate?