ContinuumIO / elm

Phase I & part of Phase II of NASA SBIR - Parallel Machine Learning on Satellite Data
http://ensemble-learning-models.readthedocs.io
43 stars 27 forks source link

Documentation improvements #176

Closed gbrener closed 7 years ago

gbrener commented 7 years ago

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?

PeterDSteinberg commented 7 years ago

@gbrener I'll build this locally now and look at it.

PeterDSteinberg commented 7 years ago

Looks good - Thanks for adding the auto reload script.