cloudmarker / cloudmarker / 101 / 3

84%

master: 84%

push

travis-ci-com

Generate API documentation

This change generates automatic API documentation from the docstrings in
the project package. Here is a list of changes done:

  - The `docs` target in `Makefile` has been updated with a
    `sphinx-apidoc` command that automatically reads the Python source
    files and generates the Sphinx source files necessary to create API
    documentation.

  - The docstrings in the Python source code have been improved to look
    good in the generated documentation.

  - Example Python interactive sessions (also known as doctest format
    examples) have been added wherever applicable. These doctest format
    examples are recognized by Sphinx documentation generator and
    rendered appropriately in the generated documentation.

  - Since we now have doctest format examples the `test` target in
    `Makefile` has been updated to run Python's `doctest` utility to
    test these examples.

  - A `__init__.py` file has been added for every subpackage. This
    allows us to write package level docstrings. It also helps
    `sphinx-apidoc` to discover all subpackages without having to use
    its `--implicit-namespaces` option.

    We don't have a need for splitting our project package across
    multiple independent directories at this time, so we don't need
    implicit namespaces right now.

57 of 57 branches covered (100.0%)

Branch coverage included in aggregate %.

303 of 303 relevant lines covered (100.0%)

1.0 hits per line