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 exoctk/docs/source/ directory named <module_name>.rst. This file should look something like this:

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

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

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

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 exoctk/docs/
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 the upstream/update-docs branch, which is a branch used specifically for testing ReadTheDocs. That way, you can generate these pages before pushing your changes to the develop branch of exoctk.

To see how things look on ReadTheDocs, you'll need to make a ReadTheDocs account. Ask someone on the team (perhaps Matthew or Joe) to add you to the ExoCTK ReadTheDocs project. Now, on your dashboard, you'll see the ExoCTK 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 update-docs, which corresponds directly to our branch update-docs and automatically generates new builds when new changes are made to this branch.

In order to make changes to the update-docs 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 update-docs
git pull origin <my_branch>
git push upstream update-docs

You may also have to do a git fetch upstream first and ensure that you have a remote called upstream that points to ExoCTK/exoctk (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 update-docs.

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