📝 Add conversion to reST

Author: veit

CHANGELOG.rst

@@ -16,6 +16,10 @@ emergencies when we need to start branches for older versions.
 `Unreleased <https://github.com/veit/python-basics-tutorial/compare/24.3.0...HEAD>`_
 ------------------------------------------------------------------------------------
 
+Added
+~~~~~
+* 📝 Add conversion to reST
+
 Changed
 ~~~~~~~
 

docs/document/sphinx/convert.rst

@@ -0,0 +1,66 @@
+Convert
+=======
+
+Other file formats can be converted to :doc:`rest` with Pandoc.
+
+Installation of Pandoc
+----------------------
+
+`Pandoc <https://pandoc.org/installing.html>`_ is a powerful document conversion
+utility. We use it for simple conversions, but it is capable of much more.
+
+Installation
+------------
+
+You can install Pandoc for the different platforms:
+
+.. tab:: Debian/Ubuntu
+
+   .. code-block:: console
+
+      $  sudo apt install pandoc
+
+.. tab:: macOS
+
+   .. code-block:: console
+
+      $  brew install pandoc
+
+.. tab:: Windows
+
+   .. code-block:: ps1
+
+      $  choco install pandoc
+
+.. seealso::
+   * `Installing pandoc <https://pandoc.org/installing.html>`_
+
+Convert
+-------
+
+In the terminal, navigate to the directory containing the documents to be
+converted. Then enter the command :samp:`pandoc -s --toc -f {INPUT_FORMAT} -t
+rst {MYDOC}.{SUFFIX}`:
+
+``-s``
+    creates an independent document
+``--toc``
+    creates a table of contents (optional)
+``-t``
+    creates a reStructuredText output
+``-f``
+    tells Pandoc the input format. You can find an overview of the available
+    input formats in `General options
+    <https://pandoc.org/MANUAL.html#general-options>`_.
+
+Correcting the converted document
+---------------------------------
+
+The extent of the correction for the converted document depends on the file
+format you are converting from. Here are a few things you should pay attention
+to:
+
+* Multi-line titles must be converted to single-line titles
+* Independent ``**`` characters
+* :samp:`***BOLD***` should be :samp:`**BOLD**`
+* Incorrect tables

docs/document/sphinx/index.rst

@@ -49,6 +49,7 @@ helpful.
 
     start
     rest
+    convert
     code-blocks
     placeholder
     ui-elements