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 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.
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.
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.