Document

To create documentation for your software package, execute these steps:

1. First, create the code. For each unit in the code (e.g., each function), you must add documentation that briefly describes the unit. Specifically, you should add docstrings and code comments. There are several guidelines to write docstrings and comments such as PEP8 and Google style guide. In our group, we follow Google style guide. A sample function code fragment with docstrings and code comments is shown below:

class HammingDistance(SequenceSimilarityMeasure):

"""

Computes Hamming distance. The Hamming distance between two

strings of equal length is the number of positions at which the

corresponding symbols are different. Thus, it measures the

minimum number of substitutions required to change one string into

the other, or the minimum number of errors that could have transformed

one string into the other.

"""

def __init__(self):

super(HammingDistance, self).__init__()

def get_raw_score(self, string1, string2):

"""Computes the raw hamming distance between two strings.

Args:

string1,string2 (str): Input strings.

Returns: Hamming distance (int).

Raises: TypeError : If the inputs are not strings or if one of the inputs is None.

ValueError : If the input strings are not of same length.

Examples:

>>> hd = HammingDistance()

>>> hd.get_raw_score('', '')

>>> hd.get_raw_score('alex', 'john')

>>> hd.get_raw_score(' ', 'a') 1

>>> hd.get_raw_score('JOHN', 'john')

"""

2. Change into 'docs' directory from project root.

3. Inside this directory, you will create a file 'config.py' and create a set of RST files (more about 'RST' format is explained below). Specifically, this directory will contain the RST files for the following:

+ API References (e.g. function signatures)

- will contain multiple RST files, one for each module.

+ Installation

+ Tutorials

+ How to contribute

+ FAQ

+ Index

The documentation is written in reStructuredText (RST) format, which is almost like writing in plain English, and built using Sphinx. The Sphinx documentation has an excellent introduction to resStructuredText format. Review the Sphinx docs to perform more complex changes to the documentation as well. Files written in this format will have '.rst' extension. The reST language allows you to write documentation quickly and comprehensively (e.g., it is easier to write code snippets in reST than in HTML). Then you can compile it to HTML. So reST is sort of like LaTeX.

When you create documentation for the first time, run the following command (from docs directory) to create configuration file 'conf.py' and 'index.rst' file:

sphinx-quickstart

This command will interactively ask a set of questions (such as project name, version etc.). Make sure you answer them correctly. If you use Google style guide for writing comments, then replace the 'extensions' in 'conf.py' with the following lines:

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'IPython.sphinxext.ipython_console_highlighting', 'IPython.sphinxext.ipython_directive' ]

Add the following lines after extensions in 'conf.py':

napoleon_google_docstring = True

napoleon_numpy_docstring = False

napoleon_include_private_with_doc = False

napoleon_include_special_with_doc = True

napoleon_use_admonition_for_examples = False

napoleon_use_admonition_for_notes = False

napoleon_use_admonition_for_references = False

napoleon_use_ivar = False

napoleon_use_param = True

napoleon_use_rtype = True

Further, uncomment and update the following lines in 'conf.py':

import

sys

.path.insert(0, os.path.abspath('../'))

We now explain how to create/update the RST files and what they should contain.

API References

a. Create '<module name>.rst' (if it does not exist) for each module in the code. In this file, add the following:

<module-name>

-----------

.. automodule:: <package-name>.<module-name>

In the above, package-name and module-name must be replaced accordingly. The above code will generate all the function signatures in the module, when the RST files are compiled.

b. In the 'index.rst' file, include the names of those modules whose function signatures needed to be included.

.. toctree::

:maxdepth

<module-name 1>

...

<module-name n>

In the above, <module-name 1>, .., <module-name n> must be replaced accordingly. You can find a sample 'index.rst' file here.

Installation

a. First, create 'installation.rst' file (if it does not exist) in the 'docs' directory.

b. Next, inside this file, explain the installation procedure. Specifically, it should contain the following information:

(i) Mention which versions of Python the package supports.

(ii) Installation instructions such as installing from source and PyPI, across different operating systems.

(iii) Mention package dependencies along with their version numbers.

You can find a sample installation file here

Tutorials

a. Create 'tutorial.rst' (if it does not exist) in the 'docs' directory.

b. Inside this file, provide a brief tutorial for the package. Specifically, it should describe how to execute a simple workflow. For instance, for an entity matching package, we should specify how to execute a simple end-to-end workflow involving steps such as loading, cleaning, blocking and matching. You can find a sample tutorial file here.

How to contribute

a) Create 'contributing.rst' file (if it does not exist) in the 'docs' directory.

b) Inside this file, describe how other collaborators can contribute to the package.

You can find a sample "how to contribute" file here.

FAQ

a) Create 'faq.rst' file (if it does not exist) in the 'docs' directory.

b) Inside this file, add frequently asked questions about the package, based on user queries.

4. Once you have created the RST files, you should then convert them into a set of HTML pages using the following command (from 'docs' directory):

make clean html

Note: If you want to create a single page HTML, execute the following command from 'docs' directory

make clean singlehtml

You can then show these pages on some website. This will provide browsable documentation for your software package.browsable documentation for your software package.

Misc Things to Pay Attention To:

The documentation on the website can conceptually be divided into a "user manual" and a "developer manual". If there is not much to include in the developer manual then it is best to just merge it into the user manual. Otherwise, one can create two separate documents.
It is important to have a single HTML page version of the entire website, to allow users to very quickly do keyword search to find information about a particular term.
If you want to be really nice, you can also create PDF versions of the information on the HTML pages. In the long run, this can create a problem because if you update the RST files, thus the HTML pages, then you would need to update the PDF files too.
Further, it is important to decide on where to host the website?. There are at least three possible candidates: (a) readthedocs.org, (b) github.io, and (c) a private Web server. In our group, we currently use github.io.

Resources

Page updated

Google Sites

Report abuse