Download the PHP package aeondigital/phpdoc-to-rst without Composer

PHP-phpdoc-to-rst

Forked from Francesco "Abbadon1334" Danti by AeonDigital.
In this fork the changes has only visual and superficial effects [ just because I'm boring :) ].
Prefer to use the "Abbadon1334" version if you prefer a constantly updated project.

Efetua a extração da documentação técnica usando PHPDoc.

Gerador de reStructuredText para Sphinx

Este projeto é pesadamente baseado em phpDocumentor/Reflection e faz uso do PHP Domain for Sphinx.

Dependências

• Python
• Sphynx
• Sphinx RTD Theme
• PHP Domain for Sphinx
• Recommonmark

Segue abaixo um rápido tutorial sobre como instalar todas as dependências para o correto funcionamento.

Instalação do Python

Vá na página oficial e faça o download do executável mais recente e estável:

Execute o instalador.

Este tutorial foi feito para a versão 3.7.3 (windows).

1. Na primeira tela selecione a opção de adicionar o Python ao PATH do Windows.

2. Selecione a instalação customizada.

   Você pode remover a documentação.
   Mantenha o pip.
   Você pode remover a biblioteca Tkinter[^1].
   Mantenha o Python Test Suite.
   Pode remover também o py launcher[^2].

3. Na próxima tela configure conforme sua preferencia e instale.
4. Após a instalação o programa oferece para desabilitar a limitação de 260 caracteres para a execução de comandos no Windows. Clique para desabilitar esta limitação e evitar problemas na execução.

[^1]: biblioteca para criação de ambiente gráfico; Não obrigatório para o uso do Sphinx.
[^2]: serve para registrar "py" como evocador do python... como estamos definindo para adicionar o Python no PATH então isto não é necessário.

Instalador do Sphinx

Abra um prompt de comando agora que o Python está instalado com o "pip".
Faça a instalação do "Sphinx" usando o seguinte comando:

Confirme a instalação do mesmo com o comando:

Instalação do RTD Theme

Saiba mais sobre o RTD Theme.

PHP Domain for Sphinx

Saiba mais PHP Domain for Sphinx.

Instalação do analisador MarkDown

Saiba Mais sobre o uso de MarkDown com o Sphynx.

Usando o Sphynx

É aconselhado criar um diretório para a documentação do seu projeto. O padrão é o diretório [./docs] na raiz do mesmo.

O diretório especial [./docs/_static] possui arquivos que deverão ser mesclados com os resultantes da extração e que ficam em [./docs/rest]. Nele, há imagens, folhas de estilo e o arquivo de configuração [conf.py] que deve ser editado para estar de acordo com cada projeto usado.

Documento "[conf.py]"

Inicialmente você deve criar seu próprio arquivo conf.py para servir aos propósitos de conversão da documentação entre reST e algum outro formato.
Se você não sabe como criar este arquivo nem quais suas diretivas, aconselhamos usar como base o template-conf.py como modelo para iniciar suas próprias versões.

Para informações completas de como este arquivo funciona e quais suas principais configurações você pode conferir em http://www.sphinx-doc.org/en/master/config

Você também pode usar o comando config (ver abaixo) para criar uma versão básica do conf.py tendo alterado apenas os rótulos informativos.

Usando o comando "phpdoc-to-rst generate"

Convertendo PHPDocs para RST
Nesta etapa o analizador provido por este próprio projeto irá se encarregar de ler todas as anotações PHPDocs contida nos arquivos que compõe o projeto alvo e então extraí-los para o formato reST.

A partir do diretório raíz do projeto:
Instale a biblioteca "phpdoc-to-rst" usando o comando:

Extraia o conteúdo usando o comando:

• output_directory: Nome do diretório onde os documentos extraidos serão adicionados.
• source_directory: Nome do diretório onde estão os arquivos fonte para criação da documentação [normalmente será src].

Exemplo

Usando o comando "phpdoc-to-rst generate-ns"

Extraindo apenas uma namespace
Se você deseja exportar apenas uma dada Namespace do seu projeto use o seguinte comando:

• namespace: Nome da namespace que você deseja exportar.
• output_directory: Nome do diretório onde os documentos extraidos serão adicionados.
• source_directory: Nome do diretório onde estão os arquivos fonte para criação da documentação [normalmente será src].

Exemplo

Usando o comando "phpdoc-to-rst config"

Preparando o arquivo "conf.py"
Se você ainda não tem um arquivo conf.py preparado e alocado no diretório [./src/_static] e nem sabe por onde começar, esta é a melhor forma de conseguir uma versão válida do mesmo que servirá para uso do comando sphinx-build (ver abaixo).

Inicie a configuração usando o comando:

Após, siga a orientação de cada item a ser configurado.
Itens que você deixar em branco serão definidos como uma string vazia "".

Usando o Sphinx com o comando "sphinx-build"

Gerando uma saída em um formato específico
Uma vez que você possui os arquivos reST contendo todo o conteúdo relativo as anotações PHPDocs do seu projeto, é hora de usar o Sphynx para converter esta massa de dados em outro formato como HTML ou Ebook.

A partir do diretório raíz do projeto:

• output_type: Formato de saida da documentação [html, epub]
• source_directory: Nome do diretório onde estão os arquivos fonte para criação da documentação.
• output_directory: Nome do diretório onde os documentos extraidos serão adicionados.

Exemplo

Importante

Como este projeto é um fork da versão que está sendo desenvolvida por Abbadon1334 apenas com o propósito de ser voltada para detalhes visuais específicos é importante atentar para o fato que possivelmente esta peça de software vá estar com um atrazo quanto a implementação de correções ou novas features.