change .readthedocs.yaml to switch publishing docs from rst to markdown

.github/workflows/changelog.yml

@@ -40,12 +40,12 @@ jobs:
 
       - name: Install dependencies
         run: |
-          uv sync --frozen --group docs
+          uv sync --frozen --group mddocs
 
       - 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/release.yml

@@ -12,7 +12,7 @@ jobs:
   release:
     name: Release package
     runs-on: ubuntu-latest
-    if: github.repository == 'MTSWebServices/syncmaster'  # prevent running on forks
+    if: github.repository == 'MTSWebServices/syncmaster' # prevent running on forks
 
     environment:
       name: pypi
@@ -44,7 +44,7 @@ jobs:
 
       - name: Fix logo in Readme
         run: |
-          sed -i "s#image:: docs/#image:: https://raw.githubusercontent.com/MTSWebServices/syncmaster/$GITHUB_SHA/docs/#g" README.rst
+          sed -i "s#image:: mddocs/docs/#image:: https://raw.githubusercontent.com/MTSWebServices/syncmaster/$GITHUB_SHA/mddocs/docs/#g" README.rst
           sed -i "s#logo_wide_red_text.svg#logo_wide.svg#g" README.rst
 
       - name: Patch version template
@@ -62,48 +62,16 @@ 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: |
-          # Release name looks like: 0.7.0 (2023-05-15)
+          cat mddocs/docs/changelog/${GITHUB_REF_NAME}.md > changelog.md
+          # Remove anchors like "{ #syncmaster-changelog-0-3-4 }"
+          sed -i -E 's/\{.*\}//g' changelog.md
+          # Header looks like "## [0.3.4](...) - 2026-05-26"
+          # Release name looks like "0.3.4 - 2026-05-26"
           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
 
@@ -119,5 +87,5 @@ jobs:
           files: |
             dist/*.tar.gz
             dist/*.whl
-            docs/_static/openapi.json
+            mddocs/docs/_static/openapi.json
             sbom.cyclonedx.json

.readthedocs.yaml

@@ -1,22 +1,19 @@
 version: 2
 
+mkdocs:
+  configuration: mddocs/mkdocs.yml
+
 build:
-  os: ubuntu-22.04
-  apt_packages:
-    - make
+  os: ubuntu-24.04
   tools:
-    python: '3.13'
+    python: '3.11'
   jobs:
-    post_checkout:
-      - git fetch --unshallow || true
     post_create_environment:
       - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH python -m pip install uv
     post_install:
-      # avoid instaling worker dependencies
-      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --no-install-project --extra server --extra scheduler --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 --no-install-project --extra server --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

@@ -230,17 +230,13 @@ Settings are stored in ``config.yml`` file.
 Build documentation
 ~~~~~~~~~~~~~~~~~~~
 
-Build documentation using Sphinx & open it:
+Build documentation using mkdocs:
 
 .. code:: bash
 
-    make docs
+    make docs-serve
 
-If documentation should be build cleanly instead of reusing existing build result:
-
-.. code:: bash
-
-    make docs-fresh
+Then open in browser ``http://localhost:8000/``.
 
 Create pull request
 ~~~~~~~~~~~~~~~~~~~
@@ -264,7 +260,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 <./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
@@ -275,22 +271,15 @@ combined with others, it will be a part of the "news digest"
 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),
-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.
@@ -312,21 +301,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
-
-    Added a ``:github:user:`` role to Sphinx config -- by :github:user:`someuser`
-
-.. code-block:: rst
-    :caption: docs/changelog/next_release/2345.bugfix.rst
+.. code-block:: markdown
+    :caption: mddocs/docs/changelog/next_release/2345.bugfix.md
 
-    Fixed behavior of ``server`` -- by :github:user:`someuser`
+    Fixed behavior of `server`
 
-.. code-block:: rst
-    :caption: docs/changelog/next_release/3456.feature.rst
+.. code-block:: markdown
+    :caption: mddocs/docs/changelog/next_release/3456.feature.md
 
-    Added support of ``timeout`` in ``LDAP``
-    -- by :github:user:`someuser`, :github:user:`anotheruser` and :github:user:`otheruser`
+    Added support of `timeout` in `LDAP`
 
 .. tip::
 
@@ -350,59 +333,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 syncmaster/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
 
@@ -411,14 +369,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

@@ -37,7 +37,6 @@ venv-cleanup: ##@Env Cleanup venv
 
 venv-install: ##@Env Install requirements to venv
 	${UV} sync --inexact --frozen --extra "server" --extra "scheduler" --extra "worker" --all-groups $(ARGS)
-	${UV} pip install --no-deps sphinx-plantuml
 
 
 
@@ -175,21 +174,27 @@ prod-cleanup: ##@Application Stop production containers
 docs: docs-build docs-open ##@Docs Generate & open docs
 
 docs-build: ##@Docs Generate docs
-	${UV} run $(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-openapi: ##@Docs Generate OpenAPI schema
-	${PYTHON} -m syncmaster.server.scripts.export_openapi_schema docs/_static/openapi.json
+docs-serve: ##@Docs Run docs server
+	PYTHONPATH=. DISABLE_MKDOCS_2_WARNING=true ${VIRTUAL_ENV}/bin/mkdocs serve --config-file mddocs/mkdocs.yml
 
-mddocs-build: mddocs-openapi ##@Docs Generate mkdocs documentation
-	PYTHONPATH=. DISABLE_MKDOCS_2_WARNING=true ${VIRTUAL_ENV}/bin/mkdocs build --strict --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 syncmaster/VERSION)" --yes
+	mv "mddocs/docs/changelog/RELEASE_TEMPLATE.md" "mddocs/docs/changelog/$(shell cat syncmaster/VERSION).md"
+	mv "mddocs/docs/changelog/temp_RELEASE_TEMPLATE.md" "mddocs/docs/changelog/RELEASE_TEMPLATE.md"
+	awk '/##/,0' "mddocs/docs/changelog/$(shell cat syncmaster/VERSION).md" > temp && mv temp "mddocs/docs/changelog/$(shell cat syncmaster/VERSION).md"
+	sed "s#\(.*NEXT_RELEASE.*\)#\1\n- [$(shell cat syncmaster/VERSION) ($(shell date --rfc-3339=date))][$(shell cat syncmaster/VERSION | tr '.' '-')]#" "mddocs/docs/changelog/index.md" > temp && mv temp "mddocs/docs/changelog/index.md"
+	sed "s#\(.*NEXT_RELEASE.*\)#\1\n    * [$(shell cat syncmaster/VERSION)](changelog/$(shell cat syncmaster/VERSION).md)#" "mddocs/docs/nav.md" > temp && mv temp "mddocs/docs/nav.md"
 
-mddocs-openapi: ##@Docs Generate OpenAPI schema for mkdocs documentation
+docs-openapi: ##@Docs Generate OpenAPI schema
 	${PYTHON} -m syncmaster.server.scripts.export_openapi_schema mddocs/docs/_static/openapi.json

README.rst

@@ -2,7 +2,7 @@
 
 |Logo|
 
-.. |Logo| image:: docs/_static/logo_wide_red_text.svg
+.. |Logo| image:: mddocs/docs/_static/logo_wide_red_text.svg
     :alt: Data.SyncMaster logo
     :target: https://github.com/MTSWebServices/data-syncmaster
 

docker-compose.test.yml

@@ -63,7 +63,7 @@ services:
     volumes:
       - ./config.docker.yml:/app/config.yml
       - ./syncmaster:/app/syncmaster
-      - ./docs/_static:/app/docs/_static
+      - ./docs/_static:/app/mddocs/docs/_static
       - ./reports:/app/reports
       - ./tests:/app/tests
       - ./pyproject.toml:/app/pyproject.toml
@@ -105,7 +105,7 @@ services:
       dockerfile: docker/Dockerfile.worker
       context: .
       target: test
-    command: --queues 123-test_queue  # Queue slug
+    command: --queues 123-test_queue # Queue slug
     entrypoint: [coverage, run, -m, celery, -A, tests.test_integration.celery_test, worker, --max-tasks-per-child=1]
     env_file: .env.docker.test
     environment:
@@ -320,18 +320,18 @@ services:
       metastore-hive:
         condition: service_healthy
     ports:
-      - 9820:9820  # HDFS IPC
-      - 9870:9870  # HDFS WebHDFS
-      - 8088:8088  # Yarn UI
-      - 8042:8042  # NodeManager UI
-      - 10000:10000  # Hive server
-      - 10002:10002  # Hive server Admin UI
-      - 19888:19888  # MapReduce JobServer History UI
-      - 9083:9083  # Hive Metastore server
+      - 9820:9820 # HDFS IPC
+      - 9870:9870 # HDFS WebHDFS
+      - 8088:8088 # Yarn UI
+      - 8042:8042 # NodeManager UI
+      - 10000:10000 # Hive server
+      - 10002:10002 # Hive server Admin UI
+      - 19888:19888 # MapReduce JobServer History UI
+      - 9083:9083 # Hive Metastore server
       - 9864:9864 # Datanode UI
     environment:
       TZ: UTC
-      WITH_HIVE_SERVER: 'false'  # We leave only the metastore server, we don’t need Hive itself, we don’t waste resources on it
+      WITH_HIVE_SERVER: 'false' # We leave only the metastore server, we don’t need Hive itself, we don’t waste resources on it
       HIVE_METASTORE_DB_URL: jdbc:postgresql://metastore-hive:5432/metastore
       HIVE_METASTORE_DB_DRIVER: org.postgresql.Driver
       HIVE_METASTORE_DB_USER: test_hive