Contribute to Documentation with reStructuredText

To contribute to some parts of the Inkscape documentation, we have to write our docs in reStructuredText file format (*.rst). It's similar to Markdown, but uses a different syntax. It is used because it has some advantages over Markdown, as it provides semantic (meaningful) markup and is more geared towards writing documentation.

The Inkscape documentation is built up on Sphinx, which is some kind of special engine. To easily contribute without being a professional developer, we can use VSCodium and some plugin to edit those *.rst files and preview (render) them.

Recommended: Install VSCodium (or VS Code)

With VSCodium we can edit *.rst files with ease. There's native syntax highlighting. But we cannot render the final result by default (needs a separate extension).

Downloads:

VSCodium

Visual Studio Code (same as VSCodium, but not fully Open Source!)

Of course, you can also use any other editor that you like to use and are acquainted with.

Optional: Install Esbonia Extension

The Esbonio extension on the VSCode marketplace

This extension can be used to preview *.rst files. Rendering helps to confirm that the code we wrote is valid before we commit and push to Inkscape repositories.

It can show a live HTML preview of the documentation, so the preview contents change whenever the document is updated. Synchronised scrolling between the source and preview is also supported.

Download/Install: https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio

Optimally, though, we would recommend that you build the documentation on your computer to benefit from the full validation capabilities that are provided by the scripts that come with the documentation, and to see the web pages almost exactly as they would be when viewed online, including CSS and styling. For this, follow the instructions in the corresponding project's README file.

Install additional requirements

Ubuntu:

We install Sphinx globally to system, that's why we use the python3-* packages:

sudo apt install python3-sphinx python3-doc8

After this, we have following commands available for CLI also:

sphinx-apidoc sphinx-autogen sphinx-build sphinx-quickstart

See also https://www.sphinx-doc.org/en/master/usage/installation.html

Clone the documentation

cd ~/
git clone https://gitlab.com/inkscape/extensions.git

Live preview of rST files in VSCodium

Open the folder within VSCodium

... and begin to contribute!

Troubleshooting

• My opened *.rst file is not rendered: Opening a single file without an active workspace is not currently supported and will lead to errors, which might not be communicated to the user visually. Open the folder containing your documentation project in VSCode instead!