しおしお

IntelliJ IDEAのことなんかを書いてます

sphinxからjavadocへのリンク簡単に貼れる拡張

Sphinx

Sphinxのドキュメントから、Javadocページ編のリンクを貼るのを簡単にするjavasphinx User’s Guide — javasphinx 0.9.8 documentationという拡張です。

この拡張を使うと、Javadocのトップページへのパスをconf.pyに設定して置けるので、
ここのページではクラスの完全修飾名を書くだけでよく割りと簡単にリンクが作成できます。

インストール

拡張のページに有るようにpipかeasy_installを使ってインストールします。

pip install javasphinx

か

easy_install -U javasphinx

javasphinx拡張を有効にする

拡張を使うためには、conf.pyのextensionsにこの拡張を追加する必要があります。

初期状態の場合、conf.pyに空の配列が設定されたextensionsがあるので以下のようにします。

extensions = ['javasphinx']

パッケージとJavadocページとのマッピング設定

この拡張機能は、パッケージ単位にJavadocのURLを設定します。
この設定は、conf.pyに対して行います。

例えば、spring(org.springframework)のJavadocページヘのマッピングは、以下のようになります。

javadoc_url_map = {
  'org.springframework' : ('http://docs.spring.io/spring-framework/docs/current/javadoc-api/', 'javadoc'),
}

リンクを書いてみる

SpringのRestTemplateへのリンクの場合、以下のように書きます。

:java:extdoc:`org.springframework.web.client.RestTemplate`

生成されたSphinxのドキュメントは、以下のようになります。
f:id:sioiri:20160403000039p:plain

リンクテキストを変えたい場合は、以下のように「リンクテキスト <クラスの完全修飾名>」とします。

:java:extdoc:`RestTemplate <org.springframework.web.client.RestTemplate>`

f:id:sioiri:20160403000219p:plain

メソッドへのリンクは、完全修飾名の後にドット(.)+メソッド名で書きます。
メソッドの引数も正確に書く必要があります。

* :java:extdoc:`String#toString <java.lang.String.toString()>`
* :java:extdoc:`String#replace <java.lang.String.replace(java.lang.CharSequence,%20java.lang.CharSequence)>`

生成されたSphinxのドキュメントは、以下のようになります。
f:id:sioiri:20160403001216p:plain

おわり。