containers/podman

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

Open

#19 701 ouverte le 22 août 2023

Voir sur GitHub
 (4 commentaires) (0 réactions) (0 assignés)Go (3 107 forks)batch import
ContribfestGood First Issuedocumentationkind/feature

Métriques du dépôt

Stars
 (31 686 stars)
Métriques de merge PR
 (Aucune PR mergée en 30 j)

Description

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

Guide contributeur

Direction de recherche
Examinez la configuration Sphinx dans docs/source/conf.py et ajoutez une substitution regex pour convertir 'podman foo(N)' en liens cliquables pour la sortie HTML, en vérifiant si le fichier .md correspondant existe.
Stack technique
python
Domaine
documentation
Type d'issue
Documentation
DifficultéDifficulté estimée pour un nouveau contributeur, de 1 pour un très petit changement à 5 pour un travail expert.
2
Temps estiméFourchette de temps approximative pour investiguer, implémenter, tester et préparer une pull request.
1-3 heures
Statut d'activitéDisponibilité apparente de l'issue : fraîche, active, ancienne, bloquée ou en attente d'un mainteneur.
Active
ClartéClarté avec laquelle l'issue explique le changement attendu, les critères d'acceptation et la prochaine étape.
Claire
Prérequis
PythonSphinxregex
Accessibilité débutantScore de 1 à 100 estimant l'accessibilité de cette issue pour un premier contributeur.
65