7

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?

mzjn
  • 48,958
  • 13
  • 128
  • 248
Taurus Olson
  • 3,153
  • 2
  • 26
  • 21
  • Sry, haven't used Jython before, but have you tried creating a wrapper that will trap the 'python' invocations such that when Sphinx calls `python` it ends up calling your wrapper which calls jython? The other thing, is for my project I had to wrapper some of my `import`s and code specifically for Sphinx. Can you check an environment variable or some other global variable before you import a jython library? Alternatively, you can create dummy python libraries that have the same interface as the jython libraries you're using and only import these dummies while running Sphinx by [cont] – Ross Rogers Feb 10 '11 at 01:45
  • manipulating environment variable `PYTHON_PATH` or `sys.path`. – Ross Rogers Feb 10 '11 at 01:47
  • Thank you for your answer. I will try what you proposed. – Taurus Olson Mar 01 '11 at 15:51
  • I'v faced similar problem while trying to create documentation for my C++ code (exported to python). The tool I was using for creating python bindings - [sip](http://www.riverbankcomputing.com/software/sip/intro) had some options for exporting the documentation too. The one that you'r using for java might have that too. – Swapnil Feb 19 '12 at 10:28

1 Answers1

6

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/sphinx-dev@googlegroups.com/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:

alexia
  • 14,440
  • 8
  • 42
  • 52
mzjn
  • 48,958
  • 13
  • 128
  • 248
  • Thanks for this detailed answer. That confirms what I thought. I will have to deal without autodoc until this is implemented. – Taurus Olson Apr 11 '12 at 13:17
  • The javasphinx project is no longer active. See https://github.com/bronto/javasphinx and https://github.com/sphinx-doc/sphinx/issues/10054. – mzjn Jan 16 '22 at 10:21