Generando documentos API en Git Workflow

No estoy seguro si esto debería estar aquí o en Progtwigdores .

Generando documentos API

Me gustaría get algunos consejos sobre cómo debería generar la documentation de API para un proyecto interno. Soy relativamente nuevo en Git y estamos tratando de implementar algunas prácticas sólidas de compilation / implementación.

Una de las cosas que discutimos fue asegurarnos de que nuestra base de códigos esté bien documentada y generar documentation usando algo como PhpDocumentor2 o una de las muchas herramientas similares.

Hemos comenzado a implementar un flujo de trabajo similar al detallado aquí .


¿Debo automatizar cuando se crean los documentos?

Por ejemplo, un enlace pre o post commit en git al labelr un lanzamiento. ¿O debería, cuando me fusioné desarrollar una twig de publicación, crear manualmente los documentos y comprometerme con el repository?

¿Es una práctica estándar tener documentos generados para cada lanzamiento?

Podría haber malinterpretado el process, ¿debería correlacionarse una nueva versión del documento con un lanzamiento / label de git?

¿Dónde almacena los documentos generados?

En el mismo repository? un repository diferente? ¿Hospedado en algún lugar como Read The Docs o solo internamente? El proyecto actual en el que estamos trabajando es solo pequeño, pero nos gustaría implementar el process en otros proyectos más grandes en el futuro si tiene éxito.

Context

El proyecto es una extensión de Magento que nos gustaría proporcionar documentos de API, testings de unidades y código conforme a PSR. Me falta información sobre cómo se integra todo el flujo de trabajo. PHPunit y PHPDocumentor2 se instalan localmente a través de Composer.

He escuchado y visto a Travis Ci, pero no estoy seguro de si los Documentos entran en esa categoría.

Esta pregunta puede parecer mezquina y / o trivial, sin embargo, no tengo mucha experiencia en integración y flujo de trabajo git y no pude encontrar mucha información.

Generado documentado generalmente son:

  • siempre en synchronization con el código fuente (por lo que la pregunta de "¿debería correlacionarse una nueva versión del documento con un lanzamiento / label git?" se convierte en discutible)
  • no almacenado en un control de versiones referencel (como un repository de git), sino más bien (re) generado a voluntad (en cualquier location que desee).

Si observa un proyecto con una gran fuente de código y una extensa documentation de código, puede tomar como ejemplo el idioma Go y su repository (un repository mercurial, pero también tiene mirror en GitHub )

  • las documentaciones estáticas como las especificaciones, los artículos, las notas de la versión, … son keys dentro del repository, ya que no se generan, sino que se actualizan manualmente y están estrechamente vinculadas a las fonts.
  • La documentation del código se guarda por separado en un website estático.
  • La documentation para todo el proyecto go se guarda en un website estático GoDoc , que searchá las fonts de los proyectos Go y generará la documentation a partir de ellos.