Documentation: mkdocs is set for a breaking change. Time to move on?

Aperta
#5,870 4 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Documentazione
Chiarezza
Da chiarire
Stato di attività
Tranquilla
Stack tecnologico
github-actions
Ambito
build-system, documentation

Direzione di ricerca

Inizia da .github/workflows/docs.yml e rivedi le sue dipendenze mkdocs, mkdocs-material, mkdocs-git-revision-date-localized-plugin e mkdocs-mermaid2-plugin. Confronta le opzioni ProperDocs, mkdocs-materialx, Fumadocs e Zensical descritte nell’issue, incluso l’impatto della migrazione. L’issue non definisce un’opzione di destinazione né criteri di accettazione, quindi per considerare il lavoro completato sarebbe prima necessario concordare l’ambito della migrazione.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Hello, I came across this library due to it deciding to build from source (just NixOS things), and noticed that it using mkdocs in the documentation workflow.

I hate to be the bearer of bad news, but mkdocs (imo) is currently imploding due to an upcoming v2 release which breaks all plugin compatibility (your workflow also seems to depend upon mkdocs-material, mkdocs-git-revision-date-localized-plugin, and mkdocs-mermaid2-plugin). At the very least, mkdocs-material is now in maintenance mode, and are creating a new system from the ground up.

With this in mind, it is probably worth considering a migration to an alternative. I am planning on the same for many of my projects, and so am happy to share my current knowledge of the options.

  • ProperDocs is a fork of mkdocs@1, which should maintain plugin compatibility. Plugin authors are encouraged to support it explicitly, but it does work without explicit support from plugin authors (if you don't mind having a heavier dependency tree).
  • mkdocs-materialx as a replacement for mkdocs-material, which should be compatible with properdocs.

Other options such as Fumadocs (JS ecosystem alternative), or Zensical (rewrite linked above) would probably require a much more-complex migration process.

Lingua principale
C
Stelle
7.6k
Fork
1.7k
Merge medio
1g 3h
PR unite (30g)
42

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di OpenMathLib/OpenBLAS

Tutte le issue di OpenMathLib/OpenBLAS

Issue simili

Altre issue su C

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.