From 0993d5e577865ebb80b89c17f03eb7460489995c Mon Sep 17 00:00:00 2001
From: Veit Schiele <veit@cusy.io>
Date: Tue, 29 Oct 2024 16:37:50 +0100
Subject: [PATCH] :memo: Add conversion to reST

---
 CHANGELOG.rst                    |  4 ++
 docs/document/sphinx/convert.rst | 66 ++++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+)
 create mode 100644 docs/document/sphinx/convert.rst

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 45912aa..78a4960 100644
--- a/CHANGELOG.rst
+++ b/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
 ~~~~~~~
 
diff --git a/docs/document/sphinx/convert.rst b/docs/document/sphinx/convert.rst
new file mode 100644
index 0000000..83a643a
--- /dev/null
+++ b/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