Sphinx para documentação do código php

Sphinx é uma biblioteca Python para gerar documentação agradável de um conjunto de arquivos de texto formatados ReST. Não é a ferramenta usada para pesquisa de texto completo

Também estou plenamente consciente das ferramentas doxygen / phpdoc. Estou tentando descobrir se existe uma maneira de usar o Sphinx para documentar projetos php? ou mesmo outras línguas que não sejam Python?

http://sphinx.pocoo.org/

Sphinx e ReST podem ser usados ​​como ferramentas genéricas de documentação, na minha experiência. Não existe nada sobre a Sphinx que o obrigue a usá-lo somente para projetos baseados em Python. Por exemplo, no meu trabalho, usei-o para criar um guia de usuário e uma referência de API XML-RPC. Em ambos os casos, eu não usava sphinx.ext.autodoc ou outros extras específicos de Python. A documentação foi escrita “à mão”, com diretrizes ReST geralmente genéricas, em vez das diretrizes especiais fornecidas pela Sphinx. Para o que vale a pena, não precisei ainda criar uma diretriz ReST personalizada para documentação que não seja Python.

Mesmo se você estiver trabalhando com um projeto PHP, acho que você encontrará Sphinx útil. Por exemplo, a maioria das diretrizes fornecidas pela marcação específica do módulo são realmente bastante gerais. Não vejo por que você não pôde ou não usaria essas construções para documentar coisas de outras linguas que não o Python. Da mesma forma, a Sphinx torna muito fácil mostrar exemplos de código em outros idiomas . Existe até um valor de configuração para alterar o padrão para qualquer idioma que o Pygments suporte (o que inclui o PHP). Se você se sentir particularmente ambicioso, você pode até criar uma extensão Sphinx para arrancar algo relevante do seu código PHP.

Tudo o que disse, não se esqueça de considerar a audiência para o seu projeto de documentação. Embora eu pense que a Sphinx é uma excelente ferramenta e recomendaria isso para uma ampla gama de projetos de documentação, se o seu público estiver esperando algo mais, fique atento a isso. Por exemplo, se você estivesse documentando um projeto Java, grande parte do seu público pode estar esperando documentos de estilo Javadoc. Se você se afastar dessa expectativa, certifique-se de que não é apenas para chutes (ou seja, isso lhe dá melhores docs do que você obtém de outra forma) e esteja preparado para (brevemente) fazer o caso do que você fez de forma diferente (por exemplo, com um Resposta ou introdução de FAQ).

Finalmente, qualquer documentação é melhor do que nenhuma documentação, independentemente da ferramenta usada para criá-las. Use qualquer ferramenta que o ajude, se for a diferença entre conseguir algo lá fora e não.

CakePHP está usando Sphinx para sua nova documentação, e eu escrevi o phpdomain para esfinge. Embora não haja nenhuma maneira de include automaticamente seus blocos de php doc em sphinx, eu ainda acho que é uma das melhores ferramentas de autoria de documentação disponíveis. É ótimo para mais documentação de estilo narrativo. Mas com o phpdomain você também pode fazer documentos api.

O projeto Doctrine, um ORM para PHP, usa a Sphinx para gerar sua documentação online em http://www.doctrine-project.org . Eles usam um aperfeiçoamento personalizado para o PHP. A documentação está disponível no Github em https://github.com/doctrine/orm-documentation . Inclui o arquivo css customizado PHP pygment.

Além disso, o pacote python-pygments vem com muitos estilos de segmentação que você pode experimentar alterando o pygments_style = value em seu arquivo de configuração Sphinx conf.py. Por exemplo, para testar o estilo de destaque do pastie , que faz parte de pygments de python, você usa

 pygments_sytle = 'pastie' 

No que me diz respeito, você pode documentar apenas qualquer syntax na Sphinx, na medida em que não se limita com os idiomas suportados pelo autodoc. Você pode criar belas referências de API usando diretivas Sphinx padrão como .. class , .. method , .. function e outros. Eles funcionam perfeitamente para além do código fonte e não requerem nenhuma geração automática e vinculando as fonts.

Você também pode criar admoestações genéricas com alguma class especial, que você poderia mais tarde se conectar ao CSS:

 .. admonition Title :class: Ololo This text could be formatted any way you want, using the ``Ololo`` tag. 

Há também papéis (eles permitem classs personalizadas também) e outros meios de adicionar texto com alguma formatação especial, se as diretrizes originais não forem suficientes para você.

Se você decidir criar seu docs asynchronous do código-fonte, certifique-se de desativar a verificação da cobertura do código e outros resources relacionados ao código na conf.py ou no início do projeto.

PS: Você pode ver uma resposta muito boa em elementos com classs personalizadas aqui .

Como você vê, há muitas ferramentas para ajudá-lo com isso, caso contrário, se você realmente precisar, confira:

https://blog.simpleigh.com/2012/08/php-documentation-and-sphinx

Intereting Posts