software - Sphinx para documentacion de codigo php
plantilla para documentar codigo (5)
Sphinx es una biblioteca de Python para generar buena documentación de un conjunto de archivos de texto con formato ReST. No es la herramienta utilizada para la búsqueda de texto completo
También soy plenamente consciente de las herramientas doxygen / phpdoc. ¿Estoy tratando de averiguar si hay una forma de usar Sphinx para documentar proyectos de php? ¿O incluso cualquier otro lenguaje que no sea python?
CakePHP está usando Sphinx para su nueva documentación, y escribí phpdomain para sphinx. Si bien no hay una manera de incluir automáticamente los bloques de documentos php en la esfinge, sigo pensando que es una de las mejores herramientas de creación de documentación disponibles. Es ideal para más documentación de estilo narrativo. Pero con el phpdomain también puedes hacer api docs.
El proyecto Doctrine, un ORM para PHP, utiliza Sphinx para generar su documentación en línea en www.doctrine-project.org . Usan un fragmento personalizado para PHP. La documentación está disponible en Github en https://github.com/doctrine/orm-documentation . Incluye el archivo css PHP pygment personalizado.
Además, el paquete python-pygments viene con muchos estilos de pygement que puedes probar cambiando el valor pygments_style = en tu archivo de configuración conf.py de sphinx. Por ejemplo, para probar la pastilla resaltando sytle, que es parte de python-pygments, usas
pygments_sytle = ''pastie''
En lo que a mí respecta, puede documentar casi cualquier sintaxis en Sphinx en la medida en que no se limite con idiomas admitidos por autodoc. Puede crear hermosas Referencias de API usando directivas estándar de Sphinx como .. class , .. method , .. function y otras. Funcionan perfectamente aparte del código fuente y no requieren ninguna generación automática y enlaces a las fuentes.
También puede crear avisos genéricos con alguna clase especial, que luego podría enganchar a CSS:
.. admonition Title
:class: Ololo
This text could be formatted any way you want, using the ``Ololo`` tag.
También hay roles (también permiten clases personalizadas) y otros medios para agregar texto con algún formato especial, si las directivas originales no son suficientes para usted.
Si decide crear sus documentos asincrónicos a partir del 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: Puedes ver una muy buena respuesta en elementos con clases personalizadas here .
Lanzamiento hace unos días: http://mark-story.com/posts/view/sphinx-phpdomain-released
Sphinx y ReST se pueden utilizar como herramientas de documentación genérica, en mi experiencia. Sphinx no tiene nada que obligue a usarlo solo para proyectos basados en Python. Por ejemplo, en mi trabajo, lo he usado para crear 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 especiales proporcionadas por Sphinx. Para lo que vale, todavía 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á a Sphinx útil. Por ejemplo, la mayoría de las directivas proporcionadas por el marcado específico del módulo son en realidad bastante generales. No veo por qué no podrías o no usarías estas construcciones para documentar cosas de otros idiomas además de Python. Del mismo modo, Sphinx hace que sea bastante fácil mostrar ejemplos de código en otros idiomas . 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 crear una extensión Sphinx para arrancar algo relevante de tu código PHP.
Dicho todo esto, asegúrese de considerar la audiencia para su proyecto de documentación. Si bien creo que Sphinx es una herramienta excelente y lo recomendaría para una amplia gama de proyectos de documentación, si su audiencia espera algo más, tenga esto en cuenta. Por ejemplo, si estaba documentando un proyecto Java, es posible que gran parte de su audiencia esté esperando documentos de estilo Javadoc. Si se desvía de esa expectativa, asegúrese de que no sea solo para las patadas (es decir, le brinda mejores documentos de los que podría obtener) y esté preparado para (brevemente) defender lo que ha hecho de manera diferente (por ejemplo, con una Preguntas frecuentes respuesta o introducción).
Finalmente, cualquier documentación es mejor que ninguna documentación, independientemente de la herramienta utilizada para crearlos. Usa cualquier herramienta que te ayude, si es la diferencia entre sacar algo y no.