
#######################
javasphinx User's Guide
#######################

Welcome to the javasphinx user's guide.

Introduction
============

javasphinx is a Sphinx_ extension that provides a Sphinx domain_ for documenting
Java projects and a ``javasphinx-apidoc`` command line tool for automatically
generating API documentation from existing Java source code and Javadoc
documentation.

.. _Sphinx: http://sphinx-doc.org
.. _domain: http://sphinx-doc.org/domains.html

Installing
==========

javasphinx is available in the Python Package Index (PyPi) and can be installed
using tools such as ``pip`` or ``easy_install``,

.. code-block:: sh

   $ pip install javasphinx

or,

.. code-block:: sh

   $ easy_install -U javasphinx

Configuration
=============

To enable javasphinx for your existing Sphinx configuration add ``'javasphinx'``
to the list of extensions in your conf.py file. javasphinx can be configured to
cross link to external sources of documentation using the ``javadoc_url_map``
option,

.. code-block:: python

   javadoc_url_map = {
       'com.netflix.curator' : ('http://netflix.github.com/curator/doc', 'javadoc'),
       'org.springframework' : ('http://static.springsource.org/spring/docs/3.1.x/javadoc-api/', 'javadoc'),
       'org.springframework.data.redis' : ('http://static.springsource.org/spring-data/data-redis/docs/current/api/', 'javadoc')
   }

Each key in the map should be a Java package. Each value is a tuple of the form
``(base_url, doc_type)`` where ``base_url`` is the base URL of the documentation
source, and ``doc_type`` is one of,

``javadoc``
  For documentation generated by the Javadoc tool *before* version 8.

``javadoc8``
  For documentation generated by the Javadoc tool after version 8. This is
  required due to changes in how method anchors are generated (see JDK-8144118_).

``sphinx``
  For external documentation generated by javasphinx.

When comparing referenced types to the list of available packages the longest
match will be used. Entries for ``java``, ``javax``, ``org.xml``, and
``org.w3c`` packages pointing to http://docs.oracle.com/javase/8/docs/api are
included automatically and do not need to be defined explicitly.

.. _JDK-8144118: https://bugs.openjdk.java.net/browse/JDK-8144118

Java domain
===========

Directives
----------

The Java domain uses the name **java** and provides the following directives,

.. rst:directive:: .. java:type:: type-signature

   Describe a Java type. The signature can represent either a class, interface,
   enum or annotation declaration.

   Use the ``param`` field to document type parameters.

   Example,

   .. code-block:: rst

      .. java:type:: public interface List<E> extends Collection<E>, Iterable<E>

         An ordered collection (also known as a *sequence*)

         :param E: type of item stored by the list

   produces,

      .. java:type:: public interface List<E> extends Collection<E>, Iterable<E>

         An ordered collection (also known as a *sequence*)

         :param E: type of item stored by the list

.. rst:directive:: .. java:field:: field-signature

   Describe a Java field.

.. rst:directive:: .. java:method:: method-signature

   Describe a Java method.

   Use the ``param`` field to document parameters.

   Use the ``throws`` field to document exceptions thrown by the method.

   Use the ``return`` field to document the return type

.. rst:directive:: .. java:constructor:: constructor-signature

   Describe a Java constructor.

   Use the ``param`` field to document parameters.

   Use the ``throws`` field to document exceptions thrown by the constructor.

.. rst:directive:: .. java:package:: package

   Provide package-level documentation and also sets the active package for the
   type, method, field, constructors, and references that follow.

   Use the ``:noindex:`` option if the directive is only being used to specify
   the active package. Only one directive for a given package should exclude
   ``:noindex:``.

.. rst:directive:: .. java:import:: package type

   Declare the given type as being provided by the given package. This
   information helps javasphinx create cross references for types in type,
   method, and field declarations. It also allows explicit cross references
   (using the ``java:ref`` role) to exclude the package qualification.

The method, construct, field, and type directives all accept the following
standard options,

.. describe:: package

   Specify the package the declaration is within. Can be used instead of, or to
   override, a ``java:package`` directive.

.. describe:: outertype

   Specify the class/interface the documented object is contained within. This
   option should be provided for any constructor, method, or field directive
   that isn't nested within a corresponding type directive.

Roles
-----

The following roles are provided,

.. rst:role:: java:ref

   This role can be used to create a cross reference to any object type within
   the Java domain. Aliases for this role include ``java:meth``, ``java:type``,
   ``java:field``, ``java:package``, and ``java:construct``.

   An explicit title can be provided by using the standard ``title <reference>``
   syntax.

.. rst:role:: java:extdoc

   This role can be used to explicitly link to an externally documented
   type. The reference must be fully qualified and supports an explicit title
   using the ``title <reference>`` syntax.

   The ``java:ref`` role will also create external references as a fall-back if
   it can't find a matching local declaration so using this role is not strictly
   necessary.

javasphinx-apidoc
=================

The ``javasphinx-apidoc`` tool is the counterpoint to the ``sphinx-apidoc`` tool
within the Java domain. It can be used to generate reST source from existing
Java source code which has been marked up with Javadoc-style comments. The
generated reST is then processed alongside hand-written documentation by Sphinx.

At minimum a source and destination directory must be provided. The input
directory will be scanned for .java files and documentation will be generated
for all non-private types and members. A separate output file will be generated
for each type (including inner classes). Each file is put within a directory
corresponding to its package (with periods replaced by directory separators) and
with the basename of the file deriving from the type name. Inner types are
placed in files with a basename using a hyphen to separate inner and outer
types, e.g. ``OuterType-InnerType.rst``.

By default ``javasphinx-apidoc`` will not override existing files. Two options
can change this behavior,

.. option:: -f, --force

   All existing output files will be rewritten. If a cache directory is
   specified it will be rebuilt.

.. option:: -u, --update

   Updated source files will have their corresponding output files
   updated. Unchanged files will be left alone. Most projects will want to use
   this option.

For larger projects it is recommended to use a cache directory. This can speed
up subsequent runs by an order of magnitude or more. Specify a directory to
store cached output using the :option:`-c` option,

.. option:: -c, --cache-dir

   Specify a directory to cache intermediate documentation representations. This
   directory will be created if it does not already exist.
