How to write QGreenland 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.

PDF vs HTML format

Our PDF doc is intended to be user-focused, but our HTML docs serve users and contributors (i.e. PDF docs are a subset of HTML docs). Most of the docs end up in both formats, so we want to use the same content to create both.

Sphinx offers the .. only:: directive for conditional content, but it does not work as one might intuitively expect. Specifically, it isn’t capable of creating conditional or filtered toctrees. Because of this insufficiency, we’re employing two nonstandard methods in doc/index.rst to deselect items from PDF docs:

Our custom .. toctree-select-builder:: directive, defined in doc/sphinx-ext/toctree_select_builder.py, is a customized toctree directive which enables filtering its contents. If a prefix is present, that entry will only be kept if the prefix matches the name of the current builder.
```
.. toctree-select-builder::
    :name: Mixed content
    :caption: Mixed content

    always/shown/document
    :html:html/only/document
    :latex:pdf/only/document
```
The package sphinx-selective-exclude enhances the behavior of .. only:: to more intuitively select content during the parsing phrase, enabling entire toctrees to be deselected. For example, the following toctree would be omitted if the builder is latex:
```
.. only:: html

    .. toctree::
        :name: HTML only
        :caption: HTML only

        html/only/document
        another/html/only/document
```

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.

Contributing to documentation

Attention

You’ll need to have TeX Live installed if you want to render PDF documentation. On Debian-based systems, you can install it with sudo apt install texlive-latex-extra.

We attempted to include this dependency via the conda package texlive-core, but there are issues with it.

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.