Documenting CMakePP

For the most part documentation in the CMakePP project falls into one of two categories: API or narrative. The following sections describe the conventions associated with these types. Many of the conventions rely on reStructuredText (reST) so the reader may find this reST primer to be of use.

Note

I presume there’s actually a real computer science term for “narrative documentation”; however, my Google-ing did not manage to find it so I’m using “narrative documentation” as a placeholder for it. If you know the real term please open an issue on the CMakeDev repo so that the documentation can be updated.

API Documentation

API documentation tells you how to use a function, what a variable is for, or what a class models. Maintaining good API documentation is a key aspect of ensuring CMakePP is user-friendly. API documentation should not be used for prolonged discussions of the inner workings of a function or algorithm (such things should be documented, but fall under narrative documentation). For the most part source code associated with CMakePP is written in one of two languages, Python or CMake, and the following subsections describe the conventions for documenting APIs in each of those languages in detail.

Python

Python has community accepted standards for documentation. Those standards are available in the Python’s developer guide. The main points are:

  • No more than 80 characters on a line

  • Indents are 3 spaces, not 4, and not tabs

  • Comments use restructured text (reST)

The standard does not however strictly specify the contents of the documentation or the format of the comments. At the moment, Sphinx is the de facto tool for creating Python documentation from comments and we thus choose to follow Sphinx’s standards.

To summarize this style, positional arguments are documented like:

:param arg1: description of arg2
:type arg1: type of arg1

variadic arguments like:

:param *args: description of the variadic arguments
:type *args: The type(s) of the variadic arguments

and returns are documented like:

:return: description of what is returned
:rtype: The type of the returned object

It should be noted that Python functions which return multiple values do so in a tuple, so the correct documentation for a multiple-return value function is:

def my_mr_fxn():
   """ Function which returns multiple values.

   :return: Two of the most overused values in documentation.
   :rtype: tuple(int, str)
   """

   return 42, 'Hello World'

I have not been able to find a standardized way of documenting kwargs; however, one “hack” I’ve come across that produces something that looks like the other aspects of the function’s API is:

:param **kwargs: See below

:Keyword Arguments:
   * *kwarg1* (``type``) -- description
   * *kwarg2* (``type``) -- description

basically you have to manually make the kwargs section match the sections auto-generated by Sphinx.

CMake

CMake documentation uses the CMakeDoc tool developed by the CMakePP project. This tool looks for specially prefixed CMake comments (line comments that start with ## and block comments that start with #[[[) and extracts the contents verbatim as documentation of the API/variable that the comment immediately proceeds. The contents of the comment are assumed to be reST and it is assumed that the documentation will be built using Sphinx. Therefore, we adopt the same reST standards as we do for Python with the following exceptions.

Whereas global variables are frowned upon in Python they are unfortunately somewhat common in CMake. To document the global variables your function uses the syntax is:

:var GLOBAL_VARIABLE: Description of global variable
:vartype GLOBAL_VARIABLE: type of the value stored in the global variable

Narrative Documentation

Narrative documentation is like the page you are currently reading. It is only loosely tied to a particular piece of code. Narrative documentation is meant for providing overviews, background information, implementation details, etc. Narrative documentation is built with Sphinx and is written using Sphinx-flavored reST. Consequentially many of the reST conventions from the API Documentation section carry over.

Compared to writing reST API documentation the biggest difference when writing narrative documentation is that narrative documentation is typically partitioned into parts, chapters, sections, etc. While reST doesn’t particularly care what characters you use to distinguish between headings for parts, chapters, sections, etc. it is very common practice (stemming from Python’s documentation conventions) to obey:

  • # with overline for part headings

    • We also use this for the package name on the main index.rst

  • * with overline for chapter headings

  • = for sections

  • - for subsections

  • ^ for subsubsections

  • " for paragraphs

  • and you should seriously reevaluate your documentation if you need anything beyond that…

The distinction between what constitutes a part, chapter, etc. is a bit fuzzy, but the general idea is that as you nest titles you rotate through the various characters. Typically what this means is that you’ll use # for titles on index.rst pages, * for titles of pages included from index.rst pages, and =, -, and ^ respectively for sections, subsections, and subsubsections in the page included from the index.rst file.