Crie e publique novos sites de documentação

Esta seção descreve como criar e publicar nova documentação ao site docs.ferodaproject.org. Antes de começar a seguir este procedimento, reveja todos os requisitos listados em Pré-requisitos.

Antes de criar um novo site de documentação, consulte primeiro a lista de discussão. Isso é para garantir que possamos publicar o seu trabalho e você não desperdice seu tempo.

  1. Clone o repositório modelo: https://pagure.io/fedora-docs/template

  2. Crie um 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 é recomendado hospedá-lo no pagure.io onde você pode reutilizar grupos Fedora para controlar o acesso de escrita ao repositório. Dependendo do tópico, também pode ser melhor hospedá-lo no fedora-docs.

  3. Clone o repositório recém-criado para seu conjunto de conteúdo.

  4. Copie o conteúdo do repositório de modelo (sem o diretório .git) para o repositório recém-criado ou importe o histórico de commit a partir do repositório de modelos.

  5. 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.

  6. 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 em todo o site. As únicas diretivas que você precisa editar neste arquivo são title e start_page.

  7. Nesse ponto, quando a configuração inicial for concluída e o repositório estiver configurado com o nome correto e outras diretivas necessárias, efetue push dessas alterações para o repositório recém-criado (ou faça uma pull request se não puder efetuar push diretamente). Este conjunto de alterações será necessário para quaisquer outras contribuições, portanto, certifique-se de que elas sejam feitas o mais cedo possível.

  8. Faça um fork do novo repositório, para que você não efetue o push das atualizações diretamente para ele.

  9. Comece a adicionar o conteúdo real do ASCIIDoc. Durante a escrita, certifique-se de que seus novos arquivos de origem estejam incluídos no arquivo de configuração nav.adoc do módulo que você está usando (./modules/ROOT/ por padrão, a localização mudará com base em o que você configurou em antora.yml anteriormente). Certifique-se também de usar pré-visualização local com frequência para verificar sua marcação.

  10. Uma vez finalizada, efetue o commit de suas alterações e o push delas para seu fork.

  11. Use o Pagure para fazer uma pull request de seu fork ao branch master do repositório principal.

  12. Alguém verá sua pull request e a mesclará ou fornecerá feedback se houver algo que você deva alterar. Trabalhe com as pessoas que estão comentando para garantir que suas contribuições estejam de acordo com os padrões.

  13. Seu novo conteúdo precisará ser publicado pela primeira vez e, no momento, isso não acontece automaticamente. Envie um e-mail para a lista de discussão pedindo que seu conteúdo seja publicado.

Se ninguém reagir ao seu pull request depois de 5 dias, entre em contato com a Equipe de Documentação. Nós podemos ter perdido o email para o seu pull request.