Documentation

Documenting a mixed-language project such as BridgeStan can be tricky.

We attempt to keep documentation in the natural place for each language: C/C++ code is documented with doxygen-style comments in the source, Python documentation appears in docstrings, etc. Our documentation generation (powered by Sphinx) automatically combines these together into the documentation you are reading now.

To build the documentation, you can run make docs in the top-level directory. This places the files in docs/_build/html. At a minimum, the following must be installed:

• The Python interface to BridgeStan

• Sphinx 5.0 or above

• nbsphinx

• sphinx-copybutton

• pydata-sphinx-theme

• MySt-Parser

There are also optional dependencies depending on which part of the documentation you are updating. If you wish to build the C++ portions of the documentation, you should also have:

• Doxygen

• Breathe

Similarly, the Julia documentation will only update if Julia is installed. Julia documentation is written in julia/docs/src/julia.md. We then build this with DocumenterMarkdown.jl, and the output is placed in docs/languages/julia.md.

Finally, the R documentation is primarily written in /docs/languages/r.md. The API documentation for R is done by including files generated by rd2markdown, which runs on the results of the roxygen2 package.