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:
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
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
Open the folder within VSCodium
... and begin to contribute!
Troubleshooting
- My opened
*.rstfile 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!