sphinx-JDLinker

A sphinx extension designed to allow you to create links to a JavaDoc website from your sphinx documentation.


Keywords
javadoc, link, sphinx, documentation, sphinx-extension, javadoc-links, sphinx-jdlinker, javadoc-website
License
MIT
Install
pip install sphinx-JDLinker==1.2.2

Documentation

sphinx-JDLinker

sphinx-JDLinker is a custom Sphinx extension that allows you to link to a JavaDoc website through your documentation.

sphinx-JDLinker does not require local jars, nor does it attempt to connect to any JavaDoc website. Instead, what it does is attempt to parse a JavaDoc role in order to produce the desired output: a link to the JavaDoc website.

Installing

sphinx-JDLinker is available on PyPI:

pip install sphinx-JDLinker

Minimum Requirements

There's a few requirements to keep in mind when using sphinx-JDLinker. Because sphinx-JDLinker relies completely on string manipulation, it can be easy to mess up. However this comes at the advantage of not having to use local jars, or connect to any JavaDoc website.

  • Sphinx 1.3
  • Online JavaDoc Website (I hope you have this if you're here!)
  • Java packages must be lower case. The reason for this is that sphinx-JDLinker has to determine the difference between a normal class and an internal class. Hopefully your project should already follow this. If it doesn't, I'd highly advise fixing this!
  • Default packages are not supported. Again, fix this if your project is using default packages!

Most projects should already easily meet these requirements anyway, so no worries here.

Usage

Using sphinx-JDLinker is relatively simple. The first thing you must do is add the javadoc_links config option to your conf.py:

javadoc_links = {'http://myjavadocwebsite.com/': ['my.root.package']}

Now let's explain this a bit. The javadoc_links variable must be a dictionary, storing the JavaDoc url as well as a list of 'root packages'. The root package is essentially what sphinx-JDLinker uses to identify a JavaDoc reference, so that the linking to multiple JavaDoc websites does not collide. So if your Java files begin at com.my.package, then when sphinx-JDLinker sees a JavaDoc reference in your documentation that begins with com.my.package, it will know that you're attempting to link to the corresponding com.my.package JavaDoc website.

The root packages are stored as a list as to allow multiple root packages. An example of multiple root packages may be found below:

javadoc_links = {'http://myjavadocwebsite.com/': ['my.root.package', 'some.other.package']}

Now we need to add sphinx-JDLinker to sphinx itself. In your conf.py file, add jdlinker to your extensions:

extensions = ['jdlinker']

Now that we've set the config options, it's time to create JavaDoc links in our sphinx documentation. We need to create a JavaDoc role:

:javadoc:`com.my.package.MyJavaClass`

It's as simple as that. This will create a reference to MyJavaClass pointing to the set JavaDoc website for com.my.package. Of course, more advanced linkages are supported as well:

:javadoc:`com.my.package.MyClass.MyInternalClass#myMethod(com.my.package.MyJavaClass, com.my.package.MyOtherClass)`

This will point to the method myMethod(MyJavaClass, MyOtherClass) for MyClass.MyInternalClass, automatically creating a reference to the method specified. Note that generics are also supported:

:javadoc:`com.my.package.MyClass<Foo>`

Since the generic isn't used in the url, it is not necessary to specify the full package of Foo. The generic is only used for display.

We can also link to fields:

:javadoc:`com.my.package.MyClass#MY_FIELD`

We can even link to the page for a specified package:

:javadoc:`com.my.package`

Imports

Of course, if you want to keep the source documentation clean from all of these long packages that are required for linking, we can use imports. Imports are specified via a javadoc-import directive:

.. javadoc-import::
    com.my.package.MyClass
    com.my.package.MyOtherClass

Now when we want to link to MyClass or MyOtherClass, it's as simple as this:

:javadoc:`MyClass`
:javadoc:`MyOtherClass`

Imports will also work for method parameters:

:javadoc:`MyClass#myMethod(MyOtherClass)`

Override Display Text

By default, the text that is displayed on the documentation is generated by the JavaDoc link present. If we want to change the text that is displayed, we can use curly braces to override the display text on a JavaDoc link:

:javadoc:`MyClass {SomeOtherThingHere}`

The JavaDoc link will still link to MyClass, however the link will display SomeOtherThingHere on the documentation. This may be useful for longer linkages that documentation editors may want to shorten.

Advanced

An advanced debug option is available that you may specify in your conf.py file. If enabled, the javadoc_dump option will dump all of the JavaDoc references into a javadoc_dump.txt file. It is highly recommended to keep this disabled in production!

Updating

If there comes to be a time that the documentation project's JavaDoc links need to be updated, you may use jdlinker-parser to help identify what needs to be updated. It will tell you what specific JavaDoc links that could not be found, as well as where the link was found.