containers/podman

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

Open

#19.701 aberto em 22 de ago. de 2023

Ver no GitHub
 (4 comments) (0 reactions) (0 assignees)Go (3.107 forks)batch import
ContribfestGood First Issuedocumentationkind/feature

Métricas do repositório

Stars
 (31.686 stars)
Métricas de merge de PR
 (Nenhuma PRs mesclada em 30d)

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

Guia do colaborador

Direção de pesquisa
Examine a configuração do Sphinx em docs/source/conf.py e adicione uma substituição regex para converter 'podman foo(N)' em links clicáveis para saída HTML, verificando se o arquivo .md correspondente existe.
Pilha de tecnologia
python
Domain
documentation
Tipo Issue
Documentação
DifficultyDificuldade de implementação estimada para um novo contribuidor, de 1 para alterações muito pequenas a 5 para trabalho de nível especializado.
2
Tempo estimadoUm intervalo de tempo aproximado para um colaborador experiente investigar, implementar, testar e preparar um pull request.
1-3 horas
Status da atividadeQuão disponível o issue aparece agora: novo, ativo, obsoleto, bloqueado ou aguardando entrada do mantenedor.
Ativo
ClarityCom que clareza o issue explica a mudança esperada, os critérios de aceitação e a próxima etapa.
Claro
Prerequisites
PythonSphinxregex
Simpatia para novatosUma pontuação de 1 a 100 que estima o quão acessível este issue é para colaboradores iniciantes.
65