Style Guide

This section describes the coding and documentation style used in MCL. These styles leverage community standards and should be familiar to pythonists, pythoneers, pythonistas’ and abusers of the word idiomatic. For experienced Python developers, this section outlines how the community standards have been used (and abused) in MCL. A brief read-through aught to be sufficient. For new Python users, this section serves a crash-course in Python coding and documentation convention. Further detail is provided externally via links.

Code

The coding convention adopted in the standard library of the main Python distribution is defined in PEP8: the Style Guide for Python Code. PEP8 warns:

A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is most important.

In short, when writing new code, take a few minutes to determine the style of the surrounding code. When contributing to the code base, attempt to ‘blend in’ and be consistent with its style.

Python is the main scripting language used at Google. The Google Python Style Guide largely complements PEP8. When in doubt, adopt the style of the surrounding code or defer to PEP8.

Help You Help Yourself

Your favourite IDE or editor can help you adhere to the PEP8 guidelines. This can be done by configuring a code checking tool to check your Python code. The tool pep8.py checks python code against some of the style conventions in PEP8. You can install, upgrade or uninstall pep8.py with these commands:

pip install pep8
pip install --upgrade pep8
pip uninstall pep8

The Pylint tool is a source-code quality and bug checker. Pylint provides:

  • checking line-code’s length,
  • checking if variable names are well-formed according to your coding standard
  • checking if imported modules are used

On Debian-based systems Pylint can be installed using:

sudo apt-get install pylint

Other (overlapping) code checking tools include flake8, pyflakes and pychecker.

Documentation

Docstrings

Python emphasises documentation through the use of docstrings:

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition [1].

Properly documenting code not only makes the source more accessible to other programmers but it enables software such as the docstring processing system, Docutils and Sphinx to parse the documentation.

Sphinx

MCL documentation is generated using Sphinx. Sphinx uses reStructuredText as its markup language. Many of Sphinx‘s strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite - the Docutils [2]. Due to Sphinx‘s reliance on Docutils, the quality of Sphinx documentation depends on the completeness of the project’s docstrings.

MCL uses Google style docstrings. A comprehensive example of Google style docstrings can be found here. Support for Google style docstrings in Sphinx is provided through the Napoleon extension.

Warning

As of Sphinx 1.3, the napoleon extension will come packaged with Sphinx under sphinx.ext.napoleon. The sphinxcontrib.napoleon extension will continue to work with Sphinx <= 1.2.

Since Sphinx relies on reStructuredText, it is worth learning the markup. Examples are provided in:

API documentation is easier to traverse and more powerful at communicating if function, class, method or attribute definitions are linked when they are referenced. Sphinx provides markup allowing these constructs to be hyperlinked when they are referenced in the documentation.

Structure

sphinx-apidoc is a tool for automatic generation of Sphinx sources that, using the autodoc extension, document a whole package in the style of other automatic API documentation tools.

Although sphinx-apidoc provides an ‘automagic’ mechanism for documentation, it is difficult to override its behaviour and format the look and feel of the documentation it produces. To allow for more control over the presentation of the MCL documentation, the structure is specified explicitly. Although this approach requires more supervision, the ‘heavy lifting’ is still done by autodoc and autosummary.

The Sphinx structure is set out in the doc/source directory. The master document, doc/source/index.rst, serves as a welcome page and contains the root of the “table of contents tree” (or toctree) - linking to additional documentation. The Sphinx configuration can be found in doc/source/conf.py.

Learning how to extend the documentation is best done by studying the structure defined in the doc/source directory. There are two points within the documentation that require maintenance. The master document, doc/source/index.rst, needs to be updated every time a new package is created. If new modules are added to an existing package, the package __init__.py file must be updated to include the new module. Modifications to existing modules do not require any maintenance - these changes will be handled by autodoc and autosummary.

Footnotes

[1]PEP 257: Docstring Conventions
[2]Sphinx: Python Documentation Generator