Building Docs¶

One of the most important aspects of writing good software is documentation. This website is generated automatically from the source files in dnppy/docs/source with Sphinx and graphviz. You can click on the “View page source” button in the top right corner to see the source code used to build this web page! Neat!

Documentation source

These documentation pages are made into pretty html and css from a couple of different sources. The first of which are .rst files typed with reStructuredText markup. These files are all found in the docs/source folder, and the structure looks something like this:

/source
    /_static
        <static content such as images>
    /dev_pages
        <rst files directed towards developers>
    /modules
        <one rst file for each module of dnppy>
    /trub
        <rst files directed at help and reference>
    design.rst
    index.rst
    install.rst
    modulesum.rst
    overview.rst

Documenting new additions¶

A new function or class

When you add a new function or class to dnppy, you will have to add a couple lines to that modules .rst file in the modules folder. These few lines allow sphinx to parse the docstrings and arguments of that function or class definition and create help pages and add it to the index so users can find it in the search bar.

Its easiest to check the source for these very doc pages.

Take a quick look at the core module help page

Now look at the .rst file used to generate the core module help page. Notice that the entire “Code Help” section consists of just a few repeated calls to the automodule plugin.

Back on the help page, notice that there is a small “source” button next to every function description.

Now check out the source code for the create_outname function.

You will notice in the source code for the core module help page a statement that looks like:

.. automodule:: dnppy.core.create_outname
    :members:

Which invokes the automodule chain and parses the docstrings of the create_outname function. In order for the parser to successfully produce the pretty outputs, the docstrings should follow syntax such as that listed below.

def foo(self, x, y):
    """
    Description of function here

    :param int x: parameter x is an integer and does ....
    :param int y: parameter y is an integer and does ....
    :rtype: returns int
    """

For the code above defining a dummy function called foo, the auto documentation tool chain will generate this:

foo(self, x, y)

Description of function here

Parameters:	x (int) – parameter x is an integer and does... y (int) – parameter y is an integer and does...
Return type:	returns int

Ensure you write descriptive docstrings for your functions, and comment well, which are things you should definitely be doing anyway right? It is worth noting that PyCharm, our recommended IDE, automatically provides tooltips to encourage the user to document to this standard as quickly and easily as possible.

A new module

When adding a new module to dnppy, you should create a new .rst file in docs/source/modules with an “Examples” and a “Code Help” section in the same way the other modules of dnppy are set up.

Checking the docs¶

Once you’ve made any kind of major edit to dnppy, we have a quick and dirty script located at dev/sphinx_build.py that you can run to create a local copy of this website in docs/build. This script will install all the required modules and run a sphinx build on your local repository. Be sure to fix any errors or warnings that sphinx may throw. You can then view the updated website by opening up docs/build/index.html in your browser. This is exactly how the live version of the website will look after you push your commits. A service at Travis-CI will perform exactly the same process on their server, then push the results to the gh-pages branch. In the event that a “build failed” badge pops up on the dnppy homepage, you will want to log in to Travis-CI and view the log of that build to see what might have gone wrong.

Note

this docs/build folder is intentionally added to the .gitignore to prevent the master branch commits from getting cluttered with changes that do not need to be tracked. Otherwise, every minor code change would be accompanied by dozens of trivial automatic changes to the html code of these doc pages.

Building the docs¶

Building the docs used to require keeping a local copy of the repository permanently set to use the gh-pages branch and follow the work-flows that can be found in the section below. However, I’m pleased to inform you that you do not need to do any special commits or setup of your development environment to automatically update these doc pages! All doc pages are automatically rebuilt every time someone commits to dnppy!

For reference, we used the following resources to set ourselves up.

documenting your project with sphinx

A custom built travis-sphinx tool

https://github.com/NASA-DEVELOP/dnppy/pull/55

https://github.com/NASA-DEVELOP/dnppy/pull/57

This process automatically tells Travis-CI to rebuild the documentation pages every time a commit is pushed to the any branch of dnppy. This is done according to the .travis.yml file. It typically takes less than 2 minutes for the changes to go live.