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 indoc/sphinx-ext/toctree_select_builder.py
, is a customizedtoctree
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 entiretoctrees
to be deselected. For example, the followingtoctree
would be omitted if the builder islatex
:.. 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.