Contribute to Documentation with reStructuredText - Revision history

Moini: Add more nuance. Not everything is 'required', people have a choice. Also note that a real build is always better, if people are able to do it.

2025-05-28T00:23:43Z

Add more nuance. Not everything is 'required', people have a choice. Also note that a real build is always better, if people are able to do it.

← Older revision		Revision as of 00:23, 28 May 2025
Line 1:		Line 1:
	To contribute to ~~recent~~ Inkscape ~~documentations~~, 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 ~~still~~ different.		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.		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.

	=== Install VS Code ~~or VSCodium~~ ===		=== 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).		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:		Downloads:

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

	~~[https://vscodium.com VSCodium] (same like Visual Studio Code, but fully Open Source!)~~
	[[File:Esbonio.png\|alt=The Esbonio extension on the VSCode marketplace\|thumb\|The Esbonio extension on the VSCode marketplace]]		[[File:Esbonio.png\|alt=The Esbonio extension on the VSCode marketplace\|thumb\|The Esbonio extension on the VSCode marketplace]]

	~~=== Install Esbonia Extension ===~~		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.
	This extension ~~is required~~ to ~~render~~ <code>*.rst</code> 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.
			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		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 ===		=== Install additional requirements ===

	'''Ubuntu:'''		'''Ubuntu:'''

	We install Sphinx globally to system, that's why we use the <code>python3-*</code> packages:		We install Sphinx globally to system, that's why we use the <code>python3-*</code> packages:
	sudo apt install python3-sphinx python3-doc8		sudo apt install python3-sphinx python3-doc8

	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>

	=== Clone the documentation ===		=== Clone the documentation ===

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

	=== 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!

Ltlnx at 14:32, 27 May 2025

2025-05-27T14:32:45Z

← Older revision		Revision as of 14:32, 27 May 2025
Line 25:		Line 25:
	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>~~[[File:Rst-vscodium.png\|Live preview of rST files in VSCodium\|alt=Live preview of rST files in VSCodium\|thumb]]~~		<p class="callout info">''See also https://www.sphinx-doc.org/en/master/usage/installation.html''</p>

	=== Clone the documentation ===		=== Clone the documentation ===
	cd ~/		cd ~/
	git clone https://gitlab.com/inkscape/extensions.git		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 ===		=== Open the folder within VSCodium ===

Leyghis: clarify which system is used

2025-05-27T09:06:02Z

clarify which system is used

← Older revision		Revision as of 09:06, 27 May 2025
Line 19:		Line 19:

	=== Install additional requirements ===		=== Install additional requirements ===
			'''Ubuntu:'''

	We install Sphinx globally to system, that's why we use the <code>python3-*</code> packages:		We install Sphinx globally to system, that's why we use the <code>python3-*</code> packages:
	sudo apt install python3-sphinx python3-doc8		sudo apt install python3-sphinx python3-doc8
Line 33:		Line 35:
	=== 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!

Ltlnx at 09:04, 27 May 2025

2025-05-27T09:04:15Z

← Older revision		Revision as of 09:04, 27 May 2025
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>[[File:Rst-vscodium.png\|Live preview of rST files in VSCodium\|alt=Live preview of rST files in VSCodium\|thumb~~\|600x600px~~]]		<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]]

	=== Clone the documentation ===		=== Clone the documentation ===

Ltlnx at 09:03, 27 May 2025

2025-05-27T09:03:44Z

← Older revision		Revision as of 09:03, 27 May 2025
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!~~[[File:Rst-vscodium.png\|Live preview of rST files in VSCodium\|alt=Live preview of rST files in VSCodium\|thumb\|600x600px]]~~		... 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!

Ltlnx at 09:03, 27 May 2025

2025-05-27T09:03:21Z

← Older revision		Revision as of 09:03, 27 May 2025
Line 29:		Line 29:
	git clone https://gitlab.com/inkscape/extensions.git		git clone https://gitlab.com/inkscape/extensions.git

	=== Open the folder within VSCodium and begin to contribute ~~===~~		=== Open the folder within VSCodium ===
	[[File:Rst-vscodium.png\|~~left~~\|Live preview of rST files in VSCodium]]		... and begin to contribute![[File:Rst-vscodium.png\|Live preview of rST files in VSCodium\|alt=Live preview of rST files in VSCodium\|thumb\|600x600px]]

	=== Troubleshooting ===		=== Troubleshooting ===

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

	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!

Ltlnx at 09:01, 27 May 2025

2025-05-27T09:01:28Z

← Older revision		Revision as of 09:01, 27 May 2025
Line 30:		Line 30:

	=== Open the folder within VSCodium and begin to contribute ===		=== Open the folder within VSCodium and begin to contribute ===
	[[File:Rst-vscodium.png\|left~~\|frame~~\|Live preview of rST files in VSCodium]]		[[File:Rst-vscodium.png\|left\|Live preview of rST files in VSCodium]]

	=== Troubleshooting ===		=== Troubleshooting ===

Ltlnx: Add media

2025-05-27T09:00:53Z

Add media

← Older revision		Revision as of 09:00, 27 May 2025
Line 11:		Line 11:

	[https://vscodium.com VSCodium] (same like Visual Studio Code, but fully Open Source!)		[https://vscodium.com VSCodium] (same like Visual Studio Code, but fully Open Source!)
			[[File:Esbonio.png\|alt=The Esbonio extension on the VSCode marketplace\|thumb\|The Esbonio extension on the VSCode marketplace]]

	=== Install Esbonia Extension ===		=== Install Esbonia Extension ===
	This extension is required to render <code>*.rst</code> 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.		This extension is required to render <code>*.rst</code> 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](~~https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio		Download/Install: https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio

	=== Install additional requirements ===		=== Install additional requirements ===
Line 22:		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~~](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>

	=== Clone the documentation ===		=== Clone the documentation ===
Line 29:		Line 30:

	=== Open the folder within VSCodium and begin to contribute ===		=== Open the folder within VSCodium and begin to contribute ===
			[[File:Rst-vscodium.png\|left\|frame\|Live preview of rST files in VSCodium]]

	=== Troubleshooting ===		=== Troubleshooting ===

Ltlnx: Ltlnx moved page Inkscape/Contribute to Documentation with reStructuredText to Contribute to Documentation with reStructuredText

2025-05-27T08:56:18Z

Ltlnx moved page Inkscape/Contribute to Documentation with reStructuredText to Contribute to Documentation with reStructuredText

← Older revision	Revision as of 08:56, 27 May 2025
(No difference)

Ltlnx: Created page with "To contribute to recent Inkscape documentations, we have to write our docs in [https://de.wikipedia.org/wiki/ReStructuredText reStructuredText] file format (`*.rst`..."

2025-05-27T08:53:32Z

Created page with "To contribute to recent Inkscape documentations, we have to write our docs in [https://de.wikipedia.org/wiki/ReStructuredText reStructuredText] file format (<code>*.rst</code>..."

New page

To contribute to recent Inkscape documentations, 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 still different.

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.

=== Install VS Code or VSCodium ===
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://code.visualstudio.com Visual Studio Code]

[https://vscodium.com VSCodium] (same like Visual Studio Code, but fully Open Source!)

=== Install Esbonia Extension ===
This extension is required to render <code>*.rst</code> 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](https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio

=== Install additional requirements ===
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](https://www.sphinx-doc.org/en/master/usage/installation.html)</p>

=== Clone the documentation ===
cd ~/
git clone https://gitlab.com/inkscape/extensions.git

=== 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!

Contribute to Documentation with reStructuredText - Revision history

Moini: Add more nuance. Not everything is 'required', people have a choice. Also note that a real build is always better, if people are able to do it.

Ltlnx at 14:32, 27 May 2025

Leyghis: clarify which system is used

Ltlnx at 09:04, 27 May 2025

Ltlnx at 09:03, 27 May 2025

Ltlnx at 09:03, 27 May 2025

Ltlnx at 09:01, 27 May 2025

Ltlnx: Add media

Ltlnx: Ltlnx moved page Inkscape/Contribute to Documentation with reStructuredText to Contribute to Documentation with reStructuredText

Ltlnx: Created page with "To contribute to recent Inkscape documentations, we have to write our docs in [https://de.wikipedia.org/wiki/ReStructuredText reStructuredText] file format (*.rst..."

Ltlnx: Created page with "To contribute to recent Inkscape documentations, we have to write our docs in [https://de.wikipedia.org/wiki/ReStructuredText reStructuredText] file format (`*.rst`..."