Skip to content

docs: migracja z Sphinx do MkDocs Material#225

Merged
mpasternak merged 5 commits into
devfrom
worktree-docs-mkdocs-material
May 14, 2026
Merged

docs: migracja z Sphinx do MkDocs Material#225
mpasternak merged 5 commits into
devfrom
worktree-docs-mkdocs-material

Conversation

@mpasternak
Copy link
Copy Markdown
Member

@mpasternak mpasternak commented May 14, 2026

Summary

  • Konwersja całej dokumentacji RST (23 plików) na Markdown
  • Przejście z Sphinx na MkDocs Material jako build backend
  • Read the Docs nadal hostuje (.readthedocs.yaml przełączone z sphinx: na mkdocs:)
  • Pełna nawigacja zachowana, wszystkie cross-references (:ref:, :doc:) zmapowane na markdown linki
  • MathJax 3 dla wzorów matematycznych w sloty.md (zastępuje sphinx.ext.imgmath)

Co się zmieniło

Obszar Detal
Pliki źródłowe 23 .rst → 22 .md (pandoc 3.9 + custom post-processor)
Usunięte docs/conf.py, docs/Makefile, docs/make.bat
Nowe mkdocs.yml (Material theme, polski UI), docs/requirements.txt, docs/assets/mathjax-config.js
RTD .readthedocs.yaml: sphinx: → mkdocs:
Ignore .gitignore: docs/_build/ → site/

Konfiguracja MkDocs

  • Theme: Material z auto dark/light mode toggle
  • Plugins: search (en stemmer), autorefs (cross-page refs), glightbox (screenshot lightbox)
  • Extensions: admonition, attr_list, md_in_html, pymdownx (arithmatex, details, superfences, tabbed, highlight, inlinehilite, snippets), toc z permalinks
  • Math: MathJax 3 z jsdelivr CDN (bez polyfill.io — compromised w 2024), re-typeset hook dla navigation.instant
  • Slugify: Unicode-aware (anchory zawierają polskie znaki, np. #pole-skupia-pracowników)

Co już działa

  • mkdocs build --strict zielony, 0 warnings, build 0.44s
  • Wszystkie 12 wzorów LaTeX w sloty.md renderuje się jako <span class="arithmatex">\\[...\\]</span> + MathJax
  • Wszystkie admonitions (!!! note, !!! warning) i cross-references działają
  • history.md (3862 linii towncrier output) skonwertowane

Test plan

  • RTD pull request preview build: zielony (auto-trigger na push)
  • Sprawdzenie renderingu pod RTD URL (preview branch)
  • Verify nawigacja: sidebar, search, dark/light toggle
  • Verify matematyka: /sloty/#próg-nr-1 do #próg-nr-3
  • Verify cross-references: edycja_uczelnia → edycja_jednostka#pole-skupia-pracowników
  • Verify obrazki z docs/images/
  • Verify auto-loaded docs/SECURITY.md (kopia z root)

Decyzje (warto wiedzieć przed review)

  1. MathJax via CDN — zamiast bundle'a w repo (~1MB). Inne projekty (FastAPI, Pydantic) robią tak samo. Wad: zależność od dostępności jsdelivr; zalety: zero local maintenance.
  2. history.md baked — 3862 linii zaimportowane z HISTORY.rst w czasie konwersji. Towncrier nadal pisze do HISTORY.rst; po każdym release trzeba regenerować history.md (można dodać do release workflow).
  3. SECURITY.md skopiowane do docs/ — alternatywą był plugin mkdocs-include-markdown. Wybrałem prostszą drogę (jeden plik więcej, brak dodatkowej zależności).
  4. MkDocs 2.0 warning — Material for MkDocs ostrzega przed nadchodzącą wersją MkDocs 2.0 która ma być backwards-incompatible. To długoterminowe ryzyko ale obecna wersja jest production-ready.

🤖 Generated with Claude Code

mpasternak and others added 5 commits May 14, 2026 11:12
@mpasternak @claude
docs: migracja z Sphinx do MkDocs Material
1437a7d 
Konwersja całej dokumentacji RST na Markdown i przejście z Sphinxa na
MkDocs Material. Build na Read the Docs pozostaje obsługiwany (.readthedocs.yaml
przełączony na sekcję mkdocs:), nawigacja zachowana w pełni przez nav: w
mkdocs.yml.

- 23 plików .rst → 22 .md (pandoc 3.9 + custom post-processor dla GFM→Material
  admonitions i :ref:/:doc: cross-references)
- usunięte: docs/conf.py, docs/Makefile, docs/make.bat
- nowy: mkdocs.yml (Material theme, polish UI, autorefs, glightbox)
- nowy: docs/requirements.txt (mkdocs-material >= 9.5)
- docs/SECURITY.md skopiowane z root żeby SECURITY_PRACTICES.md miało target
- .readthedocs.yaml: sphinx: → mkdocs:
- .gitignore: docs/_build/ → site/

mkdocs build --strict zielony, 0 warnings.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@mpasternak @claude
docs: dodaj rendering wzorów matematycznych w sloty.md
310a075 
Pandoc skonwertował RST .. math:: bloki na GFM ``` ```math ``` co MkDocs
Material nie renderuje natywnie (w przeciwieństwie do Sphinx + imgmath).

- 12 bloków ``` ```math ``` w sloty.md → $$ ... $$ (display math)
- mkdocs.yml: włączone pymdownx.arithmatex(generic=true)
- docs/assets/mathjax-config.js: konfiguracja MathJax 3 z re-typeset
  hookiem na navigation.instant (Material instant-navigation swap-uje
  strony bez reload-a, MathJax sam by nie wpadł na re-typeset)
- MathJax 3.x ładowany z jsdelivr CDN, bez polyfill.io (compromised w 2024)

Zweryfikowane: 12/12 bloków arithmatex w renderowanym HTML pod
/sloty/#próg-nr-1 do #próg-nr-3.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@mpasternak @claude
ci: dodaj workflow Docs do weryfikacji buildu MkDocs
2ad1612 
GitHub Actions workflow uruchamiany na PR i push do dev/master gdy
zmienia sie cokolwiek w docs/, mkdocs.yml, .readthedocs.yaml lub samym
workflow.

Robi:
- mkdocs build --strict (wykrywa broken anchors, missing files, refs)
- upload site/ jako artifact (retention 7 dni — szybki preview bez
  czekania na Read the Docs)

To uzupelnienie Read the Docs build-checkow:
- RTD nie uzywa --strict (broken anchors sa tylko warningiem)
- GH Actions ~30s vs RTD ~1-2min
- artifact pozwala obejrzec docs lokalnie bez deployu

Workflow SHA-pinned (actions/checkout@de0fac2e, actions/setup-python@
a26af69b, actions/upload-artifact@330a01c4) zgodnie z wzorcem z
tests.yml i polityka security-supply-chain.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@mpasternak @claude
chore(towncrier): migracja z RST do Markdown
8999f3e 
Towncrier od dawna natywnie wspiera Markdown (patrz
https://towncrier.readthedocs.io/en/stable/markdown.html). Po migracji
docs na MkDocs Material, towncrier wciąż pisał do HISTORY.rst i
wymagał ręcznej konwersji — gap, ktorego nie wyłapaliśmy w pierwszym
commicie migracji.

Zmiany:

- HISTORY.rst → HISTORY.md (jednorazowa konwersja pandocem 3.9
  + ręczne wstawienie markera "<!-- towncrier release notes start -->")
- pyproject.toml [tool.towncrier]:
  - filename = "HISTORY.md"
  - start_string = "<!-- towncrier release notes start -->\n"
  - underlines = ["", "", ""]  (Markdown nie ma underlines)
  - title_format = "## bpp {version} ({project_date})"
  - issue_format = "[#{issue}](https://github.com/iplweb/bpp/issues/{issue})"
- 9 newsfragments rename .rst → .md (content bez zmian — `` ``literal`` ``
  jest legalnym CommonMark code-spanem i renderuje tak samo)
- docs/history.md: 3862 linii baked content → 1-linijka
  `{% include-markdown "../HISTORY.md" %}`. HISTORY.md jest single
  source of truth; towncrier pisze do root, MkDocs pull-uje dynamicznie.
- mkdocs.yml: dodany plugin `include-markdown`
- docs/requirements.txt: + mkdocs-include-markdown-plugin>=7.1
- pyproject.toml: usuniety Sphinx>=7,<9 z dev-deps (juz nieuzywany
  po migracji docs na MkDocs)

Weryfikacja:
- mkdocs build --strict zielony
- towncrier build --draft --version 9999.dev renderuje 9 fragmentow
  w prawidlowym Markdown formacie z naszym title_format

Po tym commicie release flow jest spojny:
1. towncrier build (uses HISTORY.md as canonical)
2. mkdocs build (HISTORY.md → docs/history.md via include)
3. RTD/GH Actions buduja docs z up-to-date release notes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@mpasternak @claude
ci: zamien uv-secure na pip-audit (uv-secure archived w kwietniu 2026)
ac31824 
owenlamont/uv-secure zostal zarchiwizowany 2026-04-18 (read-only repo,
0 issues, ostatnie release v0.17.2 z tego samego dnia). Archived security
scanner to anti-pattern: brak update'ow bazy CVE = false sense of security.

Obecny symptom na PR-ach: `Error: brotli raised exception:` (exit 3) -
prawdopodobnie upstream rot, PyPI advisory feed zmienil sposob encoding-u,
a uv-secure nie ma juz maintainera ktory to naprawi.

Zamiennik: pip-audit (PyPA-official, autorzy pip-a). Aktywnie maintained,
czyta z tego samego PyPI Advisory DB co uv-secure plus opcjonalnie OSV.dev.

Polityka gate-a: failure na vuln z fix-em dostepnym (fix_versions non-empty).
pip-audit nie ma natywnego severity-flagi (w przeciwienstwie do uv-secure),
ale fix-availability jest dobrym proxy: skoro upstream wypuscil fix, warto
bumpnac. Vuln bez fixa idzie do job summary jako warning.

Whitelist (CVE-2026-42304 / GHSA-grgv-6hw6-v9g4):
- DoS w twisted.names DNS module
- BPP nie uruchamia twisted DNS-servera (twisted to transitive dep daphne+
  autobahn dla WebSocket/Channels, modul twisted.names niewykorzystany)
- Fix tylko w 26.4.0rc2 (RC, nie idziemy z RC do prod)
- Re-evaluate przy stable twisted 26.x

Multi-scanner backup (OSV/Grype/Trivy) bez zmian - report-only,
defense-in-depth dla wykrycia rzeczy ktorych pip-audit moze nie miec
(rozne CVE bazy).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@mpasternak mpasternak merged commit 87a76da into dev May 14, 2026
20 checks passed
@mpasternak mpasternak deleted the worktree-docs-mkdocs-material branch May 14, 2026 10:14
mpasternak added a commit that referenced this pull request May 14, 2026
@mpasternak @claude
chore(deps): remove Sphinx transitive deps from uv.lock
a58ec0d 
Follow-up po PR #225 (migracja docs Sphinx → MkDocs Material). W tamtym
commicie chore(towncrier): pyproject.toml stracił `Sphinx>=7,<9` z
dev-deps, ale uv.lock nie zostal zregenerowany - przez co `uv sync`
nadal instalowal ~13 transitive paczek Sphinxa (~3MB w .venv).

Usuniete:
- sphinx
- alabaster
- babel
- imagesize
- roman-numerals + roman-numerals-py
- snowballstemmer
- sphinxcontrib-applehelp
- sphinxcontrib-devhelp
- sphinxcontrib-htmlhelp
- sphinxcontrib-jsmath
- sphinxcontrib-qthelp
- sphinxcontrib-serializinghtml

Trywialna mechaniczna zmiana, `uv lock` regenerowal lockfile.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@mpasternak