Consider moving to MkDocs
Offen
Dieses Issue hat noch niemand übernommen.
- Vorherrschende Sprache
- Python
- Sterne
- 13
- Forks
- 18
- Ø Merge
- 2 Std. 42 Min.
- Gemergte PRs (30 T.)
- 5
Beschreibung
Just an idea. Pros:
- Simpler stack, simpler config.
- Markdown has won. People don't know reST, even myself, after years of using it, still make the most basic mistakes and need to lookup the most basic stuff.
- Also supported by RTD.
- Has the Material theme, which is modern, under active development, flexible, has dark theme, etc.
- Is used at other projects, such as python.cz or junior.guru, so know-how would be shared (contributions, maintenance).
Cons:
- We extend Sphinx and would need to rewrite those things.
- We use reST extensively. I'm not sure we can port it 1:1 (but is it necessary?)
How:
- This can happen gradually. Our current setup supports Markdown, so texts can be converted first and we would see.
- I already moved from builtin Sphinx link check to Lychee, as it works better.
Beitragsleitfaden
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Öffne einen Pull Request, der die Issue-Nummer nennt.
Rechercherichtung
Überprüfe die aktuelle Sphinx-Konfiguration sowie die vorhandene Markdown- und reST-Dokumentation und vergleiche anschließend die benutzerdefinierten Erweiterungen mit MkDocs und dessen Material-Theme. Prüfe die vorhandene Lychee-Konfiguration zur Linkprüfung und die Machbarkeit einer schrittweisen Markdown-Konvertierung. Im Issue werden weder Dateien noch Akzeptanzkriterien genannt, daher müssen der vereinbarte Migrationsumfang und die Definition of Done noch festgelegt werden.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- markdown
- Bereich
- documentation
- Issue-Typ
- Feature
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Aktivitätsstatus
- Veraltet
- Klarheit
- Muss geklärt werden
- Anfängerfreundlichkeit
- 20/100