Documentation upgrade

[j-emberton]

Work in progress

Dementpy currently lacks a structured approach to creating and maintaining documentation.

Documentation may be aimed at package users, package developers, or a combination of both. Each group will require slightly different presentation depending on what they need from the Dementpy repo/code.

Below, several strategies that could be used to create and maintain documentation for this project are presented. Each suggested strategy provides an example of a repo where this is the chosen strategy (where possible) as well as a description of how to implement it and the pros and cons of that approach.

Python Docstrings

Simplest approach to creating code documentation. Docstrings should follow a standard such as Google style, Numpy style or restructured text reST (or Sphinx style).

At a minimum, the docstring should contain:

• summary of arguments
• summary of return values
• summary of any exceptions raised
• type descriptions for inputs and outputs

Advantages

• simple to generate and maintain
• Information is inline with the relevant code - good for developers
• no 3rd party dependencies

Disadavantages

• Not convenient for code users rather than developers
• Code is highly linked to modules, classes and functions. More difficult to express narrative or overarching principles.
• No automatic linking of bibliography and docstrings
• In fact all linking is static and dumb - no clickable links or autoupdating

Github Docs

Github supports the creation of markdown (.md) docs with support for a variety of useful functionality Github docs. Very often, repos will only use markdown for the Readme, however with hyperlinks a well structured and connected set of documents forming documentation for the code can be created.

Advantages

• Simple familiar, style and formatting syntax
• Opportunity for more complex expression - tables, mathematical formulae, auto-linked references
• No third party dependencies beyond Github
• Can be integrated with GitHub Pages wiki style interface

Disadvantages

• Over and above docstrings - additional maintenance burden
• Less feature rich and powerful than alternatives
• Less convenient for robust versioning and release control
• No simple integration with python docstrings

Github pages

Github hosted website generated from repo markdown content. This repo has cerated a GitHub Pages site as its main documentation Bootstrap Docs.

More information on GitHub Pages is available here. Github pages uses Jekyll to build the site and there are plugins to incorporate python docstrings.

Requires paid GitHub subscription

Advantages

• Close integration with Github repo - less reliance on third party plugins or services
• Can support a cohesive, professional website aimed at both developers and users

Disadvantages

• Requires paid subscription (Minimum teams level)
• Less experience with this publishing model/workflow

Sphinx and auto doc

Sphinx is a powerful, open source python package for building and publishing html from a variety of sources. It has a large number of potential integrations which allow a high degree of customisability and flexibility.