Convert docstrings & switch docs puplishing

.github/PULL_REQUEST_TEMPLATE.md

@@ -19,6 +19,6 @@
 * [ ] Unit and integration tests for the changes exist
 * [ ] Tests pass on CI and coverage does not decrease
 * [ ] Documentation reflects the changes where applicable
-* [ ] `docs/changelog/next_release/<pull request or issue id>.<change type>.rst` file added describing change
+* [ ] `mddocs/docs/changelog/next_release/<pull request or issue id>.<change type>.md` file added describing change
   (see [CONTRIBUTING.rst](https://github.com/MTSWebServices/data-rentgen/blob/develop/CONTRIBUTING.rst) for details.)
 * [ ] My PR is ready to review.

.github/workflows/changelog.yml

@@ -43,8 +43,8 @@ jobs:
 
       - name: Check changelog entry exists
         run: |
-          if [ ! -s docs/changelog/next_release/${{ github.event.pull_request.number }}.*.rst ]; then
-              echo "Please add corresponding file 'docs/changelog/next_release/<issue number>.<change type>.rst' with changes description"
+          if [ ! -s mddocs/docs/changelog/next_release/${{ github.event.pull_request.number }}.*.md ]; then
+              echo "Please add corresponding file 'mddocs/docs/changelog/next_release/<issue number>.<change type>.md' with changes description"
               exit 1
           fi
 

.github/workflows/dev-release.yml

@@ -41,7 +41,7 @@ jobs:
 
       - name: Fix logo in Readme
         run: |
-          sed -i "s#image:: docs/#image:: https://raw.githubusercontent.com/MTSWebServices/data-rentgen/$GITHUB_SHA/docs/#g" README.rst
+          sed -i "s#image:: mddocs/docs/#image:: https://raw.githubusercontent.com/MTSWebServices/data-rentgen/$GITHUB_SHA/mddocs/docs/#g" README.rst
           sed -i "s#logo_wide_white_text.svg#logo_wide.svg#g" README.rst
 
       - name: Patch version template

.github/workflows/release.yml

@@ -50,7 +50,7 @@ jobs:
 
       - name: Fix logo in Readme
         run: |
-          sed -i "s#image:: docs/#image:: https://raw.githubusercontent.com/MTSWebServices/data-rentgen/$GITHUB_SHA/docs/#g" README.rst
+          sed -i "s#image:: mddocs/docs/#image:: https://raw.githubusercontent.com/MTSWebServices/data-rentgen/$GITHUB_SHA/mddocs/docs/#g" README.rst
           sed -i "s#logo_wide_white_text.svg#logo_wide.svg#g" README.rst
 
       - name: Patch version template
@@ -68,48 +68,15 @@ jobs:
           uv pip install cyclonedx-bom
           uv export --all-extras --format requirements.txt | uv run cyclonedx-py requirements - > sbom.cyclonedx.json
 
-      - name: Get changelog
-        run: |
-          cat docs/changelog/$GITHUB_REF_NAME.rst > changelog.rst
-
-      - name: Prepare rST syntax for conversion to Markdown
-        run: |
-          # Replace Github links from Sphinx syntax with Markdown
-          sed -i -E 's/:github:issue:`(.*)`/#\1/g' changelog.rst
-          sed -i -E 's/:github:pull:`(.*)`/#\1/g' changelog.rst
-          sed -i -E 's/:github:user:`(.*)`/@\1/g' changelog.rst
-          sed -i -E 's/:github:org:`(.*)`/@\1/g' changelog.rst
-
-      - name: Convert rST to Markdown
-        uses: docker://pandoc/core:2.9
-        with:
-          args: >-
-            --output=changelog.md
-            --from=rst
-            --to=gfm
-            --wrap=none
-            changelog.rst
-
-      - name: Fixing Markdown syntax after conversion
-        run: |
-          # Replace ``` {.python caption="abc"} with ```python caption="abc"
-          sed -i -E 's/``` \{\.(.*)\}/```\1/g' changelog.md
-
-          # Replace ``` python with ```python
-          sed -i -E 's/``` (\w+)/```\1/g' changelog.md
-
-          # Replace \# with #
-          sed -i -E 's/\\#/#/g' changelog.md
-
-      - name: Get release name
+      - name: Prepare changelog
         id: release-name
         run: |
+          cat mddocs/docs/changelog/${GITHUB_REF_NAME}.md > changelog.md
+          # Remove anchors like "{ #0.5.1 }"
+          sed -i -E 's/\{.*\}//g' changelog.md
           # Release name looks like: 0.7.0 (2023-05-15)
           echo -n name= > "$GITHUB_OUTPUT"
           cat changelog.md | head -1 | sed -E "s/#+\s*//g" >> "$GITHUB_OUTPUT"
-
-      - name: Fix headers
-        run: |
           # Remove header with release name
           sed -i -e '1,2d' changelog.md
 
@@ -125,6 +92,6 @@ jobs:
           files: |-
             dist/*.tar.gz
             dist/*.whl
-            docs/_static/openapi_server.json
-            docs/_static/openapi_http2kafka.json
+            mddocs/docs/_static/openapi_server.json
+            mddocs/docs/_static/openapi_http2kafka.json
             sbom.cyclonedx.json

.gitignore

@@ -69,8 +69,8 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
+# MkDocs documentation
+mddocs/generated/
 
 # PyBuilder
 .pybuilder/

.pre-commit-config.yaml

@@ -68,7 +68,7 @@ repos:
         priority: 6
       - id: insert-license
         types: [python]
-        exclude: ^(data_rentgen/dependencies/stub.py|docs/.*\.py|tests/.*\.py)$
+        exclude: ^(data_rentgen/dependencies/stub.py|tests/.*\.py)$
         args:
           - --license-filepath
           - .spdx-license-header.txt

.readthedocs.yaml

@@ -1,5 +1,8 @@
 version: 2
 
+mkdocs:
+  configuration: mddocs/mkdocs.yml
+
 build:
   os: ubuntu-22.04
   apt_packages:
@@ -15,10 +18,9 @@ build:
       - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH python -m pip install uv
 
     post_install:
-      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --frozen --no-install-project --all-extras --no-extra gssapi --group docs
-      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv pip install --no-deps sphinx-plantuml # remove after https://github.com/zqmillet/sphinx-plantuml/pull/4
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --frozen --no-install-project --all-extras --no-extra gssapi --group mddocs
       - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH python -m pip list -v
       - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH make docs-openapi
-
-sphinx:
-  configuration: docs/conf.py
+    pre_build:
+      - python mddocs/scripts/fix_refs.py
+      - python mddocs/scripts/links2anchors.py

CONTRIBUTING.rst

@@ -70,7 +70,7 @@ And *groups* (not included into package, used locally and in CI):
 
 * ``test`` - for running tests
 * ``dev`` - for development, like linters, formatters, mypy, pre-commit and so on
-* ``docs`` - for building documentation
+* ``mddocs`` - for building documentation
 
 Enable pre-commit hooks
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -196,7 +196,7 @@ Settings are stored in ``.env.docker`` file.
 Build documentation
 ~~~~~~~~~~~~~~~~~~~
 
-Build documentation using Sphinx & open it:
+Build documentation using MkDocs & open it:
 
 .. code:: bash
 
@@ -230,7 +230,7 @@ Write release notes
 for changelog management.
 
 To submit a change note about your PR, add a text file into the
-`docs/changelog/next_release <./next_release>`_ folder. It should contain an
+`mddocs/docs/changelog/next_release <./mddocs/docs/changelog/next_release>`_ folder. It should contain an
 explanation of what applying this PR will change in the way
 end-users interact with the project. One sentence is usually
 enough but feel free to add as many details as you feel necessary
@@ -242,21 +242,18 @@ telling the readers **what changed** in a specific version of
 the library *since the previous version*.
 
 You should also use
-reStructuredText syntax for highlighting code (inline or block),
+Markdown syntax for highlighting code (inline or block),
 linking parts of the docs or external sites.
-If you wish to sign your change, feel free to add ``-- by
-:user:`github-username``` at the end (replace ``github-username``
-with your own!).
 
 Finally, name your file following the convention that Towncrier
 understands: it should start with the number of an issue or a
 PR followed by a dot, then add a patch type, like ``feature``,
-``doc``, ``misc`` etc., and add ``.rst`` as a suffix. If you
+``doc``, ``misc`` etc., and add ``.md`` as a suffix. If you
 need to add more than one fragment, you may add an optional
 sequence number (delimited with another period) between the type
 and the suffix.
 
-In general the name will follow ``<pr_number>.<category>.rst`` pattern,
+In general the name will follow ``<pr_number>.<category>.md`` pattern,
 where the categories are:
 
 - ``feature``: Any new feature. Adding new functionality that has not yet existed.
@@ -278,21 +275,15 @@ changes accompanying the relevant code changes.
 Examples for adding changelog entries to your Pull Requests
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. code-block:: rst
-    :caption: docs/changelog/next_release/1234.doc.1.rst
+.. code-block:: markdown
+    :caption: mddocs/docs/changelog/next_release/2345.bugfix.md
 
-    Added a ``:github:user:`` role to Sphinx config -- by :github:user:`someuser`
+    Fixed behavior of `server`
 
-.. code-block:: rst
-    :caption: docs/changelog/next_release/2345.bugfix.rst
+.. code-block:: markdown
+    :caption: mddocs/docs/changelog/next_release/3456.feature.md
 
-    Fixed behavior of ``server`` -- by :github:user:`someuser`
-
-.. code-block:: rst
-    :caption: docs/changelog/next_release/3456.feature.rst
-
-    Added support of ``timeout`` in ``LDAP``
-    -- by :github:user:`someuser`, :github:user:`anotheruser` and :github:user:`otheruser`
+    Added support of `timeout` in `LDAP`
 
 .. tip::
 
@@ -316,59 +307,34 @@ Release Process
 
 Before making a release from the ``develop`` branch, follow these steps:
 
-0. Checkout to ``develop`` branch and update it to the actual state
+1. Checkout to ``develop`` branch and update it to the actual state
 
 .. code:: bash
 
     git checkout develop
     git pull -p
 
-1. Backup ``NEXT_RELEASE.rst``
-
-.. code:: bash
-
-    cp "docs/changelog/NEXT_RELEASE.rst" "docs/changelog/temp_NEXT_RELEASE.rst"
-
-2. Build the Release notes with Towncrier
+2. Get current release version
 
 .. code:: bash
 
     VERSION=$(cat data_rentgen/VERSION)
-    towncrier build --version=${VERSION} --yes
-
-3. Change file with changelog to release version number
-
-.. code:: bash
-
-    mv docs/changelog/NEXT_RELEASE.rst "docs/changelog/${VERSION}.rst"
-
-4. Remove content above the version number heading in the ``${VERSION}.rst`` file
-
-.. code:: bash
-
-    awk '!/^.*towncrier release notes start/' "docs/changelog/${VERSION}.rst" > temp && mv temp "docs/changelog/${VERSION}.rst"
-
-5. Update Changelog Index
-
-.. code:: bash
-
-    awk -v version=${VERSION} '/DRAFT/{print;print "    " version;next}1' docs/changelog/index.rst > temp && mv temp docs/changelog/index.rst
 
-6. Restore ``NEXT_RELEASE.rst`` file from backup
+3. Build changelog for current release
 
 .. code:: bash
 
-    mv "docs/changelog/temp_NEXT_RELEASE.rst" "docs/changelog/NEXT_RELEASE.rst"
+    make docs-generate-changelog
 
-7. Commit and push changes to ``develop`` branch
+4. Commit and push changes to ``develop`` branch
 
 .. code:: bash
 
     git add .
     git commit -m "Prepare for release ${VERSION}"
     git push
 
-8. Merge ``develop`` branch to ``master``, **WITHOUT** squashing
+5. Merge ``develop`` branch to ``master``, **WITHOUT** squashing
 
 .. code:: bash
 
@@ -377,14 +343,14 @@ Before making a release from the ``develop`` branch, follow these steps:
     git merge develop
     git push
 
-9. Add git tag to the latest commit in ``master`` branch
+6. Add git tag to the latest commit in ``master`` branch
 
 .. code:: bash
 
     git tag "$VERSION"
     git push origin "$VERSION"
 
-10. Update version in ``develop`` branch **after release**:
+7. Update version in ``develop`` branch **after release**:
 
 .. code:: bash
 

Makefile

@@ -40,7 +40,6 @@ venv-cleanup: ##@Env Cleanup venv
 
 venv-install: ##@Env Install requirements to venv
 	${UV} sync --inexact --no-install-project --frozen --all-extras --all-groups --no-extra gssapi $(ARGS)
-	${UV} pip install --no-deps sphinx-plantuml
 
 
 db: db-start db-upgrade db-partitions ##@DB Prepare database (in docker)
@@ -135,16 +134,28 @@ prod-cleanup: ##@Application Stop production containers
 docs: docs-build docs-open ##@Docs Generate & open docs
 
 docs-build: ##@Docs Generate docs
-	$(MAKE) -C docs html
+	PYTHONPATH=. DISABLE_MKDOCS_2_WARNING=true ${VIRTUAL_ENV}/bin/mkdocs build --config-file mddocs/mkdocs.yml
 
 docs-open: ##@Docs Open docs
-	xdg-open docs/_build/html/index.html
+	xdg-open mddocs/generated/index.html
 
 docs-cleanup: ##@Docs Cleanup docs
-	$(MAKE) -C docs clean
+	rm -rf mddocs/generated/
 
 docs-fresh: docs-cleanup docs-build ##@Docs Cleanup & build docs
 
+docs-serve: ##@Docs Run docs server
+	PYTHONPATH=. DISABLE_MKDOCS_2_WARNING=true ${VIRTUAL_ENV}/bin/mkdocs serve --config-file mddocs/mkdocs.yml
+
+docs-generate-changelog: ##@Docs Generate changelog
+	cp "mddocs/docs/changelog/RELEASE_TEMPLATE.md" "mddocs/docs/changelog/temp_RELEASE_TEMPLATE.md"
+	${UV} run towncrier build "--version=$(shell cat data_rentgen/VERSION)" --yes
+	mv "mddocs/docs/changelog/RELEASE_TEMPLATE.md" "mddocs/docs/changelog/$(shell cat data_rentgen/VERSION).md"
+	mv "mddocs/docs/changelog/temp_RELEASE_TEMPLATE.md" "mddocs/docs/changelog/RELEASE_TEMPLATE.md"
+	awk '!/towncrier release notes start/' "mddocs/docs/changelog/$(shell cat data_rentgen/VERSION).md" | sed '/./,$$!d' > temp && mv temp "mddocs/docs/changelog/$(shell cat data_rentgen/VERSION).md"
+	sed "s#\(.*NEXT_RELEASE.*\)#\1\n- [$(shell cat data_rentgen/VERSION)][$(shell cat data_rentgen/VERSION)]#" "mddocs/docs/changelog/index.md" > temp && mv temp "mddocs/docs/changelog/index.md"
+	sed "s#\(.*NEXT_RELEASE.*\)#\1\n    * [$(shell cat data_rentgen/VERSION)](changelog/$(shell cat data_rentgen/VERSION).md)#" "mddocs/docs/nav.md" > temp && mv temp "mddocs/docs/nav.md"
+
 docs-openapi: ##@Docs Generate OpenAPI schema
-	${PYTHON} -m data_rentgen.server.scripts.export_openapi_schema docs/_static/openapi_server.json
-	${PYTHON} -m data_rentgen.http2kafka.scripts.export_openapi_schema docs/_static/openapi_http2kafka.json
+	${PYTHON} -m data_rentgen.server.scripts.export_openapi_schema mddocs/docs/_static/openapi_server.json
+	${PYTHON} -m data_rentgen.http2kafka.scripts.export_openapi_schema mddocs/docs/_static/openapi_http2kafka.json