View source for Contribute to Documentation with reStructuredText

To contribute to some parts of the Inkscape documentation, we have to write our docs in [https://de.wikipedia.org/wiki/ReStructuredText reStructuredText] file format (<code>*.rst</code>). 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 [https://github.com/sphinx-doc/sphinx 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 <code>*.rst</code> files and preview (render) them.

=== Recommended: Install VSCodium (or VS Code) ===

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

Downloads:

[https://vscodium.com VSCodium]

[https://code.visualstudio.com 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 ===

[[File:Esbonio.png|alt=The Esbonio extension on the VSCode marketplace|thumb|The Esbonio extension on the VSCode marketplace]]

This extension can be used to preview <code>*.rst</code> 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 <code>python3-*</code> 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
 
<p class="callout info">''See also https://www.sphinx-doc.org/en/master/usage/installation.html''</p>

=== Clone the documentation ===

 cd ~/
 git clone https://gitlab.com/inkscape/extensions.git
[[File:Rst-vscodium.png|Live preview of rST files in VSCodium|alt=Live preview of rST files in VSCodium|thumb]]

=== Open the folder within VSCodium ===

... and begin to contribute!

=== Troubleshooting ===

* '''My opened <code>*.rst</code> 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!