Criar um novo módulo de documentação
Esta seção descreve como adicionar uma documentação completamente nova que cubra uma nova área em sua totalidade. Isso abrange várias páginas e geralmente está associado à criação de um novo repositório dedicado. Um ambiente de trabalho local é mais adequado para isso. Mas também é possível usar o IDE web de várias forjas do GIT.
Antes de começar a seguir este procedimento, revise todos os requisitos listados em Pré-requisitos.
Configuração do repositório de documentação
| Embora você possa criar um novo repositório ou usar um existente, recomendamos começar pelo repositório de modelo fornecido se você não estiver familiarizado com o Antora. |
Crie seu novo repositório para o novo conjunto de documentação ou peça a alguém para criar um para você. Você pode hospedar este repositório em qualquer lugar, mas recomendamos usar GitLab onde você pode usar grupos do Fedora para controlar o acesso de gravação ao repositório. Dependendo do tópico, pode ser preferível hospedá-lo no espaço de nomes da Documentação do Fedora.
No GitLab, você pode usar New project > Create from template > Group e escolher Documentation Template na lista.
Se você não estiver usando o GitLab, clone o repositório de modelos manualmente e copie o conteúdo para seu novo repositório.
📄 antora.yml
📄 site.yml
📂 modules
📂 ROOT
📄 nav.adoc
📂 pages
📄 index.adoc
📄 another-page.adoc
No novo repositório, edite o arquivo de configuração antora.yml na raiz do repositório. O arquivo contém comentários que indicam quais partes você precisa alterar. No mínimo, sempre altere name e title.
O nome (name) é o que definirá a URL final da sua documentação. No exemplo: docs.fedoraproject.org/en-US/<name>/
|
Além disso, edite o arquivo de configuração site.yml. Observe que este arquivo é usado apenas ao construir uma visualização local de seu conjunto de conteúdo – no site, ele é substituído pela configuração do site.yml global. As únicas diretivas que você precisa editar neste arquivo são title e start_page.
Neste ponto, a configuração inicial está concluída. Você pode enviar essas alterações para o repositório recém-criado (ou fazer uma pull request se não tiver os direitos necessários) e começar a escrever a documentação real.
Escrevendo documentação
Alguns links úteis de documentação:
Se a sua documentação é composta por várias páginas, você pode listá-las no nav.adoc. Este arquivo será então usado para construir o menu de navegação no lado esquerdo do docs.fp-o.
Enquanto escreve, você pode usar local preview para verificar o documento resultante.
Publicar um novo módulo de documentação
Depois que o repositório estiver configurado e o conteúdo inicial adicionado, ele estará pronto para ser publicado.
Os módulos de documentação publicados em docs.fp-o estão todos listados em playbook principal do Antora .
Para adicionar um novo módulo de documentação, você precisará adicionar seu repositório à lista content.sources:
content:
sources:
- url: https://gitlab.com/caminho/para/novo/repositório.git
branches: main (1)
start_path: docs (2)
| 1 | O branch padrão é definido como master. Se o seu repositório estiver usando qualquer outro nome (main por exemplo), você precisará especificá-lo aqui. <.> Esta configuração é opcional. Se os arquivos de documentação estiverem armazenados em um subdiretório em seu repositório (/docs/, por exemplo), você deve definir seu caminho relativo aqui, sem barras iniciais ou finais. Se estiver localizado no nível raiz, conforme documentado nesta página, você poderá omitir esse parâmetro. |
Você pode criar uma Merge Request com essas alterações ou, se não se sentir confortável em editar esse arquivo, crie um ticket no https://gitlab.com/fedora/docs/docs-website/docs-fp-o/- /issues[repositório do site Documentação do Fedora], e a equipe de documentação cuidará dessa parte para você.
|
Se você não receber nenhuma atualização em sua merge request ou ticket após 5 dias, entre em contato com a Equipe de Documentação. |
Want to help? Learn how to contribute to Fedora Docs ›