Documentation

Requirements

All parts of the TraP should be documented both at a level that is suitable for end users using the pipeline and for developers who wish to understand, fix and extend the codebase. Broadly, that distinction reflects the structure of this manual. Note that we expect that developers will benefit from both automatically generated API documentation making use of appropriate docstrings in the code, and higher-level descriptions of system architecture and functionality.

All new features or changes must be accompanied by appropriate documentation. Reviewers are required to check that pull requests are well documented before merging. See the material on Code Review for details.

Technical details

Documentation is written using Sphinx. The documentation for the HEAD of the master branch of the transientskp/tkp repository is, together with the documentation for all released versions, is automatically build every night and put online at http://docs.transientskp.org/.

Docstrings should make use of the “Napoleon” syntax. For example:

Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The :class:`FileStorage` instance to wrap
    temporary (bool): Whether or not to delete the file when the File
       instance is destructed

Returns:
    BufferedFileStorage: A buffered writable file descriptor