pyvec / pyvec/docs.pyvec.org

Consider moving to MkDocs

Offen
#434 11 Kommentare 4 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

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

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Ö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

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.