aeondigital / phpdoc-to-rst
Generate Sphinx/ReStructured documentation from PHPDoc
Requires
- phpdocumentor/reflection: ~4.0
- phpdocumentor/reflection-common: 2.0.0-beta1
- symfony/console: ^4.0
Requires (Dev)
- codacy/coverage: dev-master
- phpunit/phpunit: *
This package is auto-updated.
Last update: 2024-04-16 06:54:55 UTC
README
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).
-
Na primeira tela selecione a opção de adicionar o Python ao PATH do Windows.
-
Selecione a instalação customizada.
Você pode remover a documentação.
Mantenha o pip.
Você pode remover a biblioteca Tkinter1.
Mantenha o Python Test Suite.
Pode remover também o py launcher2. -
Na próxima tela configure conforme sua preferencia e instale.
-
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.
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:
> pip install -U sphinx
Confirme a instalação do mesmo com o comando:
> sphinx-build --version
Instalação do RTD Theme
Saiba mais sobre o RTD Theme.
> pip install -U sphinx_rtd_theme
PHP Domain for Sphinx
Saiba mais PHP Domain for Sphinx.
> pip install -U sphinxcontrib-phpdomain
Instalação do analisador MarkDown
Saiba Mais sobre o uso de MarkDown com o Sphynx.
> pip install -U recommonmark
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:
> composer require --dev aeondigital/phpdoc-to-rst
Extraia o conteúdo usando o comando:
> ./vendor/bin/phpdoc-to-rst generate <output_directory> <source_directory>
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
> ./vendor/bin/phpdoc-to-rst generate docs/rest src
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:
> ./vendor/bin/phpdoc-to-rst generate-ns <namespace> <output_directory> <source_directory>
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
> ./vendor/bin/phpdoc-to-rst generate-ns JuliusHaertl/PHPDocToRst docs/rest src
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:
> ./vendor/bin/phpdoc-to-rst config
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:
> sphinx-build -b <output_type> <source_directory> <output_directory>
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
> sphinx-build -b html docs/rest docs/html > sphinx-build -b epub docs/rest docs/epub
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.