Writing Documentation

High-quality, consistent documentation for the science code is one of the major goals of the Scikit-beam project. Hence, we describe our documentation procedures and rules here. For the scikit-beam core project we try to keep to these as closely as possible, while the standards for affiliated packages are somewhat looser. (These procedures and guidelines are still recommended for affiliated packages, as they encourage useful documentation, a characteristic often lacking in scientific software.)

Building the Documentation from source

For information about building the documentation from source, see the Building documentation section in the installation instructions.

Scikit-beam Documentation Rules and Guidelines

This section describes the standards for documentation format affiliated packages that must follow for consideration of integration into the core module, as well as the standard Scikit-beam docstring format.

• All documentation should be written use the Sphinx documentation tool.

• The template package will provide a recommended general structure for documentation. [TODO]

• Docstrings must be provided for all public classes, methods, and functions.

• Docstrings will be incorporated into the documentation using a version of numpydoc included with Scikit-beam, and should follow the Scikit-beam Docstring Rules. [TODO do we want to vendor numpydoc or use napolean?]

• Examples and/or tutorials are strongly encouraged for typical use-cases of a particular module or class.

• Any external package dependencies aside from NumPy, SciPy, or Matplotlib must be explicitly mentioned in the documentation.

• Configuration options using the scikit-beam.config mechanisms must be explicitly mentioned in the documentation. [TODO do we want to keep config]

The details of the docstring format are described on a separate page:

• Scikit-beam Docstring Rules
  • Overview
  • Docstring Standard
  • Sections
  • Documenting classes
    • Class docstring
    • Method docstrings
  • Documenting class instances
  • Documenting generators
  • Documenting constants
  • Documenting modules
  • Other points to keep in mind
  • Common reST concepts
  • Conclusion

numpydoc Extension

This extension (and some related extensions) are a port of the numpydoc extension written by the NumPy and SciPy, projects, with some tweaks for Scikit-beam. Its main purposes is to reprocess docstrings from code into a form sphinx understands. Generally, there’s no need to interact with it directly, as docstrings following the Scikit-beam Docstring Rules will be processed automatically.