Um guia para iniciantes para documentos como Code & CI/CD Pipelines

No mundo de software de hoje, a documentação não é mais uma tarefa paralela – é uma parte central do ciclo de vida do desenvolvimento. Se você ouviu termos como “documentos como código” e “pipelines de CI/CD”, mas eles parecem intimidadores ou muito avançados, este guia é para você. Seja você um escritor técnico, desenvolvedor ou colaborador de um projeto de código aberto, aprenderá como automatizar a implantação de documentação usando um gerador de sites estáticos e ações do GitHub. Não é necessário um fundo do DevOps complexo. O que é “docs como código”? Os documentos como código são uma abordagem moderna que trata a documentação como o código -fonte. Em vez de escrever documentos no Google Docs ou Word, você os escreve no Markdown, a versão no Git e os gerencia no mesmo repositório que o projeto. Essa abordagem permite: colaboração da equipe através de revisões de código de controle de versão (como Git) e solicitações de puxar para documentação de documentação de edifícios e implantação (CI/CD) de ferramentas de desenvolvedor para Docs Workflows CI/CD Pipeline IC/CD significa para integração contínua e implantação contínua. Isso significa: CI: Verificando automaticamente seu código ou documentos quando você pressiona as alterações (por exemplo, verificação ortográfica, linha, testes). CD: Construindo e implantando automaticamente seu site na Web sem etapas manuais. Neste artigo, usaremos o recurso de ações do Github para executar nosso pipeline CI/CD sempre que forçarmos para a filial principal. Por que este guia é importante enquanto alguns geradores de sites estáticos (SSGs), como a Astro Starlight ou Next.js, oferecem implantação nativa/automática, especialmente em plataformas como Vercel, Netlify, etc., outros como MKDocs, Hugo e Docusaurus não-especialmente ao usar as páginas do Github para hospedagem. Para resolver essa lacuna, criaremos nosso próprio fluxo de trabalho automatizado usando: MKDOCS (um gerador de sites estáticos baseado em Python) Ações do GitHub (para automação) Páginas do Github (para hospedagem gratuita) até o final, você terá um fluxo de trabalho em que sua documentação implanta automaticamente cada vez que você pressiona as alterações. Benefícios desta configuração Custo zero: tudo usa recursos gratuitos do GitHub. Automação: não há necessidade de implantar manualmente. Versão e rastreável: toda alteração é registrada no Git. Leve: configuração mínima necessária para documentos pessoais ou de equipe. Prerequisites Before starting, you should have: A GitHub account and repository set up Basic knowledge of Markdown and Git Python installed locally MkDocs installed (pip install mkdocs mkdocs-material) Project Recap: What We Deployed For this demo, we built and deployed a simple Vue.js documentation site using MkDocs and hosted it at:👉 demo siteIt currently includes: A custom homepage Página de introdução Guia de início rápido passo a passo: configure CI/CD para MKDOCs com páginas do GitHub. Aqui está como configuramos o pipeline: entenda o fluxo quando você empurrar as alterações no seu ramo principal, as ações do github: detectar a mudança (desencadeada pelo evento On: Push no Implement.yML). Confira seu código de repo no ambiente do fluxo de trabalho. Configurar o Python (já que o MKDOCS é baseado em Python). Instale os MKDOCs e o tema do material. Crie a documentação no HTML estático. Implantá-lo na filial de GH-Pages, que as páginas do Github serve como seu site ao vivo. Estrutura da pasta do projeto, sua pasta deve ficar assim: vue.js-mkdocs-demo/ ├── docs/ │ ├── index.md │ ├── Introdução.md │ └─— Modo de fulling.MSC.MSCLOLS/ MOMSCLOTS/ MODOS DE DEPREM IMPLOTO ├ ├— Mkdocs.yml ├— .github/ │ └ ├ ├ ├ ├stons ├ ├stoS/ devLoST.MSCLOTS/ DESCROT ├SCLOTS/ DESCLOT ├SCLOTS/ DESCROT ├SCLOT ├ ├ ├stoSl/ DeLemSen ├SCLOTS/ DeLemSl. Crie um arquivo de fluxo de trabalho implantado.yml dentro .github/workflows/, crie um arquivo chamado Implement.yml e inclua seu script semelhante ao seguinte: Nome: Implante o site MKDOCS ON: Push: Ramilos: – # Principal Nome: Desenhos Aputados para RUNS -LETUT LETROS: O conteúdo: Write # necessário para empurrar para gh -Pages Ramils: Deplayt -On para run -lets: Ubunt: Nome: Configurar Python Usos: Ações/Setup-Python@V5 com: Python-Version: ‘3.10’-Nome: Instale dependências Executar: | python -m pip install-upgrade pip pip instalar mkdocs mkdocs-mataterial-nome: construir e implantar Env: github_token: $ {{secrets.github_token}} run: mkdocs gh-deploy-force–remote-name digite o modo de linha de tela inteiro Exite Oleoduto CI/CD Esta tubulação: funciona quando você empurra para a filial principal instala Python e MkDocs constrói seus documentos a implanta para as páginas do github empurrar e assistir o pipeline executar depois que você criou o arquivo de queda. Repo Github. Você deve ver o fluxo de trabalho “Implante MKDOCS Site” em execução. Clique nele para assistir a cada etapa (check -out, configurar, instalar, construir, implantar). Todas as etapas devem ficar verdes ✅ quando bem -sucedidas. Fig2: configure configurações para páginas do github Fig4: Ações do GitHub Fluxo mostrando implantação bem -sucedida. Veja sua documentação ao vivo quando o fluxo de trabalho terminar, seu site estará ao vivo em: Digite o modo de tela de tela cheia Fig5: Site de documentos de Vue.js implantados construídos com MKDocs encerrando este guia prova que a automação de documentação não é apenas para grandes equipes de Dev-é fácil e acessível para iniciantes e acessíveis. Ao usar os documentos como práticas de código com ações do GitHub e MKDOCs, você garante que seus documentos fiquem ao vivo, versionados e atualizados com zero esforço de implantação manual. O tratamento de documentos como o código economiza tempo, cria consistência e melhora a colaboração. Se você é novo no CI/CD ou geradores de sites estáticos, este tutorial prático é um início sólido.

[Live Site](https://mike-4-prog.github.io/vue.js-mkdocs-demo/)[Github Repo](

Fonte