Generate Sphinx/ReStructured documentation from PHPDoc

Overview

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 Tkinter1.
    Mantenha o Python Test Suite.
    Pode remover também o py launcher2.

  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.

 
 


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.

Footnotes

  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.

You might also like...
Generates documentation for your REST API from annotations

NelmioApiDocBundle The NelmioApiDocBundle bundle allows you to generate a decent documentation for your APIs. Migrate from 3.x to 4.0 To migrate from

Documentation Generator for WordPress.

Pronamic WordPress Documentor is a tool to automatically extract data about the actions and filters of your WordPress theme or plugin.

Sami: an API documentation generator

Sami: an API documentation generator WARNING: Sami is not supported nor maintained anymore. Feel free to fork. Curious about what Sami generates? Have

 Yii2 Annotations Generate API Document Extension
Yii2 Annotations Generate API Document Extension

Generate online api document by code annotation for yii2 easily

Daux.io is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.

Daux.io - Deprecation Notice This repository is deprecated! Daux.io has been moved to an organization, to guarantee future development and support. So

Daux.io is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.

Daux.io Daux.io is a documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It help

SphinxQL Query Builder generates SphinxQL, a SQL dialect, which is used to query the Sphinx search engine. (Composer Package)

Query Builder for SphinxQL About This is a SphinxQL Query Builder used to work with SphinxQL, a SQL dialect used with the Sphinx search engine and it'

Sphinx Search library provides SphinxQL indexing and searching features

Sphinx Search Sphinx Search library provides SphinxQL indexing and searching features. Introduction Installation Configuration (simple) Usage Search I

Next generation phpDoc parser with support for intersection types and generics.

PHPDoc-Parser for PHPStan PHPStan Next generation phpDoc parser with support for intersection types and generics. Code of Conduct This project adheres

Add scalar type hints and return types to existing PHP projects using PHPDoc annotations

PHPDoc to Type Hint Archived! This repository is now archived. Consider using PHP CS Fixer (and especially the phpdoc_to_param_type and phpdoc_to_retu

A PHP tool to generate templateable markdown documentation from the docblocks or type-hints of your codebase.

Roster Installation To install, simply require the package using composer: composer require

Auto Generate laravel api Documentation
Auto Generate laravel api Documentation

Laravel Dark Documentation Generator 💥 You can create Documentation for your api easily by using this library Installation: Require this package with

📒📚Generate beautiful interactive documentation and Open-API 3.0 spec file from your existing Laravel app.
Generate routes documentation

Laravel Route Documentation Maybe we are wondering where these routes lead or what could be their purpose? This package decides to solve this solution

Generate API documentation for humans from your Laravel codebase.✍
Generate API documentation for humans from your Laravel codebase.✍

Scribe v3 is out now! Scribe helps you generate API documentation for humans from your Laravel/Lumen/Dingo codebase. See a live example at demo.scribe

phpDocumentor is an application that is capable of analyzing your PHP source code and DocBlock comments to generate a complete set of API Documentation

phpDocumentor What is phpDocumentor? phpDocumentor is an application that is capable of analyzing your PHP source code and DocBlock comments to genera

Generate interactive OpenAPI documentation for your RESTful API using doctrine annotations

Generate interactive OpenAPI documentation for your RESTful API using doctrine annotations

The NelmioApiDocBundle bundle allows you to generate a decent documentation for your APIs

NelmioApiDocBundle The NelmioApiDocBundle bundle allows you to generate a decent documentation for your APIs. Migrate from 3.x to 4.0 To migrate from

Boilerplate code for protecting a form with proof of work. Uses javascript in the browser to generate the hashcash and PHP on the server to generate the puzzle and validate the proof of work.

Boilerplate code for protecting a form with proof of work. Uses javascript in the browser to generate the hashcash and PHP on the server to generate the puzzle and validate the proof of work.

Owner
Rianna Cantarelli
Rianna Cantarelli
Daux.io is an documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It helps you create great looking documentation in a developer friendly way.

Daux.io Daux.io is a documentation generator that uses a simple folder structure and Markdown files to create custom documentation on the fly. It help

Daux.io 719 Nov 29, 2022
Next generation phpDoc parser with support for intersection types and generics.

PHPDoc-Parser for PHPStan PHPStan Next generation phpDoc parser with support for intersection types and generics. Code of Conduct This project adheres

PHPStan 890 Nov 27, 2022
phpDocumentor is an application that is capable of analyzing your PHP source code and DocBlock comments to generate a complete set of API Documentation

phpDocumentor What is phpDocumentor? phpDocumentor is an application that is capable of analyzing your PHP source code and DocBlock comments to genera

phpDocumentor 3.7k Dec 1, 2022
Generate interactive OpenAPI documentation for your RESTful API using doctrine annotations

Generate interactive OpenAPI documentation for your RESTful API using doctrine annotations

Robert Allen 4.6k Nov 24, 2022
Documentation Generator for PHP

phpDocumentor What is phpDocumentor? phpDocumentor is an application that is capable of analyzing your PHP source code and DocBlock comments to genera

phpDocumentor 3.7k Nov 29, 2022
PHP 7.1 ready Smart and Simple Documentation for your PHP project

Smart and Readable Documentation for your PHP project ApiGen is the simplest, the easiest to use and the most modern api doc generator. It is all PHP

ApiGen 2.1k Nov 27, 2022
An API documentation generator

Sami: an API documentation generator WARNING: Sami is not supported nor maintained anymore. Feel free to fork. Curious about what Sami generates? Have

null 2k Nov 3, 2022
Documentation generator for PHP Code using standard technology (SRC, DOCBLOCK, XML and XSLT)

phpDox phpDox is a documentation generator for PHP projects. This includes, but is not limited to, API documentation. The main focus is on enriching t

Arne Blankerts 589 Nov 11, 2022
A php API documentation generator, fork of Sami

Doctum, a PHP API documentation generator. Fork of Sami Curious about what Doctum generates? Have a look at the MariaDB MySQL Kbs or Laravel documenta

Code LTS 195 Nov 20, 2022
PHP 7.1 ready Smart and Simple Documentation for your PHP project

Smart and Readable Documentation for your PHP project ApiGen is the simplest, the easiest to use and the most modern api doc generator. It is all PHP

ApiGen 2.1k Apr 20, 2021