Ein Sphinx-Builder-Plugin, das Dokumentation als [DokuWiki](https://www.dokuwiki.org/)-Markup ausgibt.
- Python 99.3%
- Makefile 0.7%
| example | ||
| sphinxcontrib | ||
| tests | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
sphinxcontrib-dokuwiki-builder
Ein Sphinx-Builder-Plugin, das Dokumentation als DokuWiki-Markup ausgibt.
Installation
pip install sphinxcontrib-dokuwiki-builder
Oder direkt aus dem Quellcode:
pip install -e /pfad/zum/sphinxcontrib-dokuwiki-builder
Aktivierung
In conf.py des Sphinx-Projekts:
extensions = ["sphinxcontrib.dokuwiki_builder"]
Verwendung
Mit sphinx-build
sphinx-build -b dokuwiki docs docs/_build/dokuwiki
Mit dem Standard-Sphinx-Makefile
Das Standard-Sphinx-Makefile (ab Sphinx 7) unterstützt einen Catch-all, sodass gilt:
make dokuwiki
Falls das Makefile keinen Catch-all-Target hat, kann man das Target manuell ergänzen:
dokuwiki:
$(SPHINXBUILD) -M dokuwiki $(SOURCEDIR) $(BUILDDIR) $(SPHINXOPTS) $(O)
Oder direkt:
sphinx-build -b dokuwiki docs docs/_build/dokuwiki
Ausgabe
Für jedes RST-Quelldokument wird eine .txt-Datei im Ausgabeordner erzeugt, die DokuWiki-Markup enthält. Die Verzeichnisstruktur entspricht der des Sphinx-Projekts.
Beispiel:
Eingabe (docs/) |
Ausgabe (_build/dokuwiki/) |
|---|---|
index.rst |
index.txt |
guide/install.rst |
guide/install.txt |
api/reference.rst |
api/reference.txt |
Syntax-Mapping
| RST-Element | DokuWiki-Syntax |
|---|---|
| Titel Level 1 | ====== Titel ====== |
| Titel Level 2 | ===== Titel ===== |
| Titel Level 3 | ==== Titel ==== |
| Titel Level 4 | === Titel === |
| Titel Level 5 | == Titel == |
| Absatz | Text, getrennt durch Leerzeile |
| Fett | **text** |
| Kursiv | //text// |
Inline-Code |
''code'' |
| Code-Block | <code>\n...\n</code> |
| Code-Block mit Sprache | <code python>\n...\n</code> |
| Aufzählung (Bullet) | * item |
| Aufzählung (Nummeriert) | - item |
| Verschachtelte Listen | Zusätzliche Leerzeichen als Einrückung |
| Externer Link | [[https://example.com|Label]] |
| Interner Link | [[seite|Label]] |
| Bild | {{path|alt}} |
| Bild mit Breite | {{path?WIDTHpx|alt}} |
| Tabelle (Header) | ^ Spalte1 ^ Spalte2 ^ |
| Tabelle (Zeile) | | Zelle1 | Zelle2 | |
| Hinweis (note) | > **Hinweis:** ... |
| Warnung (warning) | > **Warnung:** ... |
| Blockzitat | > Text |
| toctree | Linkliste (DokuWiki-Seiten) |
Konfiguration
Folgende Konfigurationswerte können in conf.py gesetzt werden:
| Option | Standard | Beschreibung |
|---|---|---|
dokuwiki_file_suffix |
".txt" |
Dateiendung für Ausgabedateien |
dokuwiki_code_block_tag |
"code" |
HTML-Tag für Code-Blöcke (code oder file) |
dokuwiki_namespace_separator |
"/" |
Trennzeichen für Namespace in internen Links |
Beispiel:
# conf.py
dokuwiki_file_suffix = ".txt"
dokuwiki_code_block_tag = "code"
dokuwiki_namespace_separator = ":"
Limitierungen
- Statische Dateien: Statische Dateien (Bilder, CSS, JS) werden nicht in den Ausgabeordner kopiert. Bildpfade werden so übernommen, wie sie im Quelltext stehen.
- Komplexe RST-Elemente: Einige RST-Elemente (z. B. Fußnoten, Zitate, Glossar, Beschreibungslisten mit komplexer Verschachtelung) werden vereinfacht oder als Plaintext ausgegeben.
- DokuWiki-Namespaces: Wenn DokuWiki-Namespaces (mit
:als Trennzeichen) statt Dateipfaden genutzt werden sollen, mussdokuwiki_namespace_separator = ":"gesetzt werden. - Rohe Docutils-Nodes:
raw-Nodes werden ignoriert, um unerwartete HTML-Fragmente in DokuWiki-Seiten zu vermeiden. - Extensions/Plugins: Sphinx-spezifische Erweiterungen (autodoc, autosummary etc.) werden unterstützt, sofern sie Standard-Docutils-Nodes erzeugen. Spezielle Nodes dieser Extensions werden ggf. auf ihre Kinder-Nodes zurückgefallen.
Entwicklung & Tests
pip install -e ".[dev]"
pytest -q
Lizenz
MIT – siehe LICENSE.