Updating the External Resource#

In order for our documentation to be visible, we have to generate a new set of files with our new changes. This document will walk through the steps to do so.

Adding New Classes to the Sphinx Structure#

Before we actually build the documentation, we need to update the structure of our Sphinx configuration. As an example, let’s say that we created a new class NewDynamicModel.py in the dynamics/ directory of Scarabaeus. In order to tell Sphinx to include all of the documentation that we’ve written inside of it, we need to do two things:

  1. Create an autodocumentation .rst file.

  2. Add that file to the Library Reference toctree.

Make the Autodoc .rst File#

First, we’ll make the .rst file. We’ll open the docs\online_documentation\sphinx_files\scb_library\ directory. This is where all of the .rst’s that provide directives to document our classes live. You’ll notice that it’s organized with the same structure as the Scarabaeus directory is. Since our new class is under the dynamics/ directory, we’ll navigate into the scb_library\dynamics_rsts\ directory and place a new file newdynamicmodel.rst. The files in these directories correspond to their class names with no capitalization and no spaces.

Inside our new .rst, we’ll place:

---------------
NewDynamicModel
---------------
.. autoclass:: scarabaeus.NewDynamicModel
    :members:
    :undoc-members:
    :show-inheritance:
    :inherited-members:

Firstly, we have the header, which denotes the name of our class in the documentation. It’s important that the “-” above and below are the same length as the header itself. Sphinx will raise an error if it’s not. Below this header, we have the autoclass directive. We tell it which class we want it to document in the same line that we call it. Then, indented below, we have a few more sub directives to pass to autoclass. These just ensure that we’re documenting everything we need to and with the correct formatting.

With this file, Sphinx now knows how we would like for it to build the documentation for our new class.

Add to the Toctree#

Now we need to tell Sphinx where we want it to build the documentation for our new class. To do this, we’ll need to place the .rst we made above into the toctree. The toctree is how Sphinx structures all of its links. If we open the file docs\online_documentation\sphinx_files\scb_library\lib_ref.rst we’ll see multiple toctrees, each corresponding to a folder in Scarabaeus.

We’ll find the “Dynamics” section and place the path to our new .rst in the same location it’s placed in the folder:

-----------------------
:blue:`Dynamics Module`
-----------------------
The classes described in this module provide functionality for modeling the dynamic environment
acting on a spacecraft. This includes modeling of Keplerian accelerations, 3rd body perturbations,
solar radiation pressure, higher-order fidelity gravitational modeling (spherical harmonics, polyhedral),
and finite burn modeling.

.. toctree::
    :maxdepth: 1
    :numbered:
    :caption: All Dynamics Classes:

    ./dynamics_rsts/cannonballsrp.rst
    ./dynamics_rsts/dynamicmodel.rst
    ./dynamics_rsts/finiteburn.rst
    ./dynamics_rsts/forcemodel.rst
    ./dynamics_rsts/impulsiveburn.rst
    ./dynamics_rsts/newdynamicmodel.rst
    ./dynamics_rsts/nplatesrp.rst
    ./dynamics_rsts/pointmassgravity.rst
    ./dynamics_rsts/sphericalharmonicsgravity.rst
    ./dynamics_rsts/threebodygravity.rst

Now that we’ve told Sphinx how and where to build docs for our new class, we just need to tell Sphinx to actually build, which we’ll do in the next section.

Note

If we only made changes to existing classes, not an entirely new one, we will not need to perform any of this, since Sphinx already has the information it needs to find any changes we made and include them in the new version of our documentation.

Building the HTML’s#

Now that we’ve told Sphinx everything that it needs to include in our updated version of the docs, we need to tell it to build the new version. In our terminal, we’ll run:

sphinx-build -M html docs/online_documentation/sphinx_files docs/online_documentation/_build

This might take a second since we have a lot of information to parse through. There will most likely be a few warnings, but if it completes and we see the print out:

The HTML pages are in docs\online_documentation\_build\html.

Then we know that our docs have generated. Navigate to docs\online_documentation\_build\html and open index.html in your browser. This will take you to the front page of the documentation, and from there you can perform final checks, as outlined in the next section.

Final Checks#

The procedure to follow before you publish the new version is as follows:

  1. Ensure that the “About Scarabaeus” page is up to date. Are all the current members correct? Missions flown and publications?

  2. If you edited any articles in the documentation, make sure that the “last edited by” section is correct.

  3. Check the pages for all of the classes you updated or created and ensure that all of your additions/removals have been included in the update and are rendering correctly.

If all of these checks pass, then the documentation is ready to be published.

Updating the Online Version#

Will need to show how to push updates to the online version. Not sure exactly how we’re doing that yet, so this page section be left blank for now.