Documentation
Guide to documenting Q-CTRL projects
Q-CTRL projects have two types of documentation:
Contributor documentation
Contributor documentation is found in the .github/README.md file and optionally in the docs folder of a repository. The .github/README.md file contains only the necessary information for a developer to get started contributing to the project.
Q-CTRL follows the standard specified in the .github/README.md file in the Q-CTRL Template repository. This file contains the required structure, and instructions on how to apply the standard.
Additional contributor documentation may be placed in a docs folder when more comprehensive documentation is needed beyond the basic getting started information. This documentation can be built using MkDocs or Sphinx depending on the project’s needs.
User documentation
User documentation is found in two places:
- The
README.mdfile. - The Q-CTRL Documentation website.
The README.md file
The README.md file contains only the necessary information for a customer to get started using the software.
Q-CTRL follows the standard specified in the README.md file in the Q-CTRL Template repository. This file contains the required structure, and instructions on how to apply the standard.
The README.md file differs from the .github/README.md file above inasmuch as it is used by repositories whose code is published as a software package. The README.md file is used by the hosted package manager to display information about the software package on the packages home page.
Below are examples of the README.md file being used to populate package home pages.
- https://pypi.org/project/qctrl-visualizer/
- https://www.npmjs.com/package/@qctrl/visualizer
The Q-CTRL Documentation website
Any means by which a user accesses the platform is supported by user documentation with the aim of making it easy and intuitive to use the software. In the documentation, the software packages are referred to by their package names.
User documentation follows the Diátaxis Framework. This framework includes the tutorials, topics (explanations), and user guides (how-to guides), that are created in the form of Jupyter notebooks, and made available in the Q-CTRL Documentation website. The last component of this framework are references, which are generated using the appropriate tools for their programming language. The title of the reference documentation page matches the package name of the documented package.
Documentation tools
Q-CTRL uses two primary documentation tools: MkDocs and Sphinx. Choose the appropriate tool based on your documentation needs and target audience.
MkDocs
MkDocs is used for public or internal documentation and serves as a presentation layer for Markdown. MkDocs is ideal when you need to:
- Create user-friendly websites from existing Markdown documentation in your repository
- Generate API documentation using the mkdocstrings plugin
- Include Jupyter notebooks using the mknotebooks plugin
- Maintain documentation that remains usable directly in GitHub
MkDocs is unobtrusive and unopinionated, making it easy to convert existing Markdown documentation into a polished website without requiring specialized markup.
Sphinx
Sphinx can be used for both internal and external documentation. It is particularly well-suited for:
- Auto-generating comprehensive API documentation from Python docstrings
- Projects that require extensive cross-referencing and advanced documentation features
- Internal developer documentation that doesn’t need to be publicly accessible
Note: The Q-CTRL Sphinx Theme is used for public documentation, whereas the standard Sphinx Read the Docs Theme is used for internal documentation.