Как создать документацию на основе Sphinx в проекте Jython?

Я работаю над несколькими проектами Jython, используя библиотеки, написанные на Java. Я хотел бы создать хорошую документацию с помощью Sphinx благодаря расширению autodoc. Однако, когда я пытаюсь создать html, я получаю ошибки, потому что autodoc не может найти библиотеки, написанные на 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

где PoolManager — это класс Java.

Может ли кто-нибудь помочь мне решить эту проблему?


python java python-sphinx jython
person Taurus Olson    schedule 08.02.2011    source источник
comment
Извините, раньше не использовали Jython, но пытались ли вы создать оболочку, которая будет перехватывать вызовы «python», так что когда Sphinx вызывает python, он в конечном итоге вызывает вашу оболочку, которая вызывает jython? Во-вторых, для моего проекта мне пришлось обернуть некоторые из моих import и код специально для Sphinx. Можете ли вы проверить переменную среды или какую-либо другую глобальную переменную, прежде чем импортировать библиотеку jython? В качестве альтернативы вы можете создать фиктивные библиотеки Python с тем же интерфейсом, что и библиотеки jython, которые вы используете, и импортировать эти фиктивные библиотеки только во время работы Sphinx [продолжение]   -  person Ross Rogers    schedule 10.02.2011
comment
управление переменной окружения PYTHON_PATH или sys.path.   -  person Ross Rogers    schedule 10.02.2011
comment
Спасибо за ваш ответ. Я попробую то, что вы предложили.   -  person Taurus Olson    schedule 01.03.2011
comment
Я столкнулся с аналогичной проблемой при попытке создать документацию для моего кода C++ (экспортированного в python). Инструмент, который я использовал для создания привязок Python — sip, имел несколько вариантов экспорта документации. слишком. Тот, который вы используете для Java, тоже может иметь это.   -  person Swapnil    schedule 19.02.2012

Ответы (1)


arrow_upward
6
arrow_downward

Sphinx можно использовать для документирования проектов Jython, но autodoc не работает для кода, написанного на Java. Функция autodoc импортирует и проверяет модули Python. То же самое нельзя делать с классами Java.

Реализация autodoc (или чего-то подобного) для Java кажется осуществимой, но кто-то должен сделать это добровольно. См. этот комментарий автора Sphinx Георга Брандла: https://www.mail-archive.com/[email protected]/msg03162.html.

Я нашел некоторую информацию о предлагаемый проект GSoC 2010, направленный на реализацию поддержки нескольких языков для autodoc. Но согласно этой записи в блоге проект не был завершен. Разработчик решил работать над другим проектом GSoC.

репозиторий sphinx-contrib не содержит ничего, связанного с autodoc.

Обновить

Существует новое расширение Sphinx под названием javasphinx, которое выглядит интересно. Я не использовал это расширение, но согласно документации , он может создавать источники reST из кода Java:

Инструмент javasphinx-apidoc является контрапунктом инструменту sphinx-apidoc в домене Java. Его можно использовать для создания исходного кода reST из существующего исходного кода Java, который был размечен комментариями в стиле Javadoc. Сгенерированный reST затем обрабатывается Sphinx вместе с рукописной документацией.

javasphinx использует другую библиотеку под названием javalang.

Пакеты PyPI:

person mzjn    schedule 30.03.2012
comment
Спасибо за этот подробный ответ. Это подтверждает то, что я думал. Мне придется иметь дело без autodoc, пока это не будет реализовано. - person Taurus Olson; 11.04.2012