Documentation

Documentation is available on ReadTheDocs. Each time a commit is made here, the documentation gets rebuilt. The following information is useful for collaborators of this project.

Building documentation locally

This is useful for testing out the documentation build locally, i.e. before making a new project release. Before attempting to troubleshoot build issues on RTD, you need to ensure that everything looks right locally first since debugging on RTD can be a little tricky at times.

Here are the steps to building the documentation locally. First, ensure you have installed the PyPI projects sphinx and sphinx-argparse.

1. In a local project clone, navigate to the docs directory: cd encode_utils/docs
2. Remove the existing build directory, if there is one: rm -rf _build
3. Build the documentation with make html as noted in the quick-start guide.
4. Notice any error or warning messages in the build output, if any, and take necessary action to fix them.
5. Open the local documentation in your browser and verify that everything looks like it's showing as expected: open _build/html/index.html.

Once things look good locally, you can then push your final commits to GitHub, and then check out the documentation build on RTD. Note that even when there aren't any documentation build errors locally, there can still be some on RTD. When things don't look expectedly, gloss through the build docs on RTD to try and identify any issues encountered.