How to write documentation¶

Our documentation is written in reStructuredText and Markdown for the Sphinx documentation generator. The documentation website is built by and hosted on Read the Docs.

We follow a conceptual framework called Diátaxis to write high quality, easy-to-use documentation.

We expected Sphinx and reStructuredText to be difficult to learn, but were pleasantly surprised. We hope that you will also find it easy and pleasant to contribute to our documentation. Thank you in advance for your efforts!

Background information¶

Our documentation lives in the doc/ folder. The documentation-generator config is in doc/conf.py. The ReadTheDocs configuration is in .readthedocs.yml file at the root of this repository. The main tables of contents are expressed in the doc/index.rst file.

Diátaxis¶

Diátaxis provides a conceptual framework for targeting and organizing information in documentation.

Please familiarize yourself with this framework and help us continually improve the quality of our docs. The best place to start is this video on YouTube.

Sphinx¶

Sphinx reads documentation (written in reStructuredText or, with an extension, Markdown) and other content (including code with autodoc or other extensions). It converts this content into many output formats including HTML and PDF.

Sphinx’s configuration is kept at doc/conf.py.

Read the Docs¶

Read the Docs is a documentation building and hosting service. It can use Sphinx or MkDocs under the hood, and we chose Sphinx. It runs automatically in response to changes in GitHub. It is configured by .readthedocs.yml at the root of this repository.

When Read the Docs builds our documentation, it uses the Python environment defined by doc/requirements.txt.

reStructuredText¶

Start here to learn about writing reStructuredText for Sphinx documentation.

MyST Markdown extension¶

Start here to learn about writing Markdown for Sphinx documentation. Markdown is supported out of the box by Read the Docs.

How to add a new documentation page¶

Is this new content a How To, a Tutorial, Reference material, or a Discussion topic? Ensure your document is in the correct directory and written for the correct audience.
Write your documentation in Markdown, unless you’re writing a page that must be majority reStructuredText, such as an index.rst for a new group of pages.
Ensure your documentation page starts with a top-level header. This is the title of the page.
Use inv docs.watch to build documentation on every edit and view your changes in the browser.
Create a pull request. GitHub will trigger a build on Read the Docs which you can view by clicking “details” for the Read the Docs check.

How to update an existing documentation page¶

Is this new content a How To, a Tutorial, Reference material, or a Discussion topic? Ensure your document is in the correct directory and written for the correct audience.
Ensure your new content fits appropriately with surrounding content.
Use inv docs.watch to build documentation on every edit and view your changes in the browser.
Create a pull request. GitHub will trigger a build on Read the Docs which you can view by clicking “details” for the Read the Docs check.

Documentation styles¶

Screenshots and videos of the QGIS interface¶

Screenshots and videos displaying the QGIS interface should use the default theme (i.e., not the ‘dark theme’) so that the interface looks as close as possible to what a new user is likely to see when opening QGIS for the first time.

Moreover, QGIS’s ‘dark theme’ tends to make some elements difficult to read / see on the screen. For example, Layers Panel checkboxes are not clearly distinguishable.