sphinx-javalinkを使ってSphinxドキュメントからJavadocへのリンクをはってみる

Sphinxで作ったドキュメントから、Javadocへのリンクをはれる拡張のsphinx-javalinkの使い方。
※昔書いた、sphinxからjavadocへのリンク簡単に貼れる拡張 - しおしおのほうが使い方は簡単なんだけど、Java8で作られたドキュメントへのリンクがうまくできない問題があったりする。

インストール

pipを使ってインストールする。

pip install sphinx-javalink

拡張を使えるようにする

conf.pyのextensionsにこの拡張を使えるよう設定を追加する。
下のように、javalinkを追加する。

extensions = ['javalink']

javalinkに対する設定をする

conf.pyにいくつか設定を追加する。javalink_classpathの設定はわりと面倒な感じがある。

# 設定を追加するためのimport
import javalink

# Java8で生成したドキュメントへリンクをはる（デフォルトだと7)
javalink_default_version = 8

# クラスを探すためのライブラリのパスの設定
# javalink.find_rt_jar()と書くと、JAVA_HOMEからrt.jarを探してくれる
# 自分のプロジェクトのライブラリに対してリンクを貼りたい場合は、
# そのプロジェクトのjarのパスかビルド後のクラスファイルが
# 出力されるディレクトリを指定する必要がある。
javalink_classpath = [
    javalink.find_rt_jar(),
    '/home/siosio/junit-4.12.jar'
]

# Javadocのリンク先を列挙する。
# 列挙しておけば、あとは良さげにリンク先を設定してくれるらしい
javalink_docroots = [
    'https://docs.oracle.com/javase/jp/8/docs/api/',
    'http://junit.org/junit4/javadoc/latest/'
]

rstを書いて・・・

javarefを使って、リンクをはれる。
メソッドに飛ばす場合は、クラスメイトメソッド名を#で区切る。（Javadocの@seeの書き方とかと一緒）

* こんな感じにリンクをはれる →  :javaref:`java.lang.Object`
* メソッドに対しては、こんなかんじになる → :javaref:`java.lang.String#valueOf(java.lang.Object)`
* Javaのライブラリ以外もいける :javaref:`@Test <org.junit.Test>` アノテーションにもとべる

ビルドして・・・

こんな感じに生成される。