sphinx-stan

Sphinx domain for Stan, the probabilistic programming language

https://github.com/tillahoffmann/sphinx-stan

Repository

Sphinx domain for Stan, the probabilistic programming language

README.rst

sphinx-stan
===========

.. image:: https://github.com/tillahoffmann/sphinx-stan/actions/workflows/main.yml/badge.svg
    :target: https://github.com/tillahoffmann/sphinx-stan/
.. image:: https://badge.fury.io/py/sphinx-stan.svg
    :target: https://pypi.org/project/sphinx-stan/
.. image:: https://readthedocs.org/projects/sphinx-stan/badge/?version=latest
    :target: https://sphinx-stan.readthedocs.io/en/latest/?badge=latest

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 :code:`:stan:function:: ...` directive. For example, the following statements generate the documentation shown below.

.. code-block:: rst

    .. 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.

.. 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.

Stan supports `overloading `_, and so does the documentation. For example, the following function evaluates the natural logarithm, implicitly setting :math:`y=e`.

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

    Evaluate the natural logarithm of :math:`x`.

    :param x: Value to take the logarithm of.
    :return: :math:`\log\left(x\right)`.
    :throws: If :math:`x` is negative.

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

.. note::

    sphinx-stan will try to resolve unqualified function references (such as :code:`: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 :code:`*.stan` file. For example, the following statements document two functions stored in :code:`example.stan`.

.. code-block:: rst

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

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

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

.. literalinclude:: example.stan
    :language: stan

Syntax
------

.. code-block:: rst

    .. stan:function:: 

        

        :param : 
        :param : 
        :return: 
        :throws:

          - 
          - 

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

.. code-block:: rst

    .. stan:autodoc:: 
        :members: 

If :code:`: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 :code:`: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 :code:`pip install sphinx-stan` from the command line to install the package.
2. Add :code:`"sphinxcontrib.stan"` to the list of `extensions `__ in your Sphinx configuration, typically :code:`conf.py`. You can view the configuration used to build this documentation `here `__.

Owner

Citation (CITATION.cff)

# yaml-language-server: $schema=https://citation-file-format.github.io/1.2.0/schema.json
cff-version: 1.2.0
message: If you use this software, please cite it as below.
title: "sphinx-stan: Sphinx domain for Stan, the probabilistic programming language."
url: "https://github.com/tillahoffmann/sphinx-stan"
authors:
- family-names: Hoffmann
  given-names: Till
  orcid: https://orcid.org/0000-0003-4403-0722
preferred-citation:
  type: article
  authors:
  - family-names: Hoffmann
    given-names: Till
    orcid: https://orcid.org/0000-0003-4403-0722
  - family-names: Onnela
    given-names: Jukka-Pekka
    orcid: https://orcid.org/0000-0001-6613-8668
  doi: 10.48550/arXiv.2301.08836
  journal: arXiv
  start: "2301.08836"
  title: Scalable Gaussian Process Inference with Stan
  year: 2023

GitHub Events

Issues and Pull Requests

Last synced: over 1 year ago