Skip to content

Latest commit

 

History

History
244 lines (174 loc) · 8.94 KB

README.md

File metadata and controls

244 lines (174 loc) · 8.94 KB

scikit-bio documentation

This guide contains instructions for building the scikit-bio documentation, as well as guidelines for contributing to the documentation.

Note: If you're only interested in viewing the scikit-bio documentation, visit scikit-bio.org.

Building the documentation

To build the documentation, you'll need the following Python packages installed:

An easy way to install the dependencies is via pip:

pip install Sphinx sphinx-bootstrap-theme

Finally, you will need to install scikit-bio.

Important: The documentation will be built for whatever version of scikit-bio is currently installed on your system (i.e., the version imported by import skbio). This may not match the code located in this repository. You will need to either install this version of scikit-bio somewhere (e.g., in a virtualenv) or point your PYTHONPATH environment variable to this code, before building the documentation.

To build the documentation, assuming you are at the top-level scikit-bio directory:

cd doc
make html

The built HTML documentation will be at build/html/index.html.

Contributing to the documentation

If you would like to contribute to the documentation, whether by adding something entirely new or by modifying existing documentation, please first review our scikit-bio contribution guide.

Before submitting your changes, ensure that the documentation builds without any errors or warnings, and that there are no broken links:

make clean
make html
make linkcheck

Documentation guidelines

Most of scikit-bio's API documentation is automatically generated from docstrings. The advantage to this approach is that users can access the documentation in an interactive Python session or from our website as HTML. Other output forms are also possible, such as PDF.

scikit-bio docstrings follow the numpydoc conventions. This ensures that the docstrings are easily readable both from the interpreter and HTML, PDF, etc. Please read the numpydoc guidelines before continuing.

Documenting a module in scikit-bio

In addition to following the numpydoc conventions for docstrings, we have a few more conventions that will ensure your documentation is correctly built and linked within our website, and that it maintains consistency with the rest of the scikit-bio docs.

The easiest way to get started with documenting your code is to look at the docstrings in existing scikit-bio modules. A couple of modules to start with are skbio.core.sequence and skbio.core.distance. Go ahead and look through those now. We've structured our docs in a similar way to SciPy's documentation, so that may be another good place to look for examples.

We'll take a top-down approach by discussing how to document a new module that you'd like to add to scikit-bio (let's call it skbio/core/example.py).

Module docstring

The first thing you'll need to add is a docstring for the module. The docstring should be the first thing in the file following the #! line. It should start with a title for the module:

#!/usr/bin/env python
"""
Documentation examples (:mod:`skbio.core.example`)
==================================================

It is important to include the :mod: Sphinx directive in the title, as this title will be included in the table of contents. Also make sure that the title underline is the same length as the title.

We also need to include another Sphinx directive below this:

.. currentmodule:: skbio.core.example

This directive tells Sphinx that other classes, functions, etc. that we will reference are located in the skbio.core.example module.

Next, include a more detailed description of the module. For example:

This module consists of several example classes and functions to illustrate
the scikit-bio documentation system.

Following that, list any classes, functions, and exceptions that you'd like documentation generated for. Note that you do not need to include every single class, function, or exception that is defined in the module. Also, you do not need to list class methods, as those will be automatically included in the generated class documentation. Only include objects that should be exposed as part of the public API.

For example:

Classes
-------

.. autosummary::
   :toctree: generated/

   ExampleClass1
   ExampleClass2

Functions
---------

.. autosummary::
   :toctree: generated/

   example_function1
   example_function2

Exceptions
----------

.. autosummary::
   :toctree: generated/

   ExampleError

The autosummary directives are important as they generate RST files in the generated/ directory for each object. A single-line summary and link to each object is inserted into the page for you.

After listing public module members, we encourage a usage example section showing how to use some of the module's functionality. Examples should be written in doctest format so that they can be automatically tested (e.g., using nosetests --with-doctest or make doctest).

Examples
--------

Run the ``example_function1`` function:

>>> from skbio.core.example import example_function1
>>> example_function1("hello", "world")
hello world!

You can also embed the plots that an example generates into the built documentation with the .. plot:: directive. For example:

.. plot::

   >>> from skbio.draw.distributions import boxplots
   >>> fig = boxplots([[2, 2, 1, 3, 4, 4.2, 7], [0, -1, 4, 5, 6, 7]])

This will include the plot, a link to the source code used to generate the plot, and links to different image formats (e.g., PNG and PDF) so that users can easily download the plot.

You're now ready to document the members of your module.

Documenting module members

When documenting the members of a module (e.g., classes, methods, attributes, functions, and exceptions), follow the numpydoc conventions. In addition to these conventions, there are a few things to keep in mind:

  • When documenting a class, only public methods and attributes are included in the built documentation by default. If a method or attribute starts with an underscore, it is assumed to be private. If you want a private method to be included in the built documentation, add the following line to the method's docstring:

    .. shownumpydoc

    For example, you might want to document "special" methods such as __getitem__, __str__, etc., which would be ignored by default. We recommend placing this at the end of the docstring for consistency. Note that this will only work for methods; private attributes will always be ignored.

  • When documenting a class, include the Parameters and Attributes sections in the class docstring, instead of in the __init__ docstring. While numpydoc technically supports either form, __init__ is not included in the list of methods by default and thus should have its documentation included in the class docstring.

Including the module in the docs

Until now, we've only been editing docstrings, which are attached to Python code. The final step is to hook up this new module's docstrings to the documentation build system:

  1. Make sure you're within the scikit-bio/doc directory.

  2. Create a new file with the same name as your module under the source directory. Do not include skbio as part of the name, and use .rst as the suffix. For example, source/core.example.rst.

  3. Add the following line to source/core.example.rst to have your module's docstring pulled into the document:

    .. automodule:: skbio.core.example

  4. Add the following line to source/index.rst to add the new page to the top-level table of contents:

    core.example

That's it! You can now try building the documentation, which should include the documentation for your new module!

Documenting a subpackage in scikit-bio

The process of documenting a subpackage is very similar to documenting a module in scikit-bio. The only difference is that the module docstring goes in the subpackage's __init__.py.

Troubleshooting

If things aren't working correctly, try running make clean and then rebuild the docs. If things still aren't working, try building the docs without your changes, and see if there are any Sphinx errors or warnings. Make note of these, and then see what new errors or warnings are generated when you add your changes again.