As part of developing the package for Scalable Gaussian process inference, I wrote a reasonable amount of interface documentation. To avoid scattering documentation across different documents (e.g., Stan code and markdown or reStructuredText), there is a small extension for Sphinx that can autogenerate documentation from inline comments.
For example, consider the following Stan file.
/**
* Raise a matrix to a power.
*
* @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.
}
Using the Stan-domain autodoc directive in Sphinx, automatically generates the documentation below.
.. stan:autodoc:: example.stan
The extension also supports cross-references, i.e., one can use :stan:func:`mat_pow ` to generate a clickable reference within the documentation. E.g., here’s the background section for Fourier-based GPs with links to the interface documentation.
There are a few additional features (such explicit function documentation in .rst, documenting only a subset of functions defined in a .stan file, and support for both doxygen syntax and standard Sphinx-style rst).
Maybe others will also find it useful for documenting their Stan code. Instructions on how to get started are here. Disclaimer: It’s still pretty rough around the edges.