containers/podman

RFE: docs: linkify 'podman-foo(1)'

Open

#19.701 aperta il 22 ago 2023

Vedi su GitHub
 (4 commenti) (0 reazioni) (0 assegnatari)Go (3107 fork)batch import
ContribfestGood First Issuedocumentationkind/feature

Metriche repository

Star
 (31.686 star)
Metriche merge PR
 (Nessuna PR mergiata in 30 g)

Descrizione

Feature request description

#19695 gave me a taste for how tricky and inconsistent our docs are. We do not have useful doc links. We should.

Any time a doc page says 'podman-foo(1)', it should be a clickable link in the HTML pages. (Man pages, there's nothing we can do).

Suggest potential solution

Sphinx seems to be able to filter: https://github.com/containers/podman/blob/f38668e3220650630d3fab9df490bc1c2849b16e/docs/source/conf.py#L83-L94

It should be possible to do:

    re.sub('podman-foo-paren-N-closeparen', code{if podman-foo.N.md exists, convert to '[podman-foo(N)](podman-foo.N.md)' , else, leave it alone)

Have you considered any alternatives?

Could also be done in hack/markdown-preprocess, but that would only handle .md.in files

Additional context

No response

Guida contributor

Direzione di ricerca
Esamina la configurazione di Sphinx in docs/source/conf.py e aggiungi una sostituzione regex per convertire 'podman foo(N)' in link cliccabili per l'output HTML, verificando se il file .md corrispondente esiste.
Tech stack
python
Dominio
documentation
Tipo issue
Documentazione
DifficoltàQuanto dovrebbe essere impegnativa per un nuovo contributor.
2
Tempo stimatoTempo stimato per completare e verificare uno scope piccolo.
1-3 ore
Stato attivitàQuanto è probabile che la issue sia ancora attiva e reviewable.
Attiva
ChiarezzaQuanto chiaramente la issue descrive problema, scope e risultato atteso.
Chiara
Prerequisiti
PythonSphinxregex
Adatta ai principiantiQuanto la issue è adatta a contributor alla prima esperienza.
65