--- /dev/null
+
+#######################
+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.
