How to create Sphinx-based documentation in a Jython project?

Question

I'm working on several Jython projects using libraries written in Java. I'd like to create some good documentation with Sphinx thanks to the autodoc extension. However when I try to create the html, I get errors because autodoc can't find the libraries written in Java:

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

where PoolManager is a Java class.

Could anyone help me to solve this problem?

Answer 1

Sphinx can be used to document Jython projects, but autodoc does not work for code written in Java. The autodoc feature imports and inspects Python modules. There is no support for doing the same with Java classes.

Implementing autodoc (or something similar) for Java seems feasible, but someone has to volunteer to do it. See this comment by Sphinx author Georg Brandl: https://www.mail-archive.com/[email protected]/msg03162.html.

I found some information about a proposed GSoC 2010 project aiming at implementing multiple language support for autodoc. But according to this blog post, the project wasn't completed. The developer chose to work on another GSoC project.

The sphinx-contrib repository does not contain anything related to autodoc.

---

Update

There is a new Sphinx extension called javasphinx that looks interesting. I have not used this extension, but according to the documentation, it can produce reST sources from Java code:

The javasphinx-apidoc tool is the counterpoint to the sphinx-apidoc tool within the Java domain. It can be used to generate reST source from existing Java source code which has been marked up with Javadoc-style comments. The generated reST is then processed alongside hand-written documentation by Sphinx.

javasphinx makes use of another library called javalang.

PyPI packages:

• https://pypi.org/project/javasphinx/
• https://pypi.python.org/pypi/javalang