Difference between revisions of "Contribute to Documentation with reStructuredText"
| Line 23: | Line 23: | ||
After this, we have following commands available for CLI also: | After this, we have following commands available for CLI also: | ||
sphinx-apidoc sphinx-autogen sphinx-build sphinx-quickstart | 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> | <p class="callout info">''See also https://www.sphinx-doc.org/en/master/usage/installation.html''</p>[[File:Rst-vscodium.png|Live preview of rST files in VSCodium|alt=Live preview of rST files in VSCodium|thumb|600x600px]] | ||
=== Clone the documentation === | === Clone the documentation === | ||
| Line 30: | Line 30: | ||
=== Open the folder within VSCodium === | === Open the folder within VSCodium === | ||
... and begin to contribute! | ... and begin to contribute! | ||
=== Troubleshooting === | === 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! | * '''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! | ||
Revision as of 09:03, 27 May 2025
To contribute to recent Inkscape documentations, we have to write our docs in reStructuredText file format (*.rst). It's similar to Markdown, but still different.
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.
Install VS Code or VSCodium
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 (same like Visual Studio Code, but fully Open Source!)
Install Esbonia Extension
This extension is required to render *.rst files. Rendering helps to validate, 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. Syncronised scrolling between the source and preview is also supported.
Download/Install: https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio
Install additional requirements
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!