Generando la página del manual de CLI en Python

Estoy desarrollando una herramienta CLI de python (usando optparse en python2.6, pero espero cambiar pronto a python2.7) y estoy a punto de escribir la página del manual. Tengo algo de experiencia en la generación de páginas de manual dinámicas por:

  • creando un método dedicado que compone una cadena en formato pod y la escribe en un archivo
  • ejecutando el comando pod2man para generar datos en formato groff para pasarlos al comando man

También me gustaría generar páginas wiki con el mismo contenido que la página man (con pod puedo generar html a través de pod2html , y probablemente el html se puede traducir fácilmente al formato wiki). ¿Alguien tiene una mejor idea / flujo sobre cómo hacer esto?

Una cosa que me ha parecido interesante es en este enlace: Creación de páginas de comando man usando optparse y distutils

La forma habitual de generar documentación en Python es usar Sphinx . Por ejemplo, eso es lo que se usa en la documentación oficial de Python. Una vez que haya configurado un proyecto de documentación de Sphinx (consulte este tutorial ), puede generar páginas man desde los archivos de documentación de Sphinx a través de make man . También debe modificar la configuración en conf.py para producir un resultado apropiado.

(Vale la pena señalar que si bien Sphinx es la herramienta habitual para escribir documentación en Python, eso no significa que sea la herramienta habitual para generar páginas man. ¡Use lo que quiera!)

Si bien la esfinge es un excelente sistema de documentación, es tremendamente complejo y difícil de dominar. Si necesita una solución rápida , le sugiero que busque en mi proyecto build_manpage.py .

No reemplaza la documentación adecuada de sus proyectos (con la esfinge o la forma que elija). Pero tiene algunos beneficios inmediatos para un progtwigdor de Python:

  • No tienes que aprender la syntax del man .
  • No tienes que aprender la rst syntax (sin embargo, un día deberías aprenderla …)
  • No necesita mantener su optparser \ argparser y una página de manual con formato en archivo externo (en man, rst, o cualquier otro sistema de conversión).

  • Simplemente agrega un archivo a la configuración de comstackción y se crea una página de manual para usted.

Si desea utilizar un sistema más complicado, con muchos avisos, sphinx le permite convertir una página en rst una página de manual. Y un proyecto joven recientemente, tiene un enfoque similar a mi analizador y escanea su ArgumentParser para producir una rst página formateada, con directivas de esfinge (de modo que no necesita escribirlo usted mismo. En contraste, mi escáner produce una página de manual directamente ).

Tenga en cuenta que esto es ahora parte de una solicitud de extracción para agregar un formateador de páginas de manual en la biblioteca estándar .

Si está usando click puede usar click-man . Puede generar páginas man desde aplicaciones de click.