Adding Sphinx API documentation

In pull requests that introduce new modules, it is important to include sphinx documentation as part of the PR. To do this, simply add (or edit, if it already exists), a .rst file to the jwql/docs/source/ directory named <module_name>.rst. This file should look something like this:

***********
module_name
***********

.. automodule:: jwql.subpackage_name.module_name
    :members:
    :undoc-members:

Additionally, if it doesn't already exist, include a pointer to the new .rst file in the jwql/source/index.rst file under the API documentation section, for example:

API documentation
=================

.. toctree::
   :maxdepth: 1
   :caption: Contents:

   permissions.rst
   preview_image.rst
   utils.rst
   tests.rst
   <new_rst_file>.rst

These changes to the repository should be committed and pushed as part of the pull request.

Viewing the documentation locally

Once you edit the .rst files, you will probably want to see what they would look like integrated into the documentation. You can build and view the docs locally with the following commands:

cd jwql/docs/
export DJANGO_SETTINGS_MODULE=jwql.website.jwql_proj.settings
make html
open build/html/index.html

Note that you will need to re-make the files every time you edit them.

Generating ReadTheDocs Documentation

After viewing the documentation locally, you can generate the ReadTheDocs pages by pushing your changes to a branch specifically for testing ReadTheDocs. That way, you can generate these pages before pushing your changes to the development version of JWQL.

To do this, you'll need to make a ReadTheDocs account. Ask someone on the team (perhaps Matthew or Teagan) to add you to the JWQL project. Now, on your dashboard, you'll see the JWQL project. If you click on the project, you can view new and previous builds on the Builds tab. Under the Admin tab, you can confirm which branch you are viewing under Advanced Settings in Default Version. This is set to the branch test-readthedocs, which corresponds directly to our branch test-readthedocs and automatically generates new builds when new changes are made to this branch.

In order to make changes to the test-readthedocs branch, you can push your local fork changes directly to the branch without the review process needed for the develop branch. Do this with the following commands:

git checkout test-readthedocs
git pull origin <my_branch>
git push upstream test-readthedocs

You may also have to do a git fetch upstream first and ensure that you have a remote called upstream that points to spacetelescope/jwql (you can check this with git remote -v). If the regular command does not work, you may also have to try git push upstream -f test-readthedocs.

Once the ReadTheDocs pages build successfully, you can push your changes to the JWQL development branch.