Apêndice: Fazendo deploy de um projeto Sphinx online¶

Quando você estiver pronto para mostrar seu projeto de documentação ao mundo, há muitas opções disponíveis para fazê-lo. Como o HTML gerado pelo Sphinx é estático, você pode dissociar o processo de construção de sua documentação HTML da hospedagem de tais arquivos na plataforma de sua escolha. Você não precisará de um servidor sofisticado executando Python: praticamente todos os serviços de hospedagem na web serão suficientes.

Portanto, o desafio é menos como ou onde servir o HTML estático, mas sim como escolher um fluxo de trabalho que atualize automaticamente a documentação implantada sempre que houver uma alteração nos arquivos fonte.

As seções a seguir descrevem algumas das opções disponíveis para implantar sua documentação on-line e fornecem algumas informações básicas. Se quiser ir direto para a parte prática, você pode pular para Publicando suas fontes de documentação.

Opções de deployment compatíveis com Sphinx¶

Existem várias opções possíveis para hospedar sua documentação do Sphinx. Alguns deles são:

Read the Docs: Read the Docs é um serviço online especializado em hospedar documentação técnica escrita em Sphinx, bem como MkDocs. Eles têm vários recursos extras, como documentação com versão, análise de tráfego e pesquisa, domínios personalizados, redirecionamentos definidos pelo usuário e muito mais.
GitHub Pages: GitHub Pages é uma hospedagem web estática simples totalmente integrada com GitHub: HTML estático é servido a partir de um dos ramos de um projeto, e geralmente os fontes são armazenados em outro ramo para que a saída possa ser atualizada toda vez que o mudança de fontes (por exemplo, usando GitHub Actions). Seu uso é gratuito e oferece suporte a domínios personalizados.
GitLab Pages: GitLab Pages é um conceito semelhante ao GitHub Pages, integrado com GitLab e geralmente automatizado com GitLab CI.
Netlify: Netlify é uma hospedagem sofisticada para sites estáticos aprimorada por tecnologias web do lado do cliente como JavaScript (chamado “Jamstack”). Eles oferecem suporte para sistemas de gerenciamento de conteúdo headless e computação sem servidor.
Seu próprio servidor: Você sempre pode usar seu próprio servidor web para hospedar a documentação HTML do Sphinx. É a opção que dá mais flexibilidade, mas também mais complexidade.

Todas essas opções têm custo zero, com opção de pagamento por recursos extras.

Abraçando a filosofia “Documentação como Código”¶

As ofertas gratuitas da maioria das opções listadas acima exigem que suas fontes de documentação estejam disponíveis publicamente. Além disso, esses serviços esperam que você use um Sistema de Controle de Versão, uma tecnologia que rastreia a evolução de uma coleção de arquivos como uma série de instantâneos (“commits”). A prática de escrever documentação em arquivos de texto simples com as mesmas ferramentas usadas para desenvolvimento de software é comumente conhecida como “Documentação como Código”.

O sistema de controle de versão mais popular atualmente é o Git, uma ferramenta gratuita e de código aberto que é a espinha dorsal de serviços como GitHub e GitLab. Como tanto o Read the Docs quanto o Netlify têm integrações com GitHub e GitLab, e tanto GitHub quanto GitLab têm um produto Pages integrado, a maneira mais eficaz de construir automaticamente sua documentação online é fazer upload de suas fontes para qualquer um desses serviços de hospedagem Git.

Publicando suas fontes de documentação¶

GitHub¶

A maneira mais rápida de fazer upload de um projeto existente para o GitHub é:

Inscreva-se para uma conta GitHub.
Crie um novo repositório.
Abra a página “Upload files” do seu novo repositório.
Selecione os arquivos no navegador de arquivos do seu sistema operacional (no seu caso README.rst, lumache.py, os makefiles no diretório docs e tudo em docs/source ) e arraste-os para a interface do GitHub para fazer upload de todos eles.
Clique no botão Commit changes.

Nota

Certifique-se de não fazer upload do diretório docs/build, pois ele contém a saída gerada pelo Sphinx e mudará toda vez que você alterar as fontes, complicando seu fluxo de trabalho.

Estas etapas não requerem acesso à linha de comando ou instalação de qualquer software adicional. Para saber mais, leia este tutorial de início rápido ou consulte a documentação oficial do GitHub

GitLab¶

Da mesma forma que no GitHub, a maneira mais rápida de enviar seu projeto para o GitLab é usando a interface web:

Inscreva-se para uma conta GitLab.
Crie um novo projeto vazio.
Faça o upload dos arquivos do projeto (no seu caso README.rst, lumache.py, os makefiles no diretório docs e tudo em docs/source ) um de cada vez usando o botão Upload File [1].

Novamente, essas etapas não requerem software adicional em seu computador. Para saber mais, você pode:

Siga este tutorial para instalar o Git em sua máquina.
Explore a documentação do usuário do GitLab para entender as possibilidades da plataforma.

Nota

Certifique-se de não fazer upload do diretório docs/build, pois ele contém a saída gerada pelo Sphinx e mudará toda vez que você alterar as fontes, complicando seu fluxo de trabalho.

Publicando sua documentação em HTML¶

Read the Docs¶

Read the Docs oferece integração com GitHub e GitLab. A maneira mais rápida de começar é seguir o tutorial do RTD, que é vagamente baseado neste. Você pode publicar suas fontes no GitHub conforme explicado na seção anterior e, em seguida, pular diretamente para Creating a Read the Docs account. Se você escolher o GitLab, o processo será semelhante.

GitHub Pages¶

GitHub Pages requer que você publique suas fontes no GitHub. Depois disso, você precisará de um processo automatizado que execute a etapa make html toda vez que as fontes forem alteradas. Isso pode ser conseguido usando GitHub Actions.

Depois de publicar suas fontes no GitHub, crie um arquivo chamado .github/workflows/sphinx.yml em seu repositório com o seguinte conteúdo:

.github/workflows/sphinx.yml¶

name: "Sphinx: Render docs"

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
    - uses: actions/checkout@v4
      with:
        persist-credentials: false
    - name: Build HTML
      uses: ammaraskar/sphinx-action@master
    - name: Upload artifacts
      uses: actions/upload-artifact@v4
      with:
        name: html-docs
        path: docs/build/html/
    - name: Deploy
      uses: peaceiris/actions-gh-pages@v3
      if: github.ref == 'refs/heads/main'
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: docs/build/html

Contém um fluxo de trabalho do GitHub Actions com um único “job” de quatro etapas:

Fazer checkout do código.
Construir a documentação HTML usando Sphinx.
Anexar a saída HTML dos artefatos ao trabalho GitHub Actions, para facilitar a inspeção.
Se a mudança acontecer no branch padrão, pegue o conteúdo de docs/build/html e envie-o para o branch gh-pages.

Em seguida, você precisa especificar as dependências para que a atapa make html seja bem-sucedido. Para isso, crie um arquivo docs/requirements.txt e adicione o seguinte conteúdo:

docs/requirements.txt¶

furo==2021.11.16

E finalmente, você está pronto para publicar GitHub Pages a partir de uma branch. Para isso, acesse Settings, depois Pages na barra lateral esquerda, selecione a opção Deploy from a branch no menu suspenso “Source”, selecione a branch “gh-page” no menu suspenso “Branch” e clique em Salvar. Após alguns minutos, você deverá conseguir visualizar seu HTML no URL indicado.

GitLab Pages¶

GitLab Pages, por outro lado, exige que você publique suas fontes no GitLab. Quando estiver pronto, você pode automatizar o processo de execução do make html usando o GitLab CI.

Depois de publicar suas fontes no GitLab, crie um arquivo chamado .gitlab-ci.yml em seu repositório com este conteúdo:

.gitlab-ci.yml¶

stages:
  - deploy

pages:
  stage: deploy
  image: python:3.14-slim
  before_script:
    - apt-get update && apt-get install make --no-install-recommends -y
    - python -m pip install sphinx furo
  script:
    - cd docs && make html
  after_script:
    - mv docs/build/html/ ./public/
  artifacts:
    paths:
    - public
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH

Contém um fluxo de trabalho de GitLab CI com um job de várias etapas:

Instalar as dependências necessárias.
Construir a documentação HTML usando Sphinx.
Mover a saída para um local de artefatos conhecido.

Nota

Você precisará validar sua conta inserindo um método de pagamento (será cobrado um pequeno valor que será reembolsado).

Depois disso, se o pipeline for bem-sucedido, você poderá ver seu HTML no URL designado.