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!
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 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 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
.
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 are
employing two nonstandard methods in doc/index.rst
to deselect items from PDF
docs:
-
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 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 environment defined by
doc/environment.yml
.
Start here to learn about writing reStructuredText for Sphinx documentation.
Start here to learn about writing Markdown for Sphinx documentation. Markdown is supported out of the box by Read the Docs.
You will 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](https://github.com/conda-forge/texlive-core-feedstock/issues/19) with
it.
- 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 are 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.
- 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.
We have created the following styles to use when referring to QGIS elements and menu paths:
-
Any reference to a QGIS user interface element will be bolded. e.g.: "Navigate to Settings -> User Profiles -> Open Active Profile Folder to get the directory path" or "Use the Layers Panel to change the order of the layers".
-
Menu paths are delimited by ->, e.g.: Settings -> User Profiles -> Open Active Profile Folder
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.