8

JavaとPythonのコードを部分的に含む共有リポジトリを使用しています。コードベースは主にPythonに基づいていますが、一部のライブラリはJavaで記述されています。

後でPython-Sphinxまたはプラグインで使用するためにJavaドキュメントを解析または前処理する可能性はありますか？

4

3 に答える 3

13

javasphinx ( Github ) (ドキュメント)

これをセットアップするためのすべての重要な詳細を見つけるのに時間がかかりました。

インストール

# Recommend working in virtual environments with latest pip:
mkdir docs; cd docs
python3 -m venv env
source ./env/bin/activate
pip install --upgrade pip

# Recommend installing from source:
pip install git+https://github.com/bronto/javasphinx.git

pypi バージョンではインポートが壊れているようで、これらの問題は最新のチェックアウトには存在していないようでした。

セットアップと構成

Sphinx のセットアップが既に完了していると仮定します。

重要: Java の「ドメイン」を sphinx に追加します。これはパッケージに埋め込まれており、一般的な拡張名前空間形式javasphinxには従いません。.ext.(これは私が何時間も見逃した詳細です):

# docs/sources/conf.py
extensions = ['javasphinx']

オプション:外部 javadoc リンクが必要な場合:

# docs/sources/conf.py
javadoc_url_map = {
    '<namespace_here>' : ('<base_url_here>', 'javadoc'),
}

ドキュメントの生成

javasphinxパッケージはシェル ツールを追加します。javasphinx-apidoc現在の環境がアクティブな場合は、単に として呼び出すjavasphinx-apidocか、そのフル パスを使用できます: ./env/bin/javasphinx-apidoc:

$ javasphinx-apidoc -o docs/source/ --title='<name_here>' ../path/to/java_dirtoscan

このツールは、次のものとほぼ同じ引数を取りますsphinx-apidoc。

$ javasphinx-apidoc --help
Usage: javasphinx-apidoc [options] -o <output_path> <input_path> [exclude_paths, ...]

Options:
  -h, --help            show this help message and exit
  -o DESTDIR, --output-dir=DESTDIR
                        Directory to place all output
  -f, --force           Overwrite all files
  -c CACHE_DIR, --cache-dir=CACHE_DIR
                        Directory to stored cachable output
  -u, --update          Overwrite new and changed files
  -T, --no-toc          Don't create a table of contents file
  -t TOC_TITLE, --title=TOC_TITLE
                        Title to use on table of contents
  --no-member-headers   Don't generate headers for class members
  -s SUFFIX, --suffix=SUFFIX
                        file suffix (default: rst)
  -I INCLUDES, --include=INCLUDES
                        Additional input paths to scan
  -p PARSER_LIB, --parser=PARSER_LIB
                        Beautiful Soup---html parser library option.
  -v, --verbose         verbose output

生成されたドキュメントをインデックスに含める

javasphinx-apidocコマンドの出力ディレクトリには、packages.rst生成された目次ファイルがあります。これを次のように index.html の目次に含めることができます。

#docs/sources/index.rst 

Contents:

.. toctree::
   :maxdepth: 2

   packages

ドキュメントのコンパイル (html)

Python 環境がアクティブであるか、パスが変更されている場合:

$ cd docs
$ make html
or 
$ PATH=$PATH:./env/bin/ make html
于 2016-07-11T02:03:45.283 に答える
6

javadocコマンドを使用すると、独自のdocletクラスを作成して使用し、選択した形式でドキュメントを生成できます。出力は直接人間が読める形式である必要はありません...したがって、Sphinx互換形式での出力を妨げるものは何もありません。

しかし、この特定の仕事をする既存のドックレットは見つかりませんでした。

参照：

アップデート

javasphinx拡張機能がより良い代替手段かもしれません。これにより、Javaソースコードに埋め込まれたjavadocコメントからSphinxドキュメントを生成できます。

于 2013-01-10T09:32:27.503 に答える
0

Sphinx には、JavaDoc を解析するための組み込みの方法が用意されていません。また、このタスク用のサード パーティの拡張機能については知りません。

おそらく、Sphinx の autodoc 拡張機能用に独自のドキュメンターを作成する必要があります。従うことができるさまざまなアプローチがあります。

  • JavaDoc を手動で解析します。ただし、Python 用の JavaDoc pParser があるとは思いません。
  • Doxygen を使用して JavaDoc を XML に解析し、その XML を解析します。Sphinx 拡張機能のBreatheはこれを行いますが、C++ の場合です。
  • Java 用のドックレットを作成して、JavaDoc を処理可能な任意の出力形式に変換し、この出力を解析します。
于 2013-01-10T09:37:14.307 に答える