Contributing documentation

This page describes how to contribute to the online documentation your are reading.

Getting familiar with Sphinx

If you are new to writing Read the Docs documentation, we recommend the following online resources to learn about reStructuredText (.rst) files:

Building the documentation

The documentation can be built locally within a conda/mamba environment to check that everything is correct and can be built by the ReadTheDocs server. Also, IDEs including Visual Studio Code or CLion can integrate a Sphinx installation for preview or build chains.

Installing Sphinx within an environment

Sphinx and several extensions are needed to build and preview the .rst files. It can be installed into an environment using conda or mamba, similar to Met.3D itself (cf. Installation). As for building Met.3D, we recommend the miniforge distribution (if you use miniconda change all mamba commands to conda).

If you haven’t done so, install miniforge into a directory that provides enough disk space (default is in you home directory, but you may want to use a different directory!).

Install miniforge:

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
chmod +x Miniforge3-Linux-x86_64.sh
./Miniforge3-Linux-x86_64.sh

You also need to initialize miniforge to use the mamba commands:

mamba shell init

Next, create a separate mamba environment for the documentation, so that it does not interfere with other environments.

Create and activate Met.3D documentation mamba environment:

mamba create -n met3d_docs
mamba activate met3d_docs

Next, install the sphinx package and required extensions:

mamba install -c conda-forge sphinx sphinx-rtd-theme sphinx-simplepdf sphinx-tabs sphinx-notfound-page sphinxext-opengraph sphinx-copybutton sphinxcontrib-video setuptools

Building the documentation

The documentation can be built from the command line. Make sure that the met3d_docs environment is activated.

Checkout the git repository of the documentation (https://gitlab.com/wxmetvis/met.3d.docs). Here, we put the documentation sources in the “met.3d-base” directory, like we do for the Met.3D source code (cf. Compile Met.3D from source code: Linux (conda)):

cd ~
mkdir met.3d-base && cd met.3d-base
git clone https://gitlab.com/wxmetvis/met.3d.docs.git

Next, create a directory for the resulting html files and build the documentation:

cd ~/met.3d-base/
mkdir m3d_docs_html && cd m3d_docs_html
sphinx-build -b html -a ~/met.3d-base/met.3d.docs/docs ~/met.3d-base/m3d_docs_html

Editing the documentation

The .rst files can be edited with any text editor. As examples, we describe setups using Visual Studio Code and CLion.

CLion

In Settings → Plugins, install the ReStructuredText plugin.

The preview in CLion is rather minimal, but the Sphinx build process above can be integrated as a build configuration: In the dropdown menu to the left of the “run” button on the right of the upper taskbar, select “Edit Configurations”. Create a new configuration (“+” symbol), select Python docs → Sphinx task. Set:

  • Command: html

  • Input: The docs directory in the met.3d.docs repository

  • Output: A directory for the html files

  • Options: -a

  • Python interpreter: Select the mamba environment created above (you may need to add this environment via Settings → Build, Execution, Deployment → Python interpreter → Add new interpreter)

Visual Studio Code

Visual Studio Code is available from this website. It can also be installed with the Snap Store, e.g., if you use Ubuntu.

Note

Make sure you are within the above created mamba environment when using VS Code. On Linux, you can simply start VS Code from the command line within the activated environment. On Windows, you can change the Python interpreter within VS code to the corresponding one.

Visual Studio Code needs some extensions to edit RST files. Head to the extension tab on the left hand task bar in the editor.

Install the following extensions:

Next, go to File → Preferences → Settings and search for esbonio.sphinx.buildDir. There you can set a build directory for the resulting preview html files.

Next, open the docs folder within the met.3d.docs repository.

Every time you edit the .rst files, the reStructuredText extension will automatically build the html files. You can also manually trigger a re-build by using the esbonio button on the lower right of the editor.

Contribution guidelines

Please follow the following contribution guidelines.

File structure

The documentation follows a simple file structure. For each page with sub-pages a folder is required in which the sub-pages are stored.

Example:

index.rst
user_docs
|-getting_started.rst
|-getting_started
| |-first_steps.rst
| |-figs

In the example, first_steps.rst is a sub-page of getting_started.rst. That is why it is located in the getting_started folder.

Figures are located in a sub-folder called figs. This folder contains all figures for the sub-pages of getting_started.

Figures

Figures are always located in a figs folder next to the page. Figures should be saved as a .webp file with lossy compression at low quality to save space You can convert all images in a folder to this format by using image-magick’s mogrify command:

Example:

mogrify -format webp -quality 30 -define webp:lossless=false *.png

The example converts all .png files in the folder to lossy compressed .webp files. The quality is set to 30%, though that depends on the image and its readability. Please avoid uploading large images.