Sphinx para la documentación del código php

Question

Sphinx es una biblioteca de Python para generar una buena documentación a partir de un conjunto de archivos de texto con formato ReST. No es la herramienta utilizada para la búsqueda de texto completo

También conozco las herramientas doxygen/phpdoc. Estoy tratando de averiguar si hay una forma de usar Sphinx para documentar proyectos de php. o incluso cualquier otro idioma que no sea Python?

http://sphinx.pocoo.org/

Answer 1

Esfinge y el descanso pueden ser utilizados como herramientas de documentación genéricos, en mi experiencia. No hay nada acerca de Sphinx que lo obligue a usarlo solo para proyectos basados ​​en Python. Por ejemplo, en mi trabajo, lo he usado para compilar una guía de usuario y una referencia de API XML-RPC. En ambos casos, no tuve uso para sphinx.ext.autodoc u otros extras específicos de Python. La documentación fue escrita "a mano", con directivas ReST, en su mayoría genéricas, en lugar de las directivas especializadas proporcionadas por Sphinx. Por lo que vale, aún no he necesitado crear una directiva ReST personalizada para documentación que no sea de Python.

Incluso si está trabajando con un proyecto PHP, creo que encontrará útil a Sphinx. Por ejemplo, la mayoría de las directivas proporcionadas por the module specific markup son bastante generales. No veo por qué no podrías o no usar estas construcciones para documentar cosas de otros lenguajes además de Python. Del mismo modo, Sphinx hace que sea bastante fácil de show code examples in other languages. Incluso hay un valor de configuración para cambiar el valor predeterminado a cualquier idioma compatible con Pygments (que incluye PHP). Si te sientes particularmente ambicioso, incluso puedes llamar al create a Sphinx extension para obtener algo relevante de tu código PHP.

Dicho todo esto, asegúrese de tener en cuenta la audiencia para su proyecto de documentación. Aunque creo que Sphinx es una herramienta excelente y la recomendaría para una amplia gama de proyectos de documentación, si su público espera algo más, sea consciente de ello. Por ejemplo, si estaba documentando un proyecto de Java, gran parte de su audiencia puede esperar documentos de estilo Javadoc. Si te desvías de esa expectativa, asegúrate de que no sea solo para patadas (es decir, te da mejores documentos de los que obtendrías) y prepárate para (brevemente) defiende lo que has hecho de manera diferente (por ejemplo, con un Respuesta a preguntas frecuentes o introducción).

Finalmente, cualquier documentación es mejor que ninguna documentación, independientemente de la herramienta utilizada para crearlas. Use cualquier herramienta que lo ayude, si es la diferencia entre obtener algo por ahí y no.

Answer 2

acaba de publicar hace unos días: http://mark-story.com/posts/view/sphinx-phpdomain-released

Answer 3

El proyecto Doctrina, un ORM para PHP, utiliza Sphinx para generar la documentación en línea en www.doctrine-project.org. Usan una pirámide personalizada para PHP. La documentación está disponible en Github al https://github.com/doctrine/orm-documentation. Incluye el archivo personalizado PHP pygment css.

También el python-Pygments paquete viene con muchos estilos pygment que se puede tratar mediante el cambio de la pygments_style = valor en su esfinge conf.py archivo de configuración. Por ejemplo, para probar el sytle resaltado pastie, que es parte de python-Pygments, utiliza

pygments_sytle = 'pastie' 

Answer 4

CakePHP está utilizando Esfinge por su nueva documentación, y escribí la phpdomain de esfinge. Si bien no existe una manera de incluir automáticamente tus bloques de documentos php en Sphinx, sigo creyendo que es una de las mejores herramientas de creación de documentación disponibles. Es ideal para una documentación de estilo más narrativa.Pero con phpdomain puedes hacer api docs también.

Answer 5

Por lo que a mí respecta, puede documentar casi cualquier sintaxis en Sphinx siempre que no se limite a sí mismo con idiomas admitidos por autodoc. Puede crear hermosas referencias de API utilizando directivas Sphinx estándar como .. class, .. method, .. function y otras. Funcionan perfectamente aparte del código fuente y no requieren ninguna generación automática y vinculación a las fuentes.

También puede crear advertencias genéricas con alguna clase especial, que podría más tarde enganchar a CSS:

.. admonition Title 
    :class: Ololo 

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

También hay papeles (que permiten clases personalizadas también) y otros medios de adición de texto con un poco especial formateo, si las directivas originales no son suficientes para usted.

Si decide crear sus documentos de manera asincrónica desde el código fuente, asegúrese de deshabilitar la verificación de la cobertura del código y otras características relacionadas con el código en su conf.py o en el inicio del proyecto.

PD: Puede ver una muy buena respuesta en elementos con clases personalizadas here.

Answer 6

Como se puede ver hay una gran cantidad de herramientas para ayudarle con esto, de lo contrario, si realmente es necesario, comprobar que funciona:

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