PHPDoc a la wiki de GitHub

¿sabes si esta herramienta de documentation de código existe?

Mi intención para un [proyecto] genérico sería:

  1. Escribir documentation de PHPDoc
  2. Generar el descuento (o ASCIIDoc o criollo, etc. )
  3. Importar documentation generada en el directory GitHub [proyecto] .wiki

Si no existe, ¿cómo puedo usar las herramientas existentes para hacer algo como esto?

Gracias

Excelente pregunta! Todavía no he visto una herramienta que haga esto, pero creo que sería muy útil. He hecho una revisión rápida, y creo que no debería ser tan difícil build algo así.

Eche un vistazo a esta página del manual de PHPDocumentor.

Parece que tendrá que crear su propia transformación, como las que se utilizan actualmente para crear HTML, PDF y charts. Posiblemente también se necesitará una plantilla con algún estilo específico de GitHub.

Pude get phpDoc en la wiki de Github sin demasiado esfuerzo. Esto sigue siendo un trabajo en progreso, pero mira esto … esto es directamente de mi código GitHub que se comenta en parte con phpDoc: https://github.com/charlestonsoftware/WPCSL-generic/wiki/_pages

Aquí está el esquema básico. Voy a refinar más tarde esta noche y publicaré un artículo en mi blog paso a paso y el código corregirá lo necesario, pero esto debería comenzar la mayoría de ustedes:

Ve a clonar tus páginas de Wiki de GitHub

Vaya a su proyecto GitHub y busque la pestaña Wiki. Si no lo tiene, especialmente para un proyecto anterior, puede necesitar habilitar "páginas" en la configuration del repository en GitHub.

Debajo de la pestaña Wiki hay una sub-pestaña para "Git Access". Tiene la URL de repository WIKI, que se adjuntará automáticamente al proyecto principal en la pestaña wiki.

Clona esto en un nuevo directory en tu cuadro dev.

(Por cierto, este paso es opcional, así es como opté por hacer esto, mantener los documentos fuera de mi repository de código principal).

Configurar / build la herramienta PHPDocMD

  1. Ve a clonar esto en un directory limpio en tu cuadro de desarrollo: https://github.com/evert/phpdoc-md
  2. Vaya al nuevo directory phpdocmd y vaya al directory src.
  3. Ve clonando Twig debajo de un nombre de directory Twig: https://github.com/fabpot/Twig
  4. Ajusta el código phpdoc-md, simplemente edita el file ./bin/phpdocmd para que la parte superior se vea similar a esto:
$docmdDir = dirname(__FILE__); set_include_path(get_include_path().PATH_SEPARATOR.$docmdDir.'/../src/Twig/lib'); // Potential composer autoloader paths $paths = array( $docmdDir . '/../src/PHPDocMD/Parser.php', $docmdDir . '/../src/PHPDocMD/Generator.php', $docmdDir . '/../src/Twig/lib/Twig/Autoloader.php', ); foreach($paths as $path) { if (file_exists($path)) { include $path; print "including $path\n"; } } Twig_Autoloader::register(); // Everts crappy option parser. 

Estas ediciones de código son necesarias porque la herramienta aún no se ha perfeccionado. Estaba claramente configurado para el sistema del desarrollador que tiene instalado Twig y un file de autocargador de proveedor que no está en el repository git. No es un gran problema, lo suficientemente fácil de recorrer si sigues los pasos aquí.

Por cierto, ese último comentario es suyo, no mío. Salí si estaba allí para saber dónde detener la edición.

Ejecute las herramientas PhpDoc y PHPDocMD

Es posible que desee vincular simbólicamente ese phpdocmd a su directory / usr / bin para que no tenga que escribir la ruta completa cada vez, pero ahora solo necesita unos pocos pasos para crear files doc compatibles con Wiki GitHub:

 # phpdoc -t . -d . 

Eso crea el file structure.xml necesario para generar los files MD.

Luego ejecuta este command:

 # phpdocmd ./structure.xml <path to your github WIKI project> 

Ahora su proyecto de GitHub Wiki Docs debe estar lleno de files MD que reflejen su código PHPDocs. Simplemente devuelva los files de GitHub Wiki al server de GitHub.

HTH. Probablemente necesite un refinamiento, pero creo que todos podemos incorporarnos al proyecto PHPDocMD y ayudar al autor original con las características y los ajustes.

Esto no es exactamente eso, pero aquí puede tener siempre phpDocs actualizados de sus repositorys GitHub: http://github-phpdoc.israelviana.es

Implementé el path de Charleston.

Por favor, eche un vistazo a

https://github.com/webcraftmedia/lib_phpdoc_md

Uso:

https://github.com/webcraftmedia/system/blob/master/sai/modules/saimod_sys_docu/saimod_sys_docu.php

Echa un vistazo a

 public static function sai_mod__SYSTEM_SAI_saimod_sys_docu_action_generate() 

y

 public static function sai_mod__SYSTEM_SAI_saimod_sys_docu_action_generate_md() 

para un ejemplo de cómo include y llamar a esas classs.

La function _generate usa lib_phpdocumentor para generar el documento. La function _generate_md utiliza el documento phpdocumentor generado para generar los files gdmd wiki md utilizando phpdoc-md.

Hay algunos proyectos que apuntan a hacer esto:

  • PHPDoc-MD (convierte la salida de phpdocumentor usando structure.xml ), por Evert Pot
  • phpdoc-markdown-public (una plantilla phpdocumentor), por Carl Vuorinen ( ejemplo )