Migrate files from rst to md files

Modified deployment with sphinx and MyST - Markedly Structured Text Update README See Issue #41
hitobito · Mar 9, 2024 · 9fc3357 · 9fc3357
1 parent 2a4f3b6
commit 9fc3357
Show file tree

Hide file tree

Showing 9 changed files with 98 additions and 132 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -15,9 +15,9 @@ python:
   install:
     - requirements: requirements.txt
 
-# Build documentation in the docs/ directory with mkdocs
-mkdocs:
-  configuration: ./mkdocs.yml
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: ./conf.py
 
 formats:
   - htmlzip

diff --git a/README.md b/README.md
@@ -31,11 +31,14 @@ Hier eine Sammlung von User Dokumentation/Dokumente von den Community Mitglieder
 * Die Mitte: Wir zur Zeit noch erstellt (Mehrsprachig)
 
 ## Contribute generic user documentation (this repo)
-The [readthedocs](https://readthedocs.org/) page is rebuilt with each merged PR. You can check whether the build was successful [here](https://readthedocs.org/projects/hitobito/builds/). If you are unsure, you can first merge into the beta branch. This is also built and can be reached in the [beta page](https://hitobito.readthedocs.io/de/beta/)
-A helpful overview over the restructured syntax that we use can be found [here](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
+The [readthedocs](https://readthedocs.org/) page is rebuilt with each merged PR. You can check whether the build was successful [here](https://readthedocs.org/projects/hitobito/builds/). If you are unsure, you can first merge into the beta branch. This is also built and can be reached in the [beta page](https://hitobito.readthedocs.io/de/beta/). We use [Sphinx](https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html) to generate the documentation. The individual files of the documentation can be found in the "docs" folder. We use MyST - Markedly Structured Text for the description of the documentation. A helpful overview over the markdown syntax that we use can be found [here](https://myst-parser.readthedocs.io/en/latest/index.html).
 
 Manual building:
 
+To build html local use: 
+
+`make html`
+
 Ensure that you have virtualenv and rake installed. Then:
 
 `rake build:all`

diff --git a/SUMMARY.md b/SUMMARY.md
diff --git a/conf.py b/conf.py
@@ -17,6 +17,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.intersphinx',
+    'myst_parser',
 ]
 
 intersphinx_mapping = {
@@ -33,3 +34,29 @@
 
 # -- Options for EPUB output
 epub_show_urls = 'footnote'
+
+# Exclude github files
+exclude_patterns = ['README.md', 'SECURITY.md', 'SUMMARY.md', 'SETUP.md']
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+myst_enable_extensions = [
+    "amsmath",
+    "attrs_inline",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/invoices.md b/docs/invoices.md
@@ -1,20 +1,18 @@
 # Rechnungen
 
-:::{warning}
 Rechnungen sind ein Feature welches pro Instanz aktiviert werden kann.
-:::
 
-:::{note}
+```{note}
 Ob du Rechnungen verwalten kannst hängt davon ab, ob dir eine entsprechende Rolle vergeben wurde. Welche Rolle das ist hängt von der jeweiligen Organisation ab.
-:::
+```
 
 In hitobito können Rechnungen erstellt und Debitoren verwaltet werden.
 
 ## Rechnungen erstellen
 
-:::{note}
+```{note}
 Rechnungen werden nicht auf der Ansicht Rechnungen erstellt, sondern ausgehend von Personenlisten oder auf der Ansicht einer bestimmten Person.
-:::
+```
 
 Rechnungen können aus folgenden Ansichten erstellt werden:
 

diff --git a/docs/mailing_lists_mailchimp_export.md b/docs/mailing_lists_mailchimp_export.md
@@ -18,9 +18,9 @@ Mit jeder Mailingliste kann jeweils eine MailChimp-Liste verknüpft werden. Dies
 ```{image} mailing_lists_mailchimp_export/mailing_list_settings.png
 ```
 
-:::{hint}
+```{tip}
 Standardmässig werden nur die Haupt-E-Mailadressen der Abonnent\*innen synchronisiert. Sollen weitere E-Mailadressen, welche die Option "Versand" haben ebenfalls mit MailChimp synchronisiert werden, ist die Option "Alle Versandadressen synchronisieren" anzuwählen.
-:::
+```
 
 Die **«MailChimp Listen-ID»** kannst Du in den Einstellungen der gewünschten Liste in MailChimp holen (in gelb unten rechts):
 
@@ -38,16 +38,16 @@ Gratuliere, nach dem Speichern dieser zwei Informationen ist nun deine Mailingli
 
 Um die Abonnent\*innen einer Mailingliste nach MailChimp zu exportieren, wähle die entsprechende Option im «Export»-Menu des «Abonnenten»-Tabs deiner Mailingliste in Hitobito aus.
 
-:::{danger}
+```{caution}
 Bitte beachte, dass der Export deine verknüpfte Liste in MailChimp überschreiben. Bestehende Kontakte werden in Mailchimp archiviert.
-:::
+```
 
 ```{image} mailing_lists_mailchimp_export/mailing_list_export.png
 ```
 
 Nach dem Auslösen des Exports wird die Liste im Hintergrund in die gewählte MailChimp-Liste exportiert und die Abonnent\*innen deiner Mailingliste sollten nach einiger Zeit dort erscheinen.
 Sollten E-Mailadressen in Mailchimp den Status "cleaned" besitzen, wird in hitobito ein entsprechender Validation Tag gesetzt. (z.B. "Haupt-E-Mail ungültig")
 
-:::{note}
+```{hint}
 Abonnent\*innen Ihrer Mailingliste, welche sich in der Vergangenheit aktiv bei MailChimp von Ihrer Liste abgemeldet haben (über den Abmelden-Link in Ihrer E-Mail), behalten ihren «Unsubscribed»-Status und erhalten auch nach einem neuerlichen Export aus hitobito keine E-Mails mehr von Ihnen.
-:::
+```
diff --git a/index.rst b/index.rst
@@ -0,0 +1,49 @@
+.. hitobito documentation master file, created by
+   sphinx-quickstart on Mon Aug 13 09:21:58 2018.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Benutzeranleitung für Hitobito
+==============================
+
+Hier findest du die generische Benutzerdokumentation für Hitobito.
+
+Du kannst selbst deinen Beitrag leisten und Ergänzungen vornehmen, in dem du auf Github: https://github.com/hitobito/user_documentation Korrekturen an den Anleitungsseiten vornimmst. Wenn dir das zu kompliziert ist, kannst du einfach auch Änderungen, Ergänzungen über dieses Formular: https://github.com/hitobito/user_documentation/issues/new vorschlagen.
+
+
+
+.. toctree::
+  :maxdepth: 1
+  :caption: Anleitung
+
+  docs/roles
+  docs/people_filter
+  docs/events
+  docs/tags
+  docs/mailing_lists
+  docs/invoices
+  docs/access_concept
+
+.. toctree::
+  :maxdepth: 1
+  :caption: Anbindung
+
+  docs/mailing_lists_mailchimp_export
+  docs/ebics
+  docs/two_factor_authentication
+
+.. toctree::
+  :maxdepth: 1
+  :caption: FAQ
+
+  docs/faq
+
+
+
+
+..  Indices and tables
+  ==================
+
+  * :ref:`genindex`
+  * :ref:`modindex`
+  * :ref:`search`
diff --git a/requirements.txt b/requirements.txt
@@ -1,66 +1,4 @@
-#
-# This file is autogenerated by pip-compile with python 3.10
-# To update, run:
-#
-#    pip-compile docs/requirements.in
-#
-click==8.1.3
-    # via mkdocs
-ghp-import==2.1.0
-    # via mkdocs
-griffe==0.22.0
-    # via mkdocstrings-python
-importlib-metadata==4.12.0
-    # via mkdocs
-jinja2==3.1.2
-    # via
-    #   mkdocs
-    #   mkdocstrings
-markdown==3.3.7
-    # via
-    #   markdown-include
-    #   mkdocs
-    #   mkdocs-autorefs
-    #   mkdocstrings
-    #   pymdown-extensions
-markdown-include==0.6.0
-    # via -r docs/requirements.in
-markupsafe==2.1.1
-    # via
-    #   jinja2
-    #   mkdocstrings
-mergedeep==1.3.4
-    # via mkdocs
-mkdocs==1.3.0
-    # via
-    #   -r docs/requirements.in
-    #   mkdocs-autorefs
-    #   mkdocstrings
-mkdocs-autorefs==0.4.1
-    # via mkdocstrings
-mkdocstrings[python]==0.19.0
-    # via
-    #   -r docs/requirements.in
-    #   mkdocstrings-python
-mkdocstrings-python==0.7.1
-    # via mkdocstrings
-packaging==21.3
-    # via mkdocs
-pymdown-extensions==9.5
-    # via mkdocstrings
-pyparsing==3.0.9
-    # via packaging
-python-dateutil==2.8.2
-    # via ghp-import
-pyyaml==6.0
-    # via
-    #   mkdocs
-    #   pyyaml-env-tag
-pyyaml-env-tag==0.1
-    # via mkdocs
-six==1.16.0
-    # via python-dateutil
-watchdog==2.1.9
-    # via mkdocs
-zipp==3.8.0
-    # via importlib-metadata
+sphinx==7.1.2
+sphinx-rtd-theme==1.3.0rc1
+myst_parser
+linkify-it-py