Guide to documenting Q-CTRL projects
Q-CTRL projects have two types of documentation:
Contributor documentation is found in the
.github/README.md file and contains only the necessary information for a developer to get started contributing to the project.
User documentation is found in two places:
- The Q-CTRL Documentation website.
README.md file contains only the necessary information for a customer to get started using the software.
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.
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.
Reference documentation for Python packages
Reference documentation for Python packages is generated using Sphinx. The Q-CTRL Sphinx Theme is used for public documentation, whereas the standard Sphinx Read the Docs Theme is used for internal documentation.