docs/source/_ext/javasphinx/doc/index.rst

   1
   2 #######################
   3 javasphinx User's Guide
   4 #######################
   5
   6 Welcome to the javasphinx user's guide.
   7
   8 Introduction
   9 ============
  10
  11 javasphinx is a Sphinx_ extension that provides a Sphinx domain_ for documenting
  12 Java projects and a ``javasphinx-apidoc`` command line tool for automatically
  13 generating API documentation from existing Java source code and Javadoc
  14 documentation.
  15
  16 .. _Sphinx: http://sphinx-doc.org
  17 .. _domain: http://sphinx-doc.org/domains.html
  18
  19 Installing
  20 ==========
  21
  22 javasphinx is available in the Python Package Index (PyPi) and can be installed
  23 using tools such as ``pip`` or ``easy_install``,
  24
  25 .. code-block:: sh
  26
  27    $ pip install javasphinx
  28
  29 or,
  30
  31 .. code-block:: sh
  32
  33    $ easy_install -U javasphinx
  34
  35 Configuration
  36 =============
  37
  38 To enable javasphinx for your existing Sphinx configuration add ``'javasphinx'``
  39 to the list of extensions in your conf.py file. javasphinx can be configured to
  40 cross link to external sources of documentation using the ``javadoc_url_map``
  41 option,
  42
  43 .. code-block:: python
  44
  45    javadoc_url_map = {
  46        'com.netflix.curator' : ('http://netflix.github.com/curator/doc', 'javadoc'),
  47        'org.springframework' : ('http://static.springsource.org/spring/docs/3.1.x/javadoc-api/', 'javadoc'),
  48        'org.springframework.data.redis' : ('http://static.springsource.org/spring-data/data-redis/docs/current/api/', 'javadoc')
  49    }
  50
  51 Each key in the map should be a Java package. Each value is a tuple of the form
  52 ``(base_url, doc_type)`` where ``base_url`` is the base URL of the documentation
  53 source, and ``doc_type`` is one of,
  54
  55 ``javadoc``
  56   For documentation generated by the Javadoc tool *before* version 8.
  57
  58 ``javadoc8``
  59   For documentation generated by the Javadoc tool after version 8. This is
  60   required due to changes in how method anchors are generated (see JDK-8144118_).
  61
  62 ``sphinx``
  63   For external documentation generated by javasphinx.
  64
  65 When comparing referenced types to the list of available packages the longest
  66 match will be used. Entries for ``java``, ``javax``, ``org.xml``, and
  67 ``org.w3c`` packages pointing to http://docs.oracle.com/javase/8/docs/api are
  68 included automatically and do not need to be defined explicitly.
  69
  70 .. _JDK-8144118: https://bugs.openjdk.java.net/browse/JDK-8144118
  71
  72 Java domain
  73 ===========
  74
  75 Directives
  76 ----------
  77
  78 The Java domain uses the name **java** and provides the following directives,
  79
  80 .. rst:directive:: .. java:type:: type-signature
  81
  82    Describe a Java type. The signature can represent either a class, interface,
  83    enum or annotation declaration.
  84
  85    Use the ``param`` field to document type parameters.
  86
  87    Example,
  88
  89    .. code-block:: rst
  90
  91       .. java:type:: public interface List<E> extends Collection<E>, Iterable<E>
  92
  93          An ordered collection (also known as a *sequence*)
  94
  95          :param E: type of item stored by the list
  96
  97    produces,
  98
  99       .. java:type:: public interface List<E> extends Collection<E>, Iterable<E>
 100
 101          An ordered collection (also known as a *sequence*)
 102
 103          :param E: type of item stored by the list
 104
 105 .. rst:directive:: .. java:field:: field-signature
 106
 107    Describe a Java field.
 108
 109 .. rst:directive:: .. java:method:: method-signature
 110
 111    Describe a Java method.
 112
 113    Use the ``param`` field to document parameters.
 114
 115    Use the ``throws`` field to document exceptions thrown by the method.
 116
 117    Use the ``return`` field to document the return type
 118
 119 .. rst:directive:: .. java:constructor:: constructor-signature
 120
 121    Describe a Java constructor.
 122
 123    Use the ``param`` field to document parameters.
 124
 125    Use the ``throws`` field to document exceptions thrown by the constructor.
 126
 127 .. rst:directive:: .. java:package:: package
 128
 129    Provide package-level documentation and also sets the active package for the
 130    type, method, field, constructors, and references that follow.
 131
 132    Use the ``:noindex:`` option if the directive is only being used to specify
 133    the active package. Only one directive for a given package should exclude
 134    ``:noindex:``.
 135
 136 .. rst:directive:: .. java:import:: package type
 137
 138    Declare the given type as being provided by the given package. This
 139    information helps javasphinx create cross references for types in type,
 140    method, and field declarations. It also allows explicit cross references
 141    (using the ``java:ref`` role) to exclude the package qualification.
 142
 143 The method, construct, field, and type directives all accept the following
 144 standard options,
 145
 146 .. describe:: package
 147
 148    Specify the package the declaration is within. Can be used instead of, or to
 149    override, a ``java:package`` directive.
 150
 151 .. describe:: outertype
 152
 153    Specify the class/interface the documented object is contained within. This
 154    option should be provided for any constructor, method, or field directive
 155    that isn't nested within a corresponding type directive.
 156
 157 Roles
 158 -----
 159
 160 The following roles are provided,
 161
 162 .. rst:role:: java:ref
 163
 164    This role can be used to create a cross reference to any object type within
 165    the Java domain. Aliases for this role include ``java:meth``, ``java:type``,
 166    ``java:field``, ``java:package``, and ``java:construct``.
 167
 168    An explicit title can be provided by using the standard ``title <reference>``
 169    syntax.
 170
 171 .. rst:role:: java:extdoc
 172
 173    This role can be used to explicitly link to an externally documented
 174    type. The reference must be fully qualified and supports an explicit title
 175    using the ``title <reference>`` syntax.
 176
 177    The ``java:ref`` role will also create external references as a fall-back if
 178    it can't find a matching local declaration so using this role is not strictly
 179    necessary.
 180
 181 javasphinx-apidoc
 182 =================
 183
 184 The ``javasphinx-apidoc`` tool is the counterpoint to the ``sphinx-apidoc`` tool
 185 within the Java domain. It can be used to generate reST source from existing
 186 Java source code which has been marked up with Javadoc-style comments. The
 187 generated reST is then processed alongside hand-written documentation by Sphinx.
 188
 189 At minimum a source and destination directory must be provided. The input
 190 directory will be scanned for .java files and documentation will be generated
 191 for all non-private types and members. A separate output file will be generated
 192 for each type (including inner classes). Each file is put within a directory
 193 corresponding to its package (with periods replaced by directory separators) and
 194 with the basename of the file deriving from the type name. Inner types are
 195 placed in files with a basename using a hyphen to separate inner and outer
 196 types, e.g. ``OuterType-InnerType.rst``.
 197
 198 By default ``javasphinx-apidoc`` will not override existing files. Two options
 199 can change this behavior,
 200
 201 .. option:: -f, --force
 202
 203    All existing output files will be rewritten. If a cache directory is
 204    specified it will be rebuilt.
 205
 206 .. option:: -u, --update
 207
 208    Updated source files will have their corresponding output files
 209    updated. Unchanged files will be left alone. Most projects will want to use
 210    this option.
 211
 212 For larger projects it is recommended to use a cache directory. This can speed
 213 up subsequent runs by an order of magnitude or more. Specify a directory to
 214 store cached output using the :option:`-c` option,
 215
 216 .. option:: -c, --cache-dir
 217
 218    Specify a directory to cache intermediate documentation representations. This
 219    directory will be created if it does not already exist.