Construindo e hospedando continuamente nossa documentação do Swift DocC usando ações do Github e Netlify
Avalie esse Tutorial
Em uma postagem anterior desta série, mostramos como é fácil gerar documentação para nossas estruturas e bibliotecas usando o DocC e os benefícios de fazer isso. Também vimos o conteúdo diferente que podemos adicionar, como artigos, instruções e referências para nossas funções, classes e estruturas.
Mas, depois de gerada, você acaba com uma pasta DocC arquivada que não é muito fácil de compartilhar. Você pode compactá-la, enviá-la por e-mail, colocá-la em algum lugar na nuvem para que possa ser baixada, mas não é isso que queremos. Nós queremos:
- Geração automática (e contínua) do nosso pacote de documentação DocC.
- Postagem automática (e contínua) dessa documentação na web, para que possa ser lida online.
Um arquivo
.doccarchive é, como muitas outras coisas no macOS, uma pasta. Clone o repositório que criamos com nossa documentação e examine dentro BinaryTree.doccarchive a partir de um terminal.1 git clone https://github.com/mongodb-developer/realm-binary-tree-docc 2 cd BinaryTree.doccarchive
Você verá:
1 .. 2 ├── css 3 │ ├── … 4 │ └── tutorials-overview.7d1da3df.css 5 ├── data 6 │ ├── documentation 7 │ │ ├── binarytree 8 │ │ │ ├── … 9 │ │ │ └── treetraversable-implementations.json 10 │ └── tutorials 11 │ ├── binarytree 12 │ │ ├── … 13 │ │ └── traversingtrees.json 14 │ └── toc.json 15 ├── downloads 16 ├── favicon.ico 17 ├── favicon.svg 18 ├── images 19 │ ├── … 20 │ └── tree.png 21 ├── img 22 │ ├── … 23 │ └── modified-icon.5d49bcfe.svg 24 ├── index 25 │ ├── availability.index 26 │ ├── data.mdb 27 │ ├── lock.mdb 28 │ └── navigator.index 29 ├── index.html 30 ├── js 31 │ ├── chunk-2d0d3105.459bf725.js 32 │ ├ … 33 │ └── tutorials-overview.db178ab9.js 34 ├── metadata.json 35 ├── theme-settings.json 36 └── videos
Este é um aplicativo da web de página única. Infelizmente, não podemos apenas abrir
index.html e esperar que ele seja renderizado corretamente. Como a Apple explica na documentação, para que isso funcione, ele deve ser atendido a partir de um servidor web adequado, com algumas regras de reescrita adicionadas:Para hospedar um arquivo de documentação em seu website, faça o seguinte:
- Copie o arquivo de documentação para o diretório que seu servidor da web usa para fornecer arquivos. Neste exemplo, o arquivo de documentação é SlothCreator.doccarchive.
- Adicione uma regra no servidor para reescrever URL de entrada que começam com /documentation ou /tutorial para SlothCreator.doccarchive/index.html.
- Adicione outra regra para solicitações recebidas para dar suporte a recursos agrupados no arquivo de documentação, como arquivos CSS e ativos de imagem.
Eles até adicionam uma configuração de amostra para usar com o servidor Apache
httpd. Então, para recapitular:- Podemos gerar manualmente nossa documentação e carregá-la em um servidor da web.
- Precisamos adicionar as regras de reescrita descritas na documentação da Apple para que o pacote DocC funcione corretamente.
Sempre que atualizamos nossa documentação, precisamos gerá-la e carregá-la. Vamos gerar nossos Docs automaticamente.
Continuaremos usando nosso pacote de árvore binária como exemplo para gerar a documentação. Adicionaremos uma ação do Github para gerar Docs em cada novo push para principal. Dessa forma, podemos atualizar automaticamente nossa documentação com as últimas alterações introduzidas em nossa biblioteca.
Para adicionar a ação, clicaremos no botão
Actions em nosso repositório. Nesse caso, uma Swift Action é oferecida como modelo para começar. Vamos escolher esse:
Depois de clicar em
Configure, podemos começar a ajustar nossa ação. Uma ação do GitHub é apenas um conjunto de etapas que o GitHub executa em um contêiner para nós. Há etapas predefinidas, ou podemos simplesmente escrever comandos que funcionarão em nosso terminal local. O que precisamos fazer é:- Obtenha a versão mais recente do nosso código.
- Crie nosso arquivo de documentação.
- Encontre onde o
doccarchivefoi gerado. - Copie esse arquivo para um local onde ele possa ser atendido online.
Chamaremos nossa ação
docc.yml. As ações do GitHub são arquivos YAML, como a documentação nos informa. Depois de adicioná-los ao nosso repositório, eles serão armazenados em .github/workflows/. Então, eles são apenas arquivos de texto que podemos editar localmente e enviar para nosso repositório.Essa é a parte fácil. Cada vez que uma ação do Github é iniciada, ele cria um contêiner novo e vazio e clona nosso repositório. Então, nosso código está lá, pronto para ser compilado, passar em todos os testes e fazer tudo o que precisamos fazer com ele.
Nossa ação começa com:
1 name: Generate DocC 2 on: 3 push: 4 branches: [ main ] 5 6 jobs: 7 Build-Github-Actions: 8 runs-on: macos-latest 9 10 steps: 11 - name: Git Checkout 12 uses: actions/checkout@v2
Então, aqui:
- Demos à ação o nome de "Generate DocC ".
- Em seguida, selecionamos quando ele será executado, ou seja, em qualquer push para
main. - Executamos isso em um container macOS, pois precisamos do Xcode.
- O primeiro passo é clonar nosso repositório. Usamos uma ação predefinida,
checkout, que o GitHub nos fornece.
Agora que nosso código está pronto, podemos usar
xcodebuild para criar o arquivo DocC. Podemos criar nossos projetos a partir da linha de comando, executar nossos testes ou, neste caso, criar a documentação.1 xcodebuild docbuild -scheme BinaryTree -derivedDataPath ./docbuild -destination 'platform=iOS Simulator,OS=latest,name=iPhone 13 mini'
Aqui estamos construindo para gerar DocC (parâmetro
docbuild), escolhendo o esquemaBinaryTree em nosso projeto, colocando todos os binários gerados em uma pasta à mão (docbuild) e usando um iPhone 13 mini como simulador . Quando construímos nossa documentação, também precisamos compilar nossa biblioteca. É por isso que precisamos escolher o simulador (ou dispositivo) usado para a construção.Se tudo correr bem, teremos nossa documentação construída dentro de
docbuild. Nós a procuraremos, pois cada compilação gerará um hash diferente para armazenar os resultados da nossa compilação. E essa é, em cada execução, uma máquina limpa. Para localizar o arquivo, usamos:1 find ./docbuild -type d -iname "BinaryTree.doccarchive"
Agora que sabemos onde está nosso arquivo DocC, é hora de colocá-lo em outro repositório. A ideia é que teremos um repositório para nosso código e outro para nosso pacote DocC gerado. A Netlify lerá a partir deste segundo repositório e o hospedará online.
Então, clonamos o repositório que manterá nossa documentação com:
1 git clone https://github.com/mongodb-developer/realm-binary-tree-docc
Então, sim, agora temos dois repositórios, um clonado no início da ação e agora esse que contém apenas a documentação. Copiamos o arquivo DocC recém-gerado:
1 cp -R "$DOCC_DIR" realm-binary-tree-docc
E confirmamos todas as alterações:
1 cd realm-binary-tree-docc 2 git add . 3 git commit -m "$DOC_COMMIT_MESSAGE" 4 git status
Aqui,
$DOC_COMMIT_MESSAGE é apenas uma variável que preenchemos com a última mensagem de confirmação do nosso repositório e a data atual. Mas pode ser qualquer mensagem.Depois disso, precisamos enviar as alterações para o repositório de documentação.
1 git config --get remote.origin.url 2 git remote set-url origin https://${{ secrets.API_TOKEN_GITHUB}}@github.com/mongodb-developer/realm-binary-tree-docc 3 4 git push origin
Aqui, imprimimos primeiro nosso
origin (o repositório onde enviaremos nossas alterações) com1 git config --get remote.origin.url
Este comando mostrará a origem de um repositório git. Ele imprimirá a URL do nosso repositório de código. Mas não é aqui que queremos forçar. Queremos enviar para o repositório dedocumentação . Então, definimos a origem apontando para https://github.com/mongodb-developer/realm-binary-tree-docc. Como precisaremos de permissão para fazer alterações, autenticamos usando um token de acesso pessoal. Da documentação do Github sobre tokens de acesso pessoal:
Você deve criar um token de acesso pessoal para usar no lugar de uma senha com a linha de comando ou com a API.
Felizmente, o Github Actions tem uma maneira de armazenar esses segredos, então eles estão acessíveis publicamente. Basta acessar as Configurações do seu repositório e expandir Segredos. Você verá uma opção "Actions ". Ali você pode dar um nome ao seu segredo para ser usado mais tarde em suas ações.
Conforme mostrado nesta notável publicação de PHP , hospedaremos nossa documentação na Netlify. Criar uma conta grátis é superfácil. Nesse caso, recomendamos que você use suas credenciais do Github para fazer login no Netlify. Dessa forma, adicionar um novo site que lê de um repositório do Github será superfácil. Basta adicionar um novo site e selecionar Importar um projeto existente. Você pode então escolher o Github e, uma vez autorizado, poderá selecionar um dos seus repositórios.
Agora defina-o para implantar com "Any pull request against your production branch / branch deploy branches. " Então, toda vez que seu repositório for alterado, a Netlify pegará a alteração e a hospedará online (se for um aplicativo web, é claro).
Mas estamos perdendo apenas um detalhe. Lembra que mencionei antes que precisamos adicionar algumas regras de reescrita à nossa documentação hospedada? Vamos adicioná-los em um arquivo chamado
netlify.toml. Esse arquivo tem a seguinte aparência:1 [build] 2 publish = "BinaryTree.doccarchive/" 3 4 [[redirects]] 5 from = "/documentation/*" 6 status = 200 7 to = "/index.html" 8 9 [[redirects]] 10 from = "/tutorials/*" 11 status = 200 12 to = "/index.html" 13 14 [[redirects]] 15 from = "/data/documentation.json" 16 status = 200 17 to = "/data/documentation/binarytree.json" 18 19 [[redirects]] 20 force = true 21 from = "/" 22 status = 302 23 to = "/documentation/" 24 25 [[redirects]] 26 force = true 27 from = "/documentation" 28 status = 302 29 to = "/documentation/" 30 31 [[redirects]] 32 force = true 33 from = "/tutorials" 34 status = 302 35 to = "/tutorials/"
Para usá-lo em seus projetos, basta revisar as linhas:
1 publish = "BinaryTree.doccarchive/" 2 … 3 to = "/data/documentation/binarytree.json"
E altere-os adequadamente.
Nesta postagem, vimos como fazer isso:
- Adicione uma ação do Github a um repositório de código que cria continuamente um pacote de documentação do DocC toda vez que enviamos uma alteração no código.
- Essa ação, por sua vez, enviará a documentação recém-construída para um repositório de documentação para nossa biblioteca.
- Esse repositório de documentação será configurado na Netlify e adicionará algumas regras de reescrita para que possamos hospede-o online.
Não espere e adicione a geração contínua da documentação da sua biblioteca ao seu pipeline de CI!