Building and Writing Docs¶

One of the most important aspects of writing good software is clarity and readability. We hope as other developers find themselves tasked with improving this tool, documentation is also held to as high a standard as we do.

Building the docs

See Updating the Site for a guide on building docs for the website

Contributing to the Docs

The CALIPSO docs page uses the sphinx.ext.autodoc extensions to pull reStructuredText docstrings from source and create doc pages from them. inside the doc folder is the location of all code documentation, split up into three packages: general , polygon , and tools. If you’ve created a new module and would like to have it added to the docs(the answer should always be yes!), place a .rst file with the module name in the corresponding package folder.

Lets run through the scenario you have a new module, foobar.py, you wrote inside tools. It’s recommended you don’t procrastinate adding your new modules to the docs to avoid rushing. Here’s an example of what your file may look like, note the docstrings and the reStruct markdown used

########################
#    foobar.py
#    04/07/2015
#    @author: me
########################

class Foo(object):
"""
Manages certain functionality within the package, description of class utility

:param str title: Title of window
:param root: Root of application
"""

    def __init__(self, title, root):
        self.title = title
        self.root = root

    def does_stuff(self):
    """
    Does plenty of stuff

    :rtype: int
    """
        return 0

 def related_to_foo(foobar):
 """
 Takes a passed ``Foo`` object and does something with the object

 :param Foo foobar: A Foo object
 """
     # .....

Now when adding foobar.py, you’ll reference the package it is located in (tools in this case) and place a .rst file in the correct location.:

> cd vocal
> cd docs
> cd doc
> tree
.
|-- general
|   |-- attributes.rst
|   |-- calipso.rst
|   |-- consts.rst
|   |-- db.rst
|   |-- general.rst
|   |-- import.rst
|   `-- toolswindow.rst
|-- modules.rst
|-- polygon
|   |-- drawer.rst
|   |-- list.rst
|   |-- polygon.rst
|   `-- reader.rst
`-- tools
    |-- navigationtoolbar2calipso.rst
    |-- toggleablebutton.rst
    |-- tools.rst
    |-- tooltip.rst
    `-- treelistbox.rst
 > cd tools
 > vim foobar.rst

Inside foobar.rst simply specify the title and a couple auto doc lines.:

==============
Foo
==============

.. inheritance-diagram:: tools.foobar

.. automodule:: tools.foobar
   :members:

The :members: specifier tells autodoc to also include the class methods, which we also want to display.

And thats all! The documentation tool will create an inheritance diagram of all classes using graphiz, then run through the module specified and document any classes or functions available. Ensure you are using docstrings and are following the coding conventions. If you ever run into problems not knowing how to use sphinx, every doc page has a view source option you can refer to for help, and feel free to contact us on the contact page.