Software autónomo para generar documentación HTML estática a partir de Markdown

Estoy buscando una herramienta que pueda generar páginas HTML estáticas a partir de archivos de descuento. Hasta ahora todo bien, hay muchos por ahí:

Mi problema es que me gustaría escribir documentación para un repositorio de software autónomo. Debería funcionar de la siguiente manera:

  • El desarrollador inicia su estación de trabajo (Windows 7 estándar)
  • El desarrollador revisa el repositorio (que contiene archivos de descuento y la herramienta para generar)
  • El desarrollador ejecuta la generación de documentos, digamos llamandocreateDocs.bat
  • El desarrollador abre el index.html generado en su navegador

Mi problema ahora es que todas las herramientas mencionadas anteriormente necesitan algún tipo de entorno configurado de antemano: node.js, Python y módulos adicionales, ... Sin embargo, la idea detrás del entorno autónomo es

  • Se ejecuta en hosts fuera de línea
  • Se ejecuta en hosts donde no es posible instalar software
  • Se ejecuta detrás de un proxy corporativo

¿Alguien conoce una buena herramienta que funcione de esa manera? ¿Hay formas de hacer que las herramientas mencionadas anteriormente funcionen? Acabo de probar muchas cosas como convertir mkdocs con py2exe pero no he tenido éxito...

¿Por qué se ejecuta en hosts donde no es posible instalar software como requisito? Ha utilizado la palabra "desarrollador"; presumiblemente tiene cierto control de su máquina y puede "instalar software", incluso insiste en que puede "verificar el repositorio", lo que significa que debe tener (como cuestión práctica) un software de administración de versiones instalado.

Respuestas (2)

doxígeno

Doxygen es una herramienta de documentación de código de propósito general. Admite Markdown a partir de la versión 1.8.0 y puede generar archivos HTML estáticos entre muchos otros formatos.

Características:

  • Multiplataforma. Funciona en todas las versiones de Windows desde XP
  • Tiene una instalación portátil que puede empaquetar con su repositorio para que se ejecute sin conexión y sin privilegios de administrador:

Su flujo de trabajo requerido se puede lograr fácilmente con doxygen:

Con la mayoría de los VCS, es una muy mala idea verificar los binarios: hay mucha discusión en la red sobre por qué, pero básicamente, si no es el código fuente, no pertenece al VCS.
@SteveBarnes Cierto. En este caso, basta con verificar la configuración y los archivos por lotes, ya que cualquiera podría descargar y ejecutar el ejecutable desde el sitio web de Doxygen.
Según tengo entendido, no está mal verificar los binarios per se. Es solo un problema si también tiene las fuentes disponibles (entonces es redundante). En el caso de doxygen u otro tercero, es una buena manera de garantizar que el entorno con el que se construye el software se mantenga igual.
@MOnsDaR Definitivamente no hay ninguna regla en contra. Creo que la mayoría de los argumentos afirman que, dado que no puede usar herramientas de VC (como diff) en binarios, no tiene sentido versionarlos. Pero en tu caso, creo que la conveniencia de tener el ejecutable en una ruta específica es razón suficiente para incluirlo.
Algunos (muchos) sistemas VCS se vuelven muy lentos y difíciles de manejar cuando tienen binarios almacenados en ellos; mi enfoque preferido es tener una ubicación conocida donde se almacenan una o más versiones específicas de los binarios de entrada y una secuencia de comandos controlada por versión que obtiene el versión requerida. Entonces sigue siendo un proceso de dos pasos: actualizar desde VCS y luego hacer (igual que si la herramienta estuviera en el VCS). puede vincular una versión específica de la herramienta para una versión determinada de su fuente, etc. También en la empresa para la que trabajo hay una regla específica en contra.
Esta discusión se aleja un poco de la pregunta original, lo siento. @Steve: si está almacenando los binarios en un servidor y crea un script de usuario que obtiene la versión correcta, ¿no está simplemente reconstruyendo manualmente para qué está diseñado un VCS? ¿Cómo sabes qué binarios se ajustan a qué revisión? ¿Cómo podría garantizar que una revisión específica tenga los binarios correctos en el sitio? Estos son algunos de los problemas más grandes en mi experiencia: 1. Tener el entorno correcto configurado antes de poder hacer las cosas 2. Reproducir lo que una vez funcionó con una versión específica de terceros

Puedo pensar en algunas opciones para ti:

Binarios autónomos

  1. Python portátil : probablemente necesite elegir uno de los generadores de documentos anteriores, o posiblemente Sphinx , y agregarlo a su "instalación" de Python portátil.
  2. Pandoc construido como un binario reubicable como se explica aquí .

Los dos anteriores cumplen con el requisito de:

  • Se ejecuta en hosts fuera de línea
  • Se ejecuta en hosts donde no es posible instalar software
  • Se ejecuta detrás de un proxy corporativo

Pero en cualquiera de los casos anteriores, recomendaría encarecidamente modificar el flujo de trabajo deseado para agregar un paso de "desarrollador descarga y desempaqueta la herramienta", ya que hay muchas razones para no poner archivos binarios en los sistemas de control de revisión y muchos VCS corporativos tienen políticas específicas. para evitar que lo hagas.

Servidor dentro del cortafuegos

La otra opción podría ser crear un servidor de generación de documentos en línea pero detrás del firewall corporativo. Esto no funcionaría sin conexión, pero proporcionaría mucho más control sobre qué software se usa. También podría integrarse con el VCS a través de enlaces para que el flujo de trabajo se modifique a:

  • El desarrollador inicia su estación de trabajo
  • El desarrollador verifica el repositorio: debe estar en línea para hacer esto
  • El gancho posterior al pago envía el descuento al servidor del generador de documentos, mientras todavía están en línea , lo que genera el html en su disco local.
  • El desarrollador realiza cambios en el descuento; esto se puede hacer sin conexión .
  • El desarrollador genera html a partir del descuento modificado para verificar su trabajo; debe estar en línea o tener una instalación local de la misma herramienta para hacer esto.
  • El desarrollador confirma los cambios nuevamente, debe estar en línea para esto de todos modos

Esto no cumple con su primer requisito, pero ofrece algunas ventajas:

  • Puedes usar casi cualquier herramienta que necesites
  • No hay problemas con las herramientas de control de versiones.
  • No todos sus desarrolladores tienen que ejecutar Windows
  • Su generador de documentos puede tener acceso a recursos que quizás no desee instalar en la máquina de los desarrolladores, por ejemplo, el html podría incluir informes generados desde su sistema de seguimiento de problemas o desde un sistema de informes de progreso.
Ya pensé en montar un servidor para generar la documentación. Ambos métodos tienen sus propias ventajas. Hablaremos de eso mañana.
Software autónomo para generar documentación HTML estática a partir de Markdown
RespuestasAquíPolítica de privacidad1y, 0v