A maioria das ferramentas de documentação exporta HTML estático. MkDocs, Sphinx, Docusaurus, Hugo, uma referência de API gerada: o resultado é uma pasta autónoma, concebida para funcionar sem ligação. É exatamente o que precisa num avião, na cave de um centro de dados ou num cliente cujo wifi recusa o seu portátil.
Falta abri-la no tablet que levou.
Porque o PDF não é a resposta
O reflexo é exportar a documentação para PDF. Funciona, e para um documento curto é muitas vezes a escolha certa. Mas uma documentação técnica perde muito na conversão.
- A navegação lateral desaparece, substituída por um deslocamento de várias centenas de páginas.
- As ligações entre secções tornam-se, na melhor das hipóteses, remissões de página, na pior texto morto.
- O realce de sintaxe e os blocos de código recolhíveis nem sempre sobrevivem.
- Cada atualização obriga a refazer a exportação.
Ora a exportação HTML já existe, e contém tudo isso.
Manter a documentação tal como foi gerada
O Pagira abre a pasta de exportação como o faria um navegador: a barra lateral, as ligações entre páginas, o realce do código. Consulta a documentação, não uma fotografia dela.
- Copie a pasta de exportação para o Ficheiros ou para o iCloud Drive.
- Abra-a com o Pagira.
- Navegue como no site: a barra de ferramentas dá retroceder, avançar e recarregar.
iCloud Drive e a questão do offline
Uma documentação gerada pesa muitas vezes várias centenas de megabytes, imagens e tipos de letra incluídos. Colocada no iCloud Drive, descarrega enquanto lê, sem espera antes de a primeira página aparecer.
Antes de uma deslocação, descarregue uma cópia offline permanente. A transferência é retomável, portanto uma quebra não recomeça do início, e um aviso deixa claro o que continua consultável sem rede. Ver transmitir do iCloud Drive ou guardar offline.
Preparar as páginas de que vai precisar
Há o offline sofrido e o offline preparado. Se já sabe que documentos vai consultar, transfira-os para ler offline antes de partir, e adicione os mais úteis aos seus favoritos: esperam por si no ecrã inicial, e cada um reabre na página onde o deixou. Ver os favoritos.
O caso das documentações mistas
Uma documentação de empresa mistura quase sempre páginas HTML e PDF: uma especificação, um esquema de arquitetura, um anexo contratual. Ambos abrem na mesma app, e uma ligação de uma página para um PDF abre ali mesmo.
Perguntas frequentes
E uma documentação de vários gigabytes?
A transmissão a partir do iCloud evita ter de descarregar tudo de uma vez. Para o offline completo, o limite é o espaço disponível no dispositivo.
A minha documentação é confidencial
Nada é enviado. Tudo é apresentado localmente, o que é justamente o argumento face a um serviço online de visualização de documentos.
Posso consultá-la também no iPhone?
Sim, uma só app cobre ambos. Com o iCloud, a página onde vai e os seus favoritos acompanham-no de um dispositivo para o outro, para os documentos guardados no iCloud Drive.
Como a abro a partir de outra ferramenta?
Pela folha de partilha, com Abrir com o Pagira, a partir do Ficheiros ou de qualquer app. Ver abrir a partir de qualquer lado.
