Documentation websites

Documentation websites provide a central place where users and contributors can learn how to install, use, and contribute to your project. They can include user guides, tutorials, API documentation, and developer guidelines.

Several frameworks are available for building documentation websites. Among the most popular in the Python ecosystem are Jupyter Book, Sphinx, and Read the Docs. The first two are useful to generate documentation websites, while latter is also a platform for hosting and automatically publishing them.

Jupyter Book¶

Jupyter Book is the documentation framework most commonly used within the ORMIR community. It is built on MyST Markdown. You can find comprehensive guidelines on the Jupyter Book website. We use Jupyter Book both for writing community documentation, such as these Code Guidelines and the Data Sharing Guidelines, and for publishing the documentation of some Python packages, such as ORMIR-MIDS and ORMIR-XCT.

Sphinx¶

Sphinx is a tool to write and generate documentation from docstrings. You can find guidelines on how to use Sphynx here.

Read the Docs¶

Read the Docsis a tool to generate code from docstrings and to host and publish documentation on the web. To learn how to use Read the Docs follow their step-by-step tutorial. An excellent example of Read the Docs is the documentation of Ciclope.