[Epydoc-commits] SF.net SVN: epydoc: [1546] trunk/epydoc/doc

[<dva...@us...>]

Revision: 1546
          http://svn.sourceforge.net/epydoc/?rev=1546&view=rev
Author:   dvarrazzo
Date:     2007-02-20 15:51:34 -0800 (Tue, 20 Feb 2007)

Log Message:
-----------
- Added reST and javadoc markups to documentation
- Confug file example updated

Modified Paths:
--------------
    trunk/epydoc/doc/manual-epytext.txt
    trunk/epydoc/doc/manual-reference.txt
    trunk/epydoc/doc/manual-usage.txt
    trunk/epydoc/doc/manual.txt

Added Paths:
-----------
    trunk/epydoc/doc/manual-othermarkup.txt

Modified: trunk/epydoc/doc/manual-epytext.txt
===================================================================
--- trunk/epydoc/doc/manual-epytext.txt	2007-02-20 19:34:01 UTC (rev 1545)
+++ trunk/epydoc/doc/manual-epytext.txt	2007-02-20 23:51:34 UTC (rev 1546)
@@ -51,10 +51,10 @@
 .. list-table::
    :header-rows: 1
 
-   * - Docstring Input
-     - Rendered Output
+   *  - Docstring Input
+      - Rendered Output
 
-   * - .. python::
+   *  - .. python::
 
             def example():
                 """
@@ -67,11 +67,11 @@
                 """
                 *[...]*
 
-     -  This is a paragraph. Paragraphs can span multiple lines,
+      - This is a paragraph. Paragraphs can span multiple lines,
         and contain *inline markup*.
 
         This is another paragraph. Paragraphs are separated from each
-        other by blank lines. 
+        other by blank lines.
 
 Lists
 '''''

Added: trunk/epydoc/doc/manual-othermarkup.txt
===================================================================
--- trunk/epydoc/doc/manual-othermarkup.txt	                        (rev 0)
+++ trunk/epydoc/doc/manual-othermarkup.txt	2007-02-20 23:51:34 UTC (rev 1546)
@@ -0,0 +1,419 @@
+Alternate Markup Languages
+==========================
+
+.. $Id$
+
+Epydoc's default markup language is epytext_, a lightweight markup language
+that's easy to write and to understand. But if epytext is not powerful enough
+for you, or doesn't suit your needs, epydoc also supports three alternate
+markup languages:
+
+reStructuredText__
+    is an "easy-to-read, what-you-see-is-what-you-get plaintext markup syntax".
+    It is more powerful than epytext (e.g., it includes markup for tables and
+    footnotes); but it is also more complex, and sometimes harder to read.
+
+    .. __: http://docutils.sourceforge.net/rst.html
+
+Javadoc__
+    is a documentation markup language that was developed for Java. It consists
+    of HTML, augmented by a set of special tagged fields.
+
+    .. __: http://java.sun.com/j2se/javadoc/
+
+Plaintext docstrings
+    are rendered verbatim (preserving whitespace).
+
+To specify the markup language for a module, you should define a module-level
+string variable ``__docformat__``, containing the name of the module's markup
+language. The name of the markup language may optionally be followed by a
+language code (such as ``en`` for English). Conventionally, the definition of
+the ``__docformat__`` variable immediately follows the module's docstring:
+
+.. python::
+
+    # widget.py
+    """
+    Graphical support for `gizmos` and `widgets`.
+    """
+    __docformat__ = "restructuredtext en"
+    #[...]
+
+To change the default markup language from the command line, use the
+``--docformat`` option. For example, the following command generates API
+documentation for the existing regular expression package ``re``, which uses
+plaintext markup::
+
+    [epydoc]$ epydoc --docformat plaintext re
+
+
+reStructuredText
+----------------
+
+reStructuredText is a markup language that was developed in conjunction with
+Docutils_. In order to parse reStructuredText docstrings, Docutils 0.3 or
+higher must be installed. If Docutils is not installed, then reStructuredText
+docstrings will be rendered as plaintext. Docutils can be downloaded from the
+`Docutils SourceForge page`_.
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _Docutils SourceForge page:
+    http://sourceforge.net/project/showfiles.php?group_id=38414
+
+
+Default role
+''''''''''''
+
+Epydoc replaces the Docutils' default `interpreted text role`_ with
+the creation of  `documentation crossreference links`_. If you want to create
+a crossreference link to the ``somemod.Example`` class, you can put backquotes
+around your test, typing::
+
+    `somemod.Example`
+
+.. _interpreted text role:  http://docutils.sourceforge.net/
+                            docs/ref/rst/roles.html
+
+
+Consolidated Fields
+'''''''''''''''''''
+
+In addition to the `standard set of fields`_, the reStructruedText parser also
+supports *consolidated fields*, which combine the documentation for several
+objects into a single field. For example, a single ``:Parameters:`` field is
+often used to describe all of the parameters for a function or method:
+
+.. python::
+
+    def fox_speed(size, weight, age):
+        """
+        Return the maximum speed for a fox.
+
+        :Parameters:
+        - `size`: The size of the fox (in meters)
+        - `weight`: The weight of the fox (in stones)
+        - `age`: The age of the fox (in years)
+        """
+        #[...]
+
+.. _standard set of fields: `Epydoc fields`_
+
+Epydoc will automatically extract information about each parameter from this
+list. These *consolidated fields* may be written using either a `bulleted
+list`_ or a `definition list`_.
+
+* If a consolidated field is written as a *bulleted list*, then each list item
+  must begin with the field's argument, marked as `interpreted text`_, and
+  followed by a colon or dash.
+* If a consolidated field is written as a *definition list*, then each
+  definition item's term should contain the field's argument, (it is not
+  mandatory for it being marked as interpreted text).
+
+.. _bulleted list:      http://docutils.sourceforge.net/
+                        docs/user/rst/quickref.html#bullet-lists
+.. _definition list:    http://docutils.sourceforge.net/
+                        docs/user/rst/quickref.html#definition-lists
+.. _interpreted text:   http://docutils.sourceforge.net/
+                        docs/user/rst/quickref.html#inline-markup
+
+The term classifier, if present, is used to specify the associated type. The
+following example shows the use of a definition list to define a consolidated
+field (note that docutils requires a space before and after the '``:``' used
+to mark classifiers).
+
+.. python::
+
+    def fox_speed(size, weight, age):
+        """
+        Return the maximum speed for a fox.
+
+        :Parameters:
+          size
+            The size of the fox (in meters)
+          weight : float
+            The weight of the fox (in stones)
+          age : int
+            The age of the fox (in years)
+        """
+        #[...]
+
+The following consolidated fields are currently supported by epydoc:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Consolidated Field Tag
+     - Corresponding Base Field Tag
+   * - ``:Parameters:``
+     - ``:param:``
+   * - ``:Exception:``
+     - ``:except:``
+   * - ``:Groups:``
+     - ``:group:``
+   * - ``:Keywords:``
+     - ``:keyword:``
+   * - ``:Variables:``
+     - ``:var:``
+   * - ``:IVariables:``
+     - ``:ivar:``
+   * - ``:CVariables:``
+     - ``:cvar:``
+   * - ``:Types:``
+     - ``:type:``
+
+
+Graph directives
+''''''''''''''''
+
+The epydoc reStructuredText reader defines several custom `directives`, which
+can be used to automatically generate a variety of graphs. The following custom
+directives are currently defined:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   *  - Directive
+      - Description
+
+   *  - .. parsed-literal::
+
+             .. classtree:: [*classes...*]
+                 :dir: *up|down|left|right*
+
+      - Display a class hierarchy for the given class or classes (including all
+        superclasses & subclasses). If no class is specified, and the directive
+        is used in a class's docstring, then that class's class hierarchy will
+        be displayed. The ``dir`` option specifies the orientation for the graph
+        (default=\ ``down``).
+
+   *  - .. parsed-literal::
+
+             .. packagetree:: [*modules...*]
+                 :dir: *up|down|left|right*
+                 :style: *uml|tree*
+
+      - Display a package hierarchy for the given module or modules (including
+        all subpackages and submodules). If no module is specified, and the
+        directive is used in a module's docstring, then that module's package
+        hierarchy will be displayed. The ``dir`` option specifies the
+        orientation for the graph (default=\ ``down``). The ``style`` option
+        specifies whether packages should be displayed in a tree, or using
+        nested UML symbols.
+
+   *  - .. parsed-literal::
+
+            .. importgraph:: [*modules...*]
+                :dir: *up|down|left|right*
+
+      - Display an import graph for the given module or modules. If no module
+        is specified, and the directive is used in a module's docstring, then
+        that module's import graph will be displayed. The ``dir`` option
+        specifies the orientation for the graph (default=\ ``left``).
+
+   *  - .. parsed-literal::
+
+            .. callgraph:: [*functions...*]
+                :dir: *up|down|left|right*
+
+      - Display a call graph for the given function or functions. If no
+        function is specified, and the directive is used in a function's
+        docstring, then that function's call graph will be displayed. The
+        ``dir`` option specifies the orientation for the graph (default=\
+        ``right``).
+
+   *  - .. parsed-literal::
+
+            .. dotgraph:: [*title...*]
+                :caption: *text...*
+                *graph...*
+
+      - Display a custom Graphviz dot graph. The body of the directive
+        (``graph...``) should contain the body of a dot graph. The optional
+        ``title`` argument, if specified, is used as the title of the graph.
+        The optional ``caption`` option can be used to provide a caption for
+        the graph.
+
+
+Colorized snippets directive
+''''''''''''''''''''''''''''
+
+Using reStructuredText markup it is possible to specify Python snippets in a
+`doctest block`__. SUch block will be colorized as in epytext `Doctest Blocks`_.
+
+.. __:      http://docutils.sourceforge.net/
+            docs/user/rst/quickref.html#bullet-lists
+
+>>> def double(x):
+...     return x * 2
+...
+>>> print double(8)
+16
+
+Doctest block are mostly useful to be run as a part of automatized test suite
+using the doctest_ module. If the Python prompt gets in your way when you try
+to copy and paste and you are not interested in self-testing docstrings, the
+``python`` directive will let you obtain a simple block of colorized text:
+
+.. _doctest: http://docs.python.org/lib/module-doctest.html
+
+.. list-table::
+   :header-rows: 1
+
+   * -  Docstring Input
+     -  Rendered Output
+
+   * -  ::
+
+            .. python::
+
+                def fib(n):
+                    """Print a Fibonacci series."""
+                    a, b = 0, 1
+                    while b < n:
+                        print b,
+                        a, b = b, a+b
+
+     -  .. python::
+
+            def fib(n):
+                """Print a Fibonacci series."""
+                a, b = 0, 1
+                while b < n:
+                    print b,
+                    a, b = b, a+b
+
+
+External API links
+''''''''''''''''''
+
+Epydoc can be used to create hyperlinks from your package documentation towards
+objects defined in the API of other packages. Such links are similar to
+ordinary `documentation crossreference links`_, but it is required to configure
+Epydoc setting up a new `interpreted text role`_, binding it to an external API.
+
+To create a new role, the command line option ``--external-api=``\ *NAME* must
+be used. This option introduces a new interpreted text role called ``NAME``,
+which can be used to refer to objects defined in an external API.
+
+You can alternatively use a configuration file for this and all the other
+options: see the `sample configuration file`_ for a comprehensive example.
+
+For example, if your program needs to programmatically use the Epydoc package
+itself, your docstrings may refer to functions described by Epydoc API::
+
+    If you want to print a value, you can use
+    the :epydoc:`apidoc.pp_apidoc()` function.
+
+When you will generate the API documentation for such program, you will
+need the option ``--external-api=epydoc`` or you will get parsing errors due
+to the unknown role.
+
+Of course this doesn't help to really create cross references: the
+``--external-api`` option suffices to stop Epydoc complaining about unknown
+roles, but the text is simply rendered in a monotype font and no link is
+created.
+
+What Epydoc requires to create external API links is a mapping from the names
+of the objects exposed by the API and the URL where such objects are actually
+described. Such mapping must be provided as a text file, with an object name
+and its URL on each line, separated by a ``tab`` character. For example the
+Epydoc API documentation may be represented by a file names ``api-objects.txt``
+containing::
+
+    epydoc                          ->  epydoc-module.html
+    epydoc.apidoc                   ->  epydoc.apidoc-module.html
+    epydoc.apidoc.UNKNOWN           ->  epydoc.apidoc-module.html#UNKNOWN
+    epydoc.apidoc._pp_val           ->  epydoc.apidoc-module.html#_pp_val
+    epydoc.apidoc.py_src_filename   ->  epydoc.util-module.html#py_src_filename
+    epydoc.apidoc.pp_apidoc         ->  epydoc.apidoc-module.html#pp_apidoc
+    epydoc.apidoc._pp_list          ->  epydoc.apidoc-module.html#_pp_list
+    ...                                 ...
+    ...                                 ...
+
+Epydoc's HTML writer indeed includes such file in its output: see `HTML
+Files`_ for details.
+
+You can bind the definition file to the interpreted text role name using
+the command line option ``--external-api-file=``\ *NAME:FILENAME*.In the
+previous example you can use::
+
+    --external-api-file=epydoc:api-objects.txt
+
+This helps Epydoc to create relative urls: in the previous example the
+``apidoc.pp_apidoc()`` label will be linked with the
+``epydoc.apidoc-module.html#_pp_val`` URL.
+
+You can specify a new root for the generated links using the last command line
+option: ``--external-api-root=``\ *NAME:STRING*. *STRING* will be attached
+in front of any URL returned by the *NAME* text role. For example, to let your
+program refer to Epydoc API whose documentation is published at
+http://epydoc.sourceforge.net/api/ you can use the options::
+
+    --external-api-root=epydoc:http://epydoc.sourceforge.net/api/
+
+this will let your reference :epydoc:`apidoc.pp_apidoc()` point at the
+right documentation.
+
+The three options can be used any number of time, effectively allowing to link
+towards all the required external packages.
+
+
+Names resolution
+~~~~~~~~~~~~~~~~
+
+When an external API link is to be created, the required name is split along
+any separator ('``.``', '``::``', '``->``'). Everything after the first noise
+character (for example after an '``(``') is discarded.
+
+The name fragment is looked for in the names defined in the description file:
+first an exact match is attempted; if no name exactly matches the required
+name, a partial match is attempted: the required name is compared with the
+*trailing parts* of the names in the file.
+
+If a single name is found in this lookup, then its URL is returned. If the
+name is not found, or if it matches with the trailing part of many defined
+names, a warning is raised and the name is rendered as literal text.
+
+
+Linking from standalone documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Epydoc provides the script ``apirst2html.py`` which allows to use the
+previously described interpreted text roles from any reST document. The script
+exposes the same interface of the standard Docutils script ``rst2html.py`` but
+provides the extra command line options described in `External API links`_.
+
+With such tool you will be able to create hypertextual documentation of your
+package with direct links to its API.
+
+
+Javadoc
+-------
+
+Javadoc_ is a markup language developed by Sun Microsystems for documenting
+Java APIs. The epydoc implementation of Javadoc is based on the `Javadoc 1.4.2
+reference documentation`__. However, there are likely to be some minor incompatibilities between Sun's implementation and epydoc's. Known incompatibilities include:
+
+* Epydoc does not support the Javadoc block tag ``@serial``.
+* Epydoc does not support the following Javadoc inline tags: ``{@docroot}``,
+  ``{@inheritdoc}``, ``{@value}``.
+* Epydoc adds many field tags that Sun does not include, such as ``@var``,
+  ``@type``, and ``@group``.
+
+.. __: http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html
+
+
+Javadoc Fields
+''''''''''''''
+
+For compatibility with Javadoc, every ``@see`` field is assumed to contain a
+single crossreference link, unless its body is quoted, or it starts with an
+HTML tag. See the `Javadoc reference manual`__ for more information about how the
+``@see`` field is encoded in Javadoc.
+
+.. __: http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html#@see
+
+Because Javadoc does not mark end of the optional argument, field arguments
+must contain exactly one word. Thus, multi-word arguments are not available
+in Javadoc. In particular, all group names must be single words.


Property changes on: trunk/epydoc/doc/manual-othermarkup.txt
___________________________________________________________________
Name: svn:keywords
   + Id
Name: svn:eol-style
   + native

Modified: trunk/epydoc/doc/manual-reference.txt
===================================================================
--- trunk/epydoc/doc/manual-reference.txt	2007-02-20 19:34:01 UTC (rev 1545)
+++ trunk/epydoc/doc/manual-reference.txt	2007-02-20 23:51:34 UTC (rev 1546)
@@ -156,17 +156,73 @@
     *# The path to the output directory.  May be relative or absolute.*
     **target: html/**
 
+    *# An integer indicating how verbose epydoc should be.  The default*
+    *# value is 0; negative values will supress warnings and errors;*
+    *# positive values will give more verbose output.*
+    **verbosity: 0**
+
+    *# A boolean value indicating that Epydoc should show a tracaback*
+    *# in case of unexpected error. By default don't show tracebacks*
+    **debug: 0**
+
+    *# If True, don't try to use colors or cursor control when doing*
+    *# textual output. The default False assumes a rich text prompt*
+    **simple-term: 0**
+
+
+    **### Generation options**
+
     *# The default markup language for docstrings, for modules that do*
     *# not define __docformat__.  Defaults to epytext.*
     **docformat: epytext**
 
+    *# Whether or not parsing should be used to examine objects.*
+    **parse: yes**
+
+    *# Whether or not introspection should be used to examine objects.*
+    **introspect: yes**
+
+    *# Don't examine in any way the modules whose dotted name match this*
+    *# regular expression pattern.*
+    **#exclude**
+
+    *# Don't perform introspection on the modules whose dotted name match this*
+    *# regular expression pattern.*
+    **#exclude-introspect**
+
+    *# Don't perform parsing on the modules whose dotted name match this*
+    *# regular expression pattern.*
+    **#exclude-parse**
+
+    *# The format for showing inheritance objects.*
+    *# It should be one of: 'grouped', 'listed', 'included'.*
+    **inheritance: listed**
+
+    *# Whether or not to inclue private variables.  (Even if included,*
+    *# private variables will be hidden by default.)*
+    **private: yes**
+
+    *# Whether or not to list each module's imports.*
+    **imports: no**
+
+    *# Whether or not to include syntax highlighted source code in*
+    *# the output (HTML only).*
+    **sourcecode: yes**
+
+    *# Whether or not to includea a page with Epydoc log, containing*
+    *# effective option at the time of generation and the reported logs.*
+    **include-log: no**
+
+
+    **### Output options**
+
+    *# The documented project's name.*
+    **name: Example**
+
     *# The CSS stylesheet for HTML output.  Can be the name of a builtin*
     *# stylesheet, or the name of a file.*
     **css: white**
 
-    *# The documented project's name.*
-    **name: Example**
-
     *# The documented project's URL.*
     **url: http://some.project/**
 
@@ -187,24 +243,26 @@
     *# Whether or not to include a frames-based table of contents.*
     **frames: yes**
 
-    *# Whether or not to inclue private variables.  (Even if included,*
-    *# private variables will be hidden by default.)*
-    **private: yes**
+    *# Whether each class should be listed in its own section when*
+    *# generating LaTeX or PDF output.*
+    **separate-classes: no**
 
-    *# Whether or not to list each module's imports.*
-    **imports: no**
 
-    *# An integer indicating how verbose epydoc should be.  The default*
-    *# value is 0; negative values will supress warnings and errors;*
-    *# positive values will give more verbose output.*
-    **verbosity: 0**
+    **### API linking options**
 
-    *# Whether or not parsing should be used to examine objects.*
-    **parse: yes**
+    *# Define a new API document.  A new interpreted text role*
+    *# will be created*
+    **#external-api: epydoc**
 
-    *# Whether or not introspection should be used to examine objects.*
-    **introspect: yes**
+    *# Use the records in this file to resolve objects in the API named NAME.*
+    **#external-api-file: epydoc:api-objects.txt**
 
+    *# Use this URL prefix to configure the string returned for external API.*
+    **#external-api-root: epydoc:http://epydoc.sourceforge.net/api**
+
+
+    **### Graph options**
+
     *# The list of graph types that should be automatically included*
     *# in the output.  Graphs are generated using the Graphviz "dot"*
     *# executable.  Graph types include: "classtree", "callgraph",*
@@ -215,19 +273,35 @@
     *# graphs.*
     **dotpath: /usr/local/bin/dot**
 
-    *# Whether or not to include syntax highlighted source code in*
-    *# the output (HTML only).*
-    **sourcecode: yes**
-
     *# The name of one or more pstat files (generated by the profile*
     *# or hotshot module).  These are used to generate call graphs.*
     **pstat: profile.out**
 
-    *# Whether each class should be listed in its own section when*
-    *# generating LaTeX or PDF output.*
-    **separate-classes: no**
+    *# Specify the font used to generate Graphviz graphs.*
+    *# (e.g., helvetica or times).*
+    **graph-font: Helvetica**
 
+    *# Specify the font size used to generate Graphviz*
+    **graph-font-size: 10**
 
+
+    **### Return value options**
+
+    *# If true, return a non-zero exit status, indicating failure,*
+    *# if any errors are encountered.*
+    **fail-on-error: false**
+
+    *# If true, return a non-zero exit status, indicating failure,*
+    *# if any errors or warnings are encountered (not including*
+    *# docstring warnings).*
+    **fail-on-warning: false**
+    
+    *# Return a non-zero exit status, indicating failure, if any*
+    *# errors or warnings are encountered (including docstring*
+    *# warnings).*
+    **fail-on-docstring-warning: false**
+
+
 Warnings and Errors
 -------------------
 

Modified: trunk/epydoc/doc/manual-usage.txt
===================================================================
--- trunk/epydoc/doc/manual-usage.txt	2007-02-20 19:34:01 UTC (rev 1545)
+++ trunk/epydoc/doc/manual-usage.txt	2007-02-20 23:51:34 UTC (rev 1546)
@@ -270,8 +270,8 @@
     ``array.ArrayType``.
 
 *module*\ ``-pysrc.html``
-    A page with the module colourized source code, with links back to the
-    objects main documentation pages. The creation of the colourized source
+    A page with the module colorized source code, with links back to the
+    objects main documentation pages. The creation of the colorized source
     pages can be controlled using the options_ ``--show-sourcecode`` and
     ``--no-sourcecode``.
 
@@ -311,8 +311,7 @@
 ``api-objects.txt``
     A text file containing each available item and the URL where it is
     documented. Each item takes a file line and it is separated by the URL by
-    a ``tab`` charecter. Such file can be used to create documents linkig to
-    the API: see the ``--external-api`` documentation for details.
+    a ``tab`` charecter. Such file can be used to create `external API links`_.
 
 ``redirect.html``
     A page containing Javascript code that redirect the browser to the

Modified: trunk/epydoc/doc/manual.txt
===================================================================
--- trunk/epydoc/doc/manual.txt	2007-02-20 19:34:01 UTC (rev 1545)
+++ trunk/epydoc/doc/manual.txt	2007-02-20 23:51:34 UTC (rev 1546)
@@ -42,5 +42,6 @@
 .. include:: manual-usage.txt
 .. include:: manual-epytext.txt
 .. include:: manual-fields.txt
+.. include:: manual-othermarkup.txt
 .. include:: manual-docstring.txt
 .. include:: manual-reference.txt


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.