ejemplos - Usando el apidoc de Sphinx para generar documentación a partir de código C++

ejemplos de documentacion de codigo

Question

Ha habido un par de hilos sobre este tema en el pasado que afirman que Sphinx no admite esto en absoluto. Tenía mis dudas, pero o bien se ha actualizado desde entonces o la documentación estaba bastante bien oculta, porque aquí hay un enlace en el sitio web que indica lo contrario: http://sphinx.pocoo.org/latest/domains.html#array:T:::subscript-operatorC

De todos modos, soy nuevo en Sphinx pero estoy tratando de usarlo para automatizar (eventualmente) la documentación usando algún texto de algún código fuente de C ++. Hasta ahora no he podido llegar a ninguna parte al usar el comando sphinx-apidoc -o ....... Se crea un documento casi en blanco. Probablemente no esté usando las directivas correctas, ya que no sé cómo, la documentación de respaldo no ha podido ayudarme.

¿Alguien puede proporcionar ayuda con los pasos básicos necesarios para que funcione? Si no es posible generar automáticamente la documentación desde C ++, ¿para qué sirven los dominios de C ++ y cómo usarlos?

Answer 1

En la generación automática de documentación en C ++:

Después de leer sobre cómo usar la esfinge , deberías echar un vistazo a la breathe :

Breathe proporciona un puente entre los sistemas de documentación Sphinx y Doxygen.

Es una forma fácil de incluir información de Doxygen en un conjunto de documentación generada por Sphinx. El objetivo es producir un soporte de autodoc para personas que disfrutan utilizando Sphinx pero que trabajan con otros idiomas además de Python. El sistema se basa en la salida xml de Doxygen.

Así que, además, deberá seguir el estilo de comentarios de Doxygen e incluso configurar un proyecto doxygen. Pero lo intenté y funciona muy bien después de la configuración inicial. Aquí hay un extracto de nuestro CMakeLists.txt que podría darle una idea de cómo la esfinge y el doxygen trabajan juntos:

macro(add_sphinx_target TARGET_NAME BUILDER COMMENT_STR)
    add_custom_target(${TARGET_NAME}
    COMMAND sphinx-build -b ${BUILDER} . sphinx/build/${BUILDER}
        WORKING_DIRECTORY docs
        DEPENDS doxygen
        COMMENT ${COMMENT_STR}
    )

endmacro(add_sphinx_target)

add_custom_target(doxygen
    COMMAND doxygen docs/doxygen.conf
    COMMENT "Build doxygen xml files used by sphinx/breathe."
)

add_sphinx_target(docs-html
    html
    "Build html documentation"
)

Así que después de la configuración inicial, esencialmente se reduce a:

1. construir la documentación de doxygen path/to/config con la doxygen path/to/config
2. cd en el directorio donde está la configuración de la esfinge.
3. construir la documentación de la sphinx-build . path/to/output con sphinx-build . path/to/output sphinx-build . path/to/output

En el dominio c ++:

Sphinx es un "poco" más que un sistema para generar automáticamente la documentación. Le sugiero que eche un vistazo a los ejemplos (y considere que el sitio web de la esfinge en sí está escrito en el código reST de la esfinge) Especialmente haga clic en el enlace Show Source en muchas páginas generadas por esfinge.

Entonces, si no puede generar documentación automáticamente para un proyecto, debe hacerlo usted mismo. Básicamente, la esfinge es una repetición para cualquier compilador (LaTeX, HTML, ...). Así que puedes escribir texto arbitrario, pero la ventaja es que tiene muchos comandos para documentar el código fuente de diferentes idiomas. Cada idioma obtiene su propio dominio (prefijo o espacio de nombres) para separar los espacios de nombres de los diferentes idiomas. Entonces, por ejemplo, puedo documentar una función de python usando:

.. py:function:: Timer.repeat([repeat=3[, number=1000000]])
    Does something nasty with timers in repetition

( source )

Puedo hacer lo mismo usando el dominio cpp:

.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)

   Describes a method with parameters and types.

( source )

Entonces, si desea documentar su proyecto c ++ sin doxygen + respira pero con esfinge, tendrá que escribir usted mismo los archivos de texto reestructurados. Esto también significa que divide la documentación de su código fuente, lo que puede ser indeseable.

Espero que eso aclare un poco las cosas. Para obtener más información, le sugiero encarecidamente que lea detenidamente el tutorial y la documentation sphinx hasta que haya entendido lo que realmente hace.