.. _doc_contrib_doc:

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:

* `Getting started with RST`_
* `Cheat Sheet`_ for the RST syntax and Sphinx


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. :doc:`/02_getting_started/installation/index`).
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. :doc:`/02_getting_started/installation/src_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:

* `reStructuredText`_: For RST language support.
* `reStructuredText Syntax highlighting`_: For syntax highlighting.
* `Esbonio`_: Server for auto-compiling and previewing RST files.
* `LTeX`_: To enable spell checking in the RST files.

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.


.. _`Getting started with RST`: https://sphinx-tutorial.readthedocs.io/step-1/
.. _`Cheat Sheet`: https://sphinx-tutorial.readthedocs.io/cheatsheet/
.. _`website`: https://code.visualstudio.com/
.. _`Snap Store`: https://snapcraft.io/code
.. _`reStructuredText`: https://marketplace.visualstudio.com/items?itemName=lextudio.restructuredtext
.. _`reStructuredText Syntax highlighting`: https://marketplace.visualstudio.com/items?itemName=trond-snekvik.simple-rst
.. _`Esbonio`: https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio
.. _`LTeX`: https://marketplace.visualstudio.com/items?itemName=valentjn.vscode-ltex
.. _`conda`: https://docs.conda.io/projects/conda/en/latest/
.. _miniconda: https://docs.conda.io/en/latest/miniconda.html
.. _mamba: https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html
.. _miniforge: https://conda-forge.org/download/