The Docstring system

A docstring is a string literal that occurs as the first statement in a package, module or function (method). These structures (Python objects) can be properly commented and the documentation processed/retrieved by tools such as Sphinx and help().

1. Example: commenting a class



In [ ]:

    
class ClassExample():
    '''This first line is a summary of this class. \
There must be ONLY one logical line in this overview.
    
    However (notice that must be an empty line between the summary and this
    block of text), the rest of this doctrings can be placed in several lines.
    These lines usually provides extended information about the functionality
    of the class. The last line of the docstring should contain only
    three simple quotation marks (as follows).
    '''
    
    x = 1
    
    def __init__(self):
        '''A summary about the constructor. This is an example of a one-line docstring.'''
        print(self.x)
        
    def set(self, x):
        '''A summary about \"set\".
        
        Arguments:
            x: an integer that ... bla, bla, bla.
            (Notice the indentation of this/these lines)
            
        Returns:
            Nothing.
        '''
        self.x = x
        
    def get(self):
        '''A summary about \"get\".
        
        Arguments:
            None.
            
        Returns:
            The value of \"x\".
        '''
        return self.x

2. Using `help()`

Getting help for a whole class.



In [ ]:

    
help(ClassExample)

A different way of getting help (in Ipython):



In [ ]:

    
ClassExample?

Getting help for a single member function:



In [ ]:

    
help(ClassExample.get)

help() only prints the __doc__ variable:

Any function, class or module starting with a string literal has a non-empty __doc__ attribute which can be printed to get information.



In [ ]:

    
print(ClassExample.get.__doc__)



In [ ]:

    
print(type(ClassExample.get.__doc__))

The same queries can be carried out with an instance.



In [ ]:

    
a = ClassExample()



In [ ]:

    
help(a)



In [ ]:

    
help(a.set)



In [ ]:

    
print(a.__doc__)



In [ ]:

    
print(a.get.__doc__)

3. Documenting Your Project Using Sphinx

3.1 Installation

$ pip install Sphinx                # Necessary only once

3.2 Configuration of the project (example)

$ pwd
/Users/vruiz/YAPT

$ sphinx-quickstart                 # Necessary only once by project

> Root path for the documentation [.]: <enter>
> Separate source and build directories (y/n) [n]: <enter>
> Name prefix for templates and static dir [_]: <enter>
**********************************************
> Project name: My ClassExample Python Project
> Author name(s): Your Name Here
> Project version []: 1.0
**********************************************
> Project release [1.0]: <enter>
> Project language [en]: <enter>
> Source file suffix [.rst]: <enter>
> Name of your master document (without suffix) [index]: <enter>
> Do you want to use the epub builder (y/n) [n]: <enter>
********************************************************************
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
********************************************************************
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: <enter>
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: <enter>
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: <enter>
> coverage: checks for documentation coverage (y/n) [n]: <enter>
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: <enter>
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: <enter>
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: <enter>
> viewcode: include links to the source code of documented Python objects (y/n) [n]: <enter>
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: <enter>
> Create Makefile? (y/n) [y]: <enter>
*******************************************
> Create Windows command file? (y/n) [y]: n
*******************************************

$ # Only to see how to add new (sub-)pages ...
$ cat > extra_documentation.rst << EOF
Extra Documentation
===================

Your extra documentation which has not been included in the code could
be placed here.
EOF

$ # You need to select which modules will be processed. 
$ cat > code.rst << EOF
Code Documentation
==================

.. automodule:: ClassExample
    :members:
EOF

$ # Your index.rst file should show like (use a text editor):
$ cat index.rst
.. My ClassExample Python Project documentation master file, created by
   sphinx-quickstart on Thu Dec  8 17:46:01 2016.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to My ClassExample Python Project's documentation!
==========================================================

Testing Docstrings and Sphinx!

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   code
   extra_documentation

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

3.3 Compilation of the documentation

Makes sure to include the path to your modules in in the sys.path in the conf.py file previously generated.

$ make clean
$ make html

3.4 Seeing the results

$ firefox _build/html/index.html