How to Use This Guide

The first thing you need to do to use this guide is to set up a documentation project. If you haven’t done so, check out this tutorial.

In Qiskit we are using a documentation framework called Diátaxis. It divides documentation according to the user’s needs in the following categories:

  • Tutorials: practical steps for learning.

  • How-to guides: practical steps for work.

  • Reference: concise technical manual of the API for work

  • Explanation: detailed information with additional context for learning.

For more details about what each documentation category means, check out this page.

This guide includes a section for each one of these types: Tutorials, How-to Guides, API Reference and Explanations. Each section includes content-related guidelines for writing the corresponding document type, as well as existing examples and the instructions needed to include it in your documentation. That also means that this guide itself is not actually implementing Diátaxis, so, for example, the Tutorials section is not made up of tutorials, even though you can find examples there.

Similarly, the Documentation Home, Getting Started and Release Notes pages will contain information about how to write this kind of files instead of being actual instances of them.

If what you are looking for is not how to deal with the content of your documentation but with the more technical details of creating documentation with Sphinx (the documentation builder we are using in Qiskit) refer to the Sphinx Guide section. There you will find explanatory material about Sphinx and ReStructuredText (Sphinx’s native language), as well as guides for Sphinx-related tasks such as building documentation, structuring it with different headers and lists and including links and technical expressions like code blocks or mathematic formulae.

Contributing to this guide

If you want to help improve this guide, you can open an issue in the qiskit_sphinx_theme repository to make any suggestions or directly create a pull request for the docs_guide folder of the repository if you prefer to make the changes yourself.