diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 3c6fac5..78e716c 100644 --- 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 index 4e2353a..5214281 100644 --- 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 deleted file mode 100644 index 106f5f9..0000000 --- a/SUMMARY.md +++ /dev/null @@ -1,3 +0,0 @@ -# Table of contents - -* [hitobito Standard](README.md) diff --git a/conf.py b/conf.py index f162d94..6e4c937 100644 --- 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", +] \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index f7b8f28..0000000 --- a/docs/index.md +++ /dev/null @@ -1,46 +0,0 @@ -% 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: Korrekturen an den Anleitungsseiten vornimmst. Wenn dir das zu kompliziert ist, kannst du einfach auch Änderungen, Ergänzungen über dieses Formular: vorschlagen. - -```{toctree} -:caption: Anleitung -:maxdepth: 3 - -roles -people_filter -events -tags -mailing_lists -invoices -access_concept -``` - -```{toctree} -:caption: Anbindung -:maxdepth: 3 - -mailing_lists_mailchimp_export -ebics -two_factor_authentication -``` - -```{toctree} -:caption: FAQ -:maxdepth: 3 - -faq -``` - -% Indices and tables -% ================== -% -% * :ref:`genindex` -% * :ref:`modindex` -% * :ref:`search` diff --git a/docs/invoices.md b/docs/invoices.md index baab00f..4523a4d 100644 --- 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 index 1c09214..9259d9f 100644 --- 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,9 +38,9 @@ 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 ``` @@ -48,6 +48,6 @@ Bitte beachte, dass der Export deine verknüpfte Liste in MailChimp überschreib 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 new file mode 100644 index 0000000..83da296 --- /dev/null +++ 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 index 8f0f216..ffa9f4f 100644 --- 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 \ No newline at end of file +sphinx==7.1.2 +sphinx-rtd-theme==1.3.0rc1 +myst_parser +linkify-it-py \ No newline at end of file