¿Cómo crear documentación basada en Sphinx en un proyecto Jython?

Estoy trabajando en varios proyectos Jython usando librerías escritas en Java. Me gustaría crear una buena documentación con Sphinx gracias a la extensión autodoc. Sin embargo, cuando intento crear el HTML, se producen errores porque autodoc no puede encontrar las bibliotecas escritas en Java:¿Cómo crear documentación basada en Sphinx en un proyecto Jython?

sphinx-build -b html -d _build/doctrees . _build/html 
Running Sphinx v1.0.5 
loading pickled environment... done 
building [html]: targets for 1 source files that are out of date 
updating environment: 0 added, 1 changed, 0 removed 
reading sources... [100%] index 

/Users/myName/myJythonProject/doc/index.rst:14: (WARNING/2) 
autodoc can't import/find module 'myJythonProject', it reported error: 
"global name 'PoolManager' is not defined", 
please check your spelling and sys.path

donde PoolManager es una clase Java.

¿Alguien podría ayudarme a resolver este problema?

Fuente

2011-02-08 Taurus Olson

Sry, no han utilizado Jython antes, pero ¿ha intentado crear un envoltorio que atrapará las invocaciones 'pitón' tal que cuando Sphinx llama a 'python' y termina llamando a su contenedor que llama a jython? La otra cosa, es que para mi proyecto tuve que envolver algunos de mis 'import's y códigos específicamente para Sphinx. ¿Puedes verificar una variable de entorno o alguna otra variable global antes de importar una biblioteca jython? Alternativamente, puede crear bibliotecas ficticias de python que tengan la misma interfaz que las bibliotecas de jython que está utilizando y solo importe estas variables ficticias mientras ejecuta Sphinx mediante [cont] –

manipulando la variable de entorno 'PYTHON_PATH' o' sys.path'. –

Gracias por su respuesta. Voy a intentar lo que propones. –

Sphinx se puede utilizar para documentar proyectos de Jython, pero autodoc no funciona para el código escrito en Java. La función autodoc importa e inspecciona los módulos de Python. No hay soporte para hacer lo mismo con las clases de Java.

Implementar autodoc (o algo similar) para Java parece factible, pero alguien tiene que ser voluntario para hacerlo. Vea este comentario del autor de la Esfinge Georg Brandl: http://www.mail-archive.com/[email protected]/msg03162.html.

Encontré algo de información sobre a proposed GSoC 2010 project con el objetivo de implementar el soporte de múltiples idiomas para autodoc. Pero de acuerdo con this blog post, el proyecto no se completó. El desarrollador eligió trabajar en otro proyecto de GSoC.

El sphinx-contrib repository no contiene nada relacionado con autodoc.

actualización

Hay una nueva extensión llamada Esfinge javasphinx que parece interesante. No he utilizado esta extensión, pero de acuerdo con the documentation, puede producir fuentes de reposo de código Java:

La herramienta javasphinx-apidoc es el contrapunto a la herramienta sphinx-apidoc dentro del dominio de Java. Se puede usar para generar fuente reST a partir del código fuente Java existente que se ha marcado con comentarios de estilo Javadoc. La reST generada se procesa junto con la documentación manuscrita de Sphinx.

javasphinx hace uso de otra biblioteca llamada javalang.

paquetes PyPI:

Fuente

2012-03-30 21:23:25 mzjn

Gracias por esta respuesta detallada. Eso confirma lo que pensé. Tendré que lidiar sin autodoc hasta que esto se implemente. –

¿Cómo crear documentación basada en Sphinx en un proyecto Jython?

Respuesta

Cuestiones relacionadas