sphinx-stan

sphinx-stan is a Sphinx extension for documenting Stan code. It supports both standard Sphinx fields as well as the doxygen syntax recommended by the Stan user guide.

Warning

sphinx-stan is an early release; use it at your own risk. Bugs and feature requests can be filed on GitHub.

Explicit documentation of functions

Functions can be documented explicitly using the :stan:function:: ... directive. For example, the following statements generate the documentation shown below.

.. stan:function:: real log(real x, real y)

    Evaluate the logarithm of :math:`x` with base :math:`y`.

    :param x: Value to take the logarithm of.
    :param y: Base of the logarithm.
    :return: :math:`\log_y\left(x\right)`.
    :throws: If :math:`x` or :math:`y` are negative.

real log(real x, real y)

Evaluate the logarithm of \(x\) with base \(y\).

Parameters

• x – Value to take the logarithm of.

• y – Base of the logarithm.

Returns

\(\log_y\left(x\right)\).

Throws

If \(x\) or \(y\) are negative.

Stan supports overloading, and so does the documentation. For example, the following function evaluates the natural logarithm, implicitly setting \(y=e\).

real log(real x)

Evaluate the natural logarithm of \(x\).

Parameters

x – Value to take the logarithm of.

Returns

\(\log\left(x\right)\).

Throws

If \(x\) is negative.

Using the :stan:func:`...` role, we can reference specific overloaded implementations (such as log(real, real) or log(real)) by specifying the argument types.

Note

sphinx-stan will try to resolve unqualified function references (such as :stan:func:`log`). A warning will be issued if the unqualified reference is ambiguous and the reference may point to any of the overloaded functions.

Automatic documentation

Functions can also be documented by loading them from a *.stan file. For example, the following statements document two functions stored in example.stan.

.. stan:autodoc:: example.stan
    :members: mat_pow; log1p_series(real, int)

matrix mat_pow(matrix X, real y)

Raise a matrix to a power (described using doxygen syntax in a separate Stan file).

We can also reference other functions from within *.stan files, such as log(real, real).

Parameters

• X – Matrix to raise to a power.

• y – Power.

Returns

\(X^y\)

Throws

An error if there’s a problem.

real log1p_series(real x, int n)

Evaluate a series approximation of \(\log\left(1 + x\right)\) with \(n\) terms.

Note

The example file contains another function with different signature that does not show up in the documentation because it does not match the :members: field.

Documentation for each function must preceed it and be wrapped in /** ... */ comments. The content of the example file is:

/**
* Raise a matrix to a power (described using doxygen syntax in a separate Stan file).
*
* We can also reference other functions from within *.stan files, such as
* :stan:func:`log(real, real)`.
*
* @param X Matrix to raise to a power.
* @param y Power.
* @return :math:`X^y`
* @throws An error if there's a problem.
*/
matrix mat_pow(matrix X, real y) {
    return rep_matrix(0, 1, 1);  // Not the correct value, of course.
}

/**
Evaluate a series approximation of :math:`\log\left(1 + x\right)` with :math:`n` terms.

.. note::

  The example file contains another function with different signature that does not show up in the
  documentation because it does not match the :code:`:members:` field.
*/
real log1p_series(real x, int n) {
    return 0;  // Not the correct value, of course.
}


/**
This function does not appear in the documentation.
*/
real log1p_series(real x) {
    return 0;  // Not the correct value, of course.
}

Syntax

.. stan:function:: <signature of the function>

    <general documentation that supports any reST syntax>

    :param <parameter name>: <parameter description>
    :param <parameter name>: <parameter description>
    :return: <return value description>
    :throws:

      - <first error condition>
      - <second error condition>

Alternatively, functions may also be documented using the doxygen syntax (see the Stan user guide for details).

.. stan:autodoc:: <path to stan file>
    :members: <semi-colon separated list of functions to document>

If :members: is omitted, all functions in the file are documented in the order they appear. Function names are matched using the same logic as for the :stan:func:`...` cross-referencing logic. If the file contains overloaded functions and only an unqualified name is provided (i.e., without argument types), all overloaded functions with the given identifier will be documented in the order they appear.

Installation

The extension can be installed in two steps:

1. Run pip install sphinx-stan from the command line to install the package.

2. Add "sphinxcontrib.stan" to the list of extensions in your Sphinx configuration, typically conf.py. You can view the configuration used to build this documentation here.