Documentation ============= All submitted code should be documented. Documentation should use numpydoc style docstrings. Since Napoleon is currently used to render the docstrings, the `Napoleon example documentation`_ is the main reference to use, and there is additional information in the `numpydoc documentation`_. .. _Napoleon example documentation: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_numpy.html#example-numpy-style-python-docstrings .. _numpydoc documentation: https://numpydoc.readthedocs.io/en/latest/format.html Module level docstrings with a summary of what the code does, and docstrings for all public functions are a **minimum requirement**. For public functions, all parameters and return values should be documented, along with a summary of what the function does. Docstrings should comply with the conventions outlined in `PEP 257`_. .. _PEP 257: https://peps.python.org/pep-0257/ .. note:: The first line of the docstring of a public function should be written in the imperative mood (e.g. "Do this", "Return that"), not as a description (e.g. "Does this", "Returns that"). The documentation for the core libraries (ANTS and UG-ANTS) and ug-ancillary-file-science are built as part of rose-stem tests and via GitHub actions when a pull request is opened or modified. Warnings are treated as errors - this means all sphinx warnings need to be fixed for core documentation. For ancillary-file-science code, docstrings are expected to be included at the same level as for core code. They can be a "best effort" approximation of numpydoc format, since the ancillary-file-science docs are not currently built as part of the ancillary-file-science rose-stem. Additional documentation should be in plain text (i.e. ``.txt``) files for short additional notes (e.g. README files), or in reStructuredText (i.e. ``.rst``) files for additional information that should be in the published documentation. If in doubt, ``.rst`` is preferred. Documentation should be as clear as possible to aid undertanding. Some external links in the documentation are not clear where they go or that they are external. When updating exetrnal links or adding new links, it should be made clear where the links lead. Sphinx details -------------- Links to Python code in either docstrings or standalone ``.rst`` files should use the relevant role from the sphinx `Python domain `_ (i.e. ``:class:``, ``:func:`` etc). Links to other parts of ANTS documentation should use the ``:doc:`` role, and relative links rather than absolute links - e.g. ``:doc:`/introduction``` instead of ``https://metoffice.github.io/ANTS/introduction.html``. This ensures that the documentation build in a working copy only depends on that working copy, and not on the published documentation. Links to other projects' documentation can be achieved using `intersphinx mapping `_. References to script options e.g. ``--option`` made in ``.rst`` files should be wrapped in code markup `````` tags e.g.:: ``--begin`` Section heading markers should follow the `python development guidelines `_, i.e.: .. code-block:: none * with overline, for chapters = for sections - for subsections ^ for subsubsections Sphinx codeblocks ----------------- By default, all sphinx codeblocks are assumed to be `python interactive `_ sessions. To override this for a document, use a `highlight directive `_. To override for a single code block, use a `code-block directive `_.