¿Existe una buena manera de producir documentación para las interfaces swig?

Question

Me gustaría saber si hay algunas buenas técnicas para construir/mantener la documentación de en la interfaz.

Estoy construyendo una interfaz desde código C++ a python usando swig; en su mayoría soy % incluyendo los archivos de encabezado C++. Estoy tratando con al menos docenas de clases y cientos de funciones, por lo que se prefieren las herramientas automáticas.

Idealmente, me gustaría utilizar los comentarios formateados doxygen en los encabezados de C++ a llene las cadenas de documentos en las clases/métodos de python.

De forma alternativa, generar documentación separada (en ascii, html ...) también sería útil. Parece que este tipo de funcionalidad era compatible con en versiones anteriores de swig (1.3 y anterior) pero no veo una manera de hacerlo con 2.0.

¿Existen técnicas útiles (automatizadas) para documentar la interfaz?

Answer 1

Hay algo de kilometraje en %feature("autodoc") con SWIG 2.0, que creo que es lo más lejos que va actualmente.

Por ejemplo:

%module test 

%feature("autodoc", "3"); 

void foo (int *a, void *bar, double epsilon); 

provoca algún tipo de documentación vagamente cuerdo a insertar.

Si eso no es suficiente Creo que el próximo paso más fácil sería utilizar %pythonprepend para hacer un marcador que es único lo suficientemente sed o similar se puede utilizar para insertar la documentación en el interfaz después TRAGO se ejecute automáticamente:

%pythonprepend foo "MARKER" 

y luego:

sed -ei 's/MARKER/some documentation' test.py 

¿Dónde se puede encontrar a las funciones %pythonprepend mirando por encima de la salida de Doxygen usando un (Python?) script para generar los marcadores y sustituirlos después de r desatando SWIG.

Answer 2

Para obtener sus comentarios doxygen en los archivos python existe una herramienta python llamada doxy2swig.py en la web como se describe here.

Crea la documentación xml de tu código. A continuación, utilice la herramienta:

doxy2swig.py index.xml documentation.i

e importación documentation.i en que swig archivo de interfaz a través de

% importación "documentation.i"

Y listo.