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. |
Create your new repository for the new documentation set, or ask someone to create one for you. You can host this repository anywhere but we recommend using Fedora Forge where you can use Fedora groups to control write access to the repository.
Simply clone the template repository manually and copy the content to your new repository.
📄 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.
Documentation modules published on docs.fp-o are all listed in the main Antora playbook.
Para adicionar um novo módulo de documentação, você precisará adicionar seu repositório à lista content.sources:
content:
sources:
- url: https://forge.fedoraproject.org/path/to/new/repository.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. |
You can either create a Pull Request with these changes, or if you do not feel comfortable editing this file, create a ticket on the Fedora Docs Website repository, and the Documentation Team will handle that part for you.
|
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 ›