epydoc-commits Mailing List for Python API documentation generation tool (Page 12)
Brought to you by:
edloper
Menu
▾
▴
epydoc-commits — CVS commit logs for the epydoc project
You can subscribe to this list here.
| 2006 |
Jan
|
Feb
|
Mar
|
Apr
(77) |
May
|
Jun
(6) |
Jul
(8) |
Aug
(91) |
Sep
(67) |
Oct
(4) |
Nov
|
Dec
(1) |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2007 |
Jan
(17) |
Feb
(135) |
Mar
(25) |
Apr
|
May
(1) |
Jun
(1) |
Jul
(7) |
Aug
|
Sep
(62) |
Oct
(1) |
Nov
(3) |
Dec
|
| 2008 |
Jan
(40) |
Feb
(102) |
Mar
(5) |
Apr
|
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
| 2009 |
Jan
|
Feb
(2) |
Mar
|
Apr
|
May
|
Jun
|
Jul
|
Aug
|
Sep
|
Oct
|
Nov
|
Dec
|
|
From: <dva...@us...> - 2007-02-20 01:38:40
|
Revision: 1537
http://svn.sourceforge.net/epydoc/?rev=1537&view=rev
Author: dvarrazzo
Date: 2007-02-19 17:38:37 -0800 (Mon, 19 Feb 2007)
Log Message:
-----------
- Generated HTML pages description updated.
Modified Paths:
--------------
trunk/epydoc/doc/using.html
Modified: trunk/epydoc/doc/using.html
===================================================================
--- trunk/epydoc/doc/using.html 2007-02-19 22:59:58 UTC (rev 1536)
+++ trunk/epydoc/doc/using.html 2007-02-20 01:38:37 UTC (rev 1537)
@@ -23,7 +23,7 @@
<p>Epydoc can also be accessed programmatically; see epydoc's <a
href="api/">API documentation</a> for more information. </p>
-<a name="cli"><h2> The Command Line Interface </h2></a>
+<a name="cli"></a><h2> The Command Line Interface </h2>
<p> The <code>epydoc</code> script extracts API documentation for a
set of python objects, and writes it using a selected output format.
@@ -324,9 +324,8 @@
<a name="files"><h2> HTML Files </h2></a>
-<p> Epydoc creates two subdirectories, for the public and private
- documentation. Within each subdirectory, every module and class
- is documented in its own file. An index file, a trees file, a
+<p> Every Python module and class
+ is documented in its own file. Index files, tree files, a
help file, and a frames-based table of contents are also created.
The following list describes each of the files generated by
epydoc: </p>
@@ -350,16 +349,58 @@
complete dotted name of the class, such as epydoc.epytext.Token or
array.ArrayType. </li>
- <li><b><code>trees.html</code></b>
- The module and class hierarchies. </li>
+ <li><b><code><code class="user">module</code>-pysrc.html</code></b>
+ A page with the module colourized source code, with links back to the
+ objects main documentation pages. The creation of the colourized source
+ pages can be controlled using the options <code>--show-sourcecode</code> and
+ <code>--no-sourcecode</code>.</li>
- <li><b><code>indices.html</code></b>
- The term and identifier indices. </li>
+ <li><b><code>module-tree.html</code></b>
+ The documented module hierarchy. </li>
+ <li><b><code>class-tree.html</code></b>
+ The documented classes hierarchy. </li>
+
+ <li><b><code>identifier-index.html</code></b>
+ The index of all the identifiers found in the documented items. </li>
+
+ <li><b><code>term-index.html</code></b>
+ The index of all the term definition found in the docstrings.
+ Term definitions are created using the <a href="epytext.html#indexed">Indexed
+ Term</a> markup. </li>
+
+ <li><b><code>bug-index.html</code></b>
+ The index of all the known bug in the documented sources.
+ Bugs are marked using the <code>@bug</code> tag. </li>
+
+ <li><b><code>todo-index.html</code></b>
+ The index of all the <i>to-do</i> items in the documented sources.
+ They are marked using the <code>@todo</code> tag. </li>
+
<li><b><code>help.html</code></b>
The help page for the project. This page explains how to use and
navigate the webpage produced by epydoc. </li>
+ <li><b><code>epydoc-log.html</code></b>
+ A page with the log of the epydoc execution. It is available clicking on the
+ timestamp below each page, if the documentation was created using the
+ <code>--include-log</code> option. The page also contains the list of the
+ options enabled when the documentation was created. </li>
+
+ <li><b><code>api-objects.txt</code></b>
+ 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 <code>tab</code> charecter. Such file can be used to create documents
+ linkig to the API: see the <code>--external-api</code> documentation for
+ details.</li>
+
+ <li><b><code>redirect.html</code></b>
+ A page containing Javascript code that redirect the browser to the
+ documetation page indicated by the accessed fragment. For example opening
+ the page <code>redirect.html#epydoc.apidoc.DottedName</code> the browser
+ will be redirected to the page
+ <code>/epydoc.apidoc.DottedName-class.html</code>.</li>
+
<li><b><code>frames.html</code></b>
The main frames file. Two frames on the left side of the window
contain a table of contents, and the main frame on the right side of
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-19 23:00:03
|
Revision: 1536
http://svn.sourceforge.net/epydoc/?rev=1536&view=rev
Author: dvarrazzo
Date: 2007-02-19 14:59:58 -0800 (Mon, 19 Feb 2007)
Log Message:
-----------
- Fixed docstrings so they correctly link to the Epydoc API.
Currently it is required to use `register_canonical_role()` instead of
`register_local_role()` in `xlink.create_api_role()`
Modified Paths:
--------------
trunk/epydoc/src/epydoc/test/apidoc.doctest
trunk/epydoc/src/epydoc/test/docbuilder.doctest
trunk/epydoc/src/epydoc/test/docintrospecter.doctest
trunk/epydoc/src/epydoc/test/docparser.doctest
trunk/epydoc/src/epydoc/test/pyval_repr.doctest
trunk/epydoc/src/epydoc/test/zope2.doctest
trunk/epydoc/src/epydoc/test/zope3.doctest
Modified: trunk/epydoc/src/epydoc/test/apidoc.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/apidoc.doctest 2007-02-19 22:55:22 UTC (rev 1535)
+++ trunk/epydoc/src/epydoc/test/apidoc.doctest 2007-02-19 22:59:58 UTC (rev 1536)
@@ -2,7 +2,7 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This file serves to provide both documentation and regression tests
for the epydoc.apidoc module. The main purpose of this module is to
-define the `APIDoc` class hierarchy, which is used to encode API
+define the :epydoc:`APIDoc` class hierarchy, which is used to encode API
documentation about Python programs. The API documentation for a
Python program is encoded using a graph of `APIDoc` objects, each of
which encodes information about a single Python variable or value.
Modified: trunk/epydoc/src/epydoc/test/docbuilder.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/docbuilder.doctest 2007-02-19 22:55:22 UTC (rev 1535)
+++ trunk/epydoc/src/epydoc/test/docbuilder.doctest 2007-02-19 22:59:58 UTC (rev 1536)
@@ -338,9 +338,9 @@
===================
When we do both parsing & introspection, and merge the result, we
should trust the introspected APIDoc's is_imported value more than the
-parsed APIDoc. In particular, in the following example, `x` should
+parsed APIDoc. In particular, in the following example, ``x`` should
have `is_imported=True`. But if we can't tell from introspection,
-then use parse info -- so `y` should be imported, but `z` should not.
+then use parse info -- so ``y`` should be imported, but ``z`` should not.
>>> import epydoc.docintrospecter
>>> epydoc.docintrospecter.clear_cache()
Modified: trunk/epydoc/src/epydoc/test/docintrospecter.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/docintrospecter.doctest 2007-02-19 22:55:22 UTC (rev 1535)
+++ trunk/epydoc/src/epydoc/test/docintrospecter.doctest 2007-02-19 22:59:58 UTC (rev 1536)
@@ -2,16 +2,16 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `epydoc.docintrospecter` module is used to extract API documentation
by introspecting Python objects directy. Its primary interface is
-`introspect_docs()`, which takes a Python object, and returns a
+`docintrospecter.introspect_docs()`, which takes a Python object, and returns a
`ValueDoc` describing that value.
Test Function
=============
This test function takes a string containing the contents of a module.
It writes the string contents to a file, imports the file as a module,
-and uses `introspect_docs` to introspect it, and pretty prints the resulting
-ModuleDoc object. The `attribs` argument specifies which attributes
-of the `APIDoc`s should be displayed. The `introspect` argument gives the
+and uses `docintrospecter.introspect_docs` to introspect it, and pretty prints the resulting
+`ModuleDoc` object. The ``attribs`` argument specifies which attributes
+of the `APIDoc`s should be displayed. The ``introspect`` argument gives the
name of a variable in the module whose value should be introspected,
instead of introspecting the whole module.
@@ -43,7 +43,7 @@
+- x => VariableDoc for epydoc_test.x [5]
+- y => VariableDoc for epydoc_test.y [6]
-If two variables share the same value, then their `VariableDoc`s will
+If two variables share the same value, then their `VariableDoc`\ s will
share a `ValueDoc`:
>>> runintrospecter(s="""
@@ -143,8 +143,8 @@
Variable Docstrings
===================
-The DocIntrospecter is unable extract docstrings for variables. These
-docstrings can only be detected if the DocParser is used.
+The `docintrospecter` is unable extract docstrings for variables. These
+docstrings can only be detected if the `docparser` is used.
>>> runintrospecter(s="""
... x = 12
@@ -188,12 +188,12 @@
+- pyval = <function f at ...>
+- vararg = None
-The function's arguments are described by the properties `posargs`,
-`posarg_defaults`, `kwarg`, and `vararg`. `posargs` is a list of
+The function's arguments are described by the properties ``posargs``,
+``posarg_defaults``, ``kwarg``, and ``vararg``. ``posargs`` is a list of
argument names (or nested tuples of names, for tuple-unpacking args).
-`posarg_defaults` is a list of `ValueDoc`s for default values,
-corresponding 1:1 with `posargs`. `posarg_defaults` is None for
-arguments with no default value. `vararg` and `kwarg` are the names
+``posarg_defaults`` is a list of `ValueDoc`\ s for default values,
+corresponding 1:1 with ``posargs``. ``posarg_defaults`` is None for
+arguments with no default value. ``vararg`` and ``kwarg`` are the names
of the variable argument and keyword argument, respectively:
>>> runintrospecter(s="""
@@ -388,7 +388,7 @@
+- value
+- GenericValueDoc [2]
-The right-hand side of a `del` statement may contain a nested
+The right-hand side of a ``del`` statement may contain a nested
combination of lists, tuples, and parenthases. All variables found
anywhere in this nested structure should be deleted:
@@ -424,7 +424,7 @@
+- variables
+- g => VariableDoc for epydoc_test.g [1]
-The right-hand side of a `del` statement may contain a dotted name, in
+The right-hand side of a ``del`` statement may contain a dotted name, in
which case the named variable should be deleted from its containing
namespace.
@@ -595,10 +595,10 @@
SF Bug [ 1657050 ] Builtins not resolved in "os"
------------------------------------------------
-If a variable is listed in __all__, then we need to introspect it,
+If a variable is listed in ``__all__``, then we need to introspect it,
even if we know for certain that it's imported. Before this bug
-was fixed, the following test generated a generic 'ValueDoc' value
-instead of a 'RoutineDoc' value, because it didn't introspect the
+was fixed, the following test generated a generic `ValueDoc` value
+instead of a `RoutineDoc` value, because it didn't introspect the
value of getcwd.
>>> x = runintrospecter(s="""
Modified: trunk/epydoc/src/epydoc/test/docparser.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/docparser.doctest 2007-02-19 22:55:22 UTC (rev 1535)
+++ trunk/epydoc/src/epydoc/test/docparser.doctest 2007-02-19 22:59:58 UTC (rev 1536)
@@ -2,16 +2,16 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The `epydoc.docparser` module is used to extract API documentation by
parsing the source code of Python files. Its primary interface is
-`parse_docs()`, which takes a module's filename, and returns a
+`docparser.parse_docs()`, which takes a module's filename, and returns a
ModuleDoc describing that module and its contents.
Test Function
=============
This test function takes a string containing the contents of a module,
-and writes it to a file, uses `parse_docs` to parse it, and pretty
-prints the resulting ModuleDoc object. The `attribs` argument
+and writes it to a file, uses `docparser.parse_docs()` to parse it, and pretty
+prints the resulting ModuleDoc object. The ``attribs`` argument
specifies which attributes of the `APIDoc`s should be displayed. The
-`show` argument, if specifies, gives the name of the object in the
+``show`` argument, if specifies, gives the name of the object in the
module that should be displayed (but the whole module will always be
inspected; this just selects what to display).
@@ -27,7 +27,7 @@
loops, while loops, and try/except/finally blocks. Tuple assignments
are unpacked, when possible.
-For simple variable assignments, DocParser creates VariableDoc objects
+For simple variable assignments, DocParser creates `VariableDoc` objects
containing the name; a valuedoc with the value (as both an abstract
syntax tree and a string representation); and information about
whether we think the value was imported; is an alias; and is an
@@ -424,12 +424,12 @@
+- posargs = [u'x']
+- vararg = None
-The function's arguments are described by the properties `posargs`,
-`posarg_defaults`, `kwarg`, and `vararg`. `posargs` is a list of
+The function's arguments are described by the properties ``posargs``,
+``posarg_defaults``, ``kwarg``, and ``vararg``. ``posargs`` is a list of
argument names (or nested tuples of names, for tuple-unpacking args).
-`posarg_defaults` is a list of `ValueDoc`s for default values,
-corresponding 1:1 with `posargs`. `posarg_defaults` is None for
-arguments with no default value. `vararg` and `kwarg` are the names
+``posarg_defaults`` is a list of `ValueDoc`\ s for default values,
+corresponding 1:1 with ``posargs``. ``posarg_defaults`` is None for
+arguments with no default value. ``vararg`` and ``kwarg`` are the names
of the variable argument and keyword argument, respectively:
>>> runparser(s="""
@@ -587,7 +587,7 @@
+- GenericValueDoc [2]
+- parse_repr = u'12'
-The right-hand side of a `del` statement may contain a nested
+The right-hand side of a ``del`` statement may contain a nested
combination of lists, tuples, and parenthases. All variables found
anywhere in this nested structure should be deleted:
@@ -623,7 +623,7 @@
+- variables
+- g => VariableDoc for epydoc_test.g [1]
-The right-hand side of a `del` statement may contain a dotted name, in
+The right-hand side of a ``del`` statement may contain a dotted name, in
which case the named variable should be deleted from its containing
namespace.
Modified: trunk/epydoc/src/epydoc/test/pyval_repr.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/pyval_repr.doctest 2007-02-19 22:55:22 UTC (rev 1535)
+++ trunk/epydoc/src/epydoc/test/pyval_repr.doctest 2007-02-19 22:59:58 UTC (rev 1536)
@@ -206,7 +206,7 @@
Line Wrapping
=============
If a line goes beyond linelen, it is wrapped using ``↵`` (which
-gets translated to ``\\`` by `to_plaintext()`).
+gets translated to ``\\`` by `ParsedEpytextDocstring.to_plaintext()`).
>>> colorizer = PyvalColorizer(linelen=40)
>>> print colorizer.colorize('x'*100).to_plaintext(None)
@@ -233,8 +233,8 @@
Representation Scores
=====================
When colorized representations are built, a score is computed
-evaluating how helpful the repr is. E.g., unhelpful values like `<Foo
-instance at 0x12345>` get low scores. Currently, the scoring
+evaluating how helpful the repr is. E.g., unhelpful values like ``<Foo
+instance at 0x12345>`` get low scores. Currently, the scoring
algorithm is:
- [+1] for each object colorized. When the colorizer recurses into
@@ -244,8 +244,8 @@
- [-100] if repr(obj) raises an exception, for any colorized object
(including objects in structures).
-The `min_score` arg to colorize can be used to set a cutoff-point for
-scores; if the score is too low, then `colorize` will return `None`.
+The ``min_score`` arg to colorize can be used to set a cutoff-point for
+scores; if the score is too low, then `PyvalColorizer.colorize` will return ``None``.
>>> def color2(v):
... colorizer = PyvalColorizer(linelen=40)
Modified: trunk/epydoc/src/epydoc/test/zope2.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/zope2.doctest 2007-02-19 22:55:22 UTC (rev 1535)
+++ trunk/epydoc/src/epydoc/test/zope2.doctest 2007-02-19 22:59:58 UTC (rev 1536)
@@ -52,6 +52,6 @@
+- RoutineDoc [18]
+- pyval = <CMethod object at ...>
-(If we didn't add special support, `ExtensionClass` would be a
+(If we didn't add special support, ``ExtensionClass`` would be a
`GenericValueDoc`.)
Modified: trunk/epydoc/src/epydoc/test/zope3.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/zope3.doctest 2007-02-19 22:55:22 UTC (rev 1535)
+++ trunk/epydoc/src/epydoc/test/zope3.doctest 2007-02-19 22:59:58 UTC (rev 1536)
@@ -23,5 +23,5 @@
+- canonical_name = DottedName('epydoc_test', 'IExample')
+- pyval = <InterfaceClass epydoc_test.IExample>
-(If we didn't add special support, `IExample` would be a
+(If we didn't add special support, ``IExample`` would be a
`GenericValueDoc`.)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-19 22:55:23
|
Revision: 1535
http://svn.sourceforge.net/epydoc/?rev=1535&view=rev
Author: dvarrazzo
Date: 2007-02-19 14:55:22 -0800 (Mon, 19 Feb 2007)
Log Message:
-----------
- Don't load duplicate entries in the URL generators.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docwriter/xlink.py
Modified: trunk/epydoc/src/epydoc/docwriter/xlink.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/xlink.py 2007-02-19 22:20:09 UTC (rev 1534)
+++ trunk/epydoc/src/epydoc/docwriter/xlink.py 2007-02-19 22:55:22 UTC (rev 1535)
@@ -283,6 +283,10 @@
% (self._filename, name))
continue
+ # discard duplicates
+ if name in self._exact_matches:
+ continue
+
self._exact_matches[name] = url
self._exact_matches[cname] = url
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-19 22:20:17
|
Revision: 1534
http://svn.sourceforge.net/epydoc/?rev=1534&view=rev
Author: dvarrazzo
Date: 2007-02-19 14:20:09 -0800 (Mon, 19 Feb 2007)
Log Message:
-----------
- Always using the registered name to get the resolver, so it can work
as default role too.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docwriter/xlink.py
Modified: trunk/epydoc/src/epydoc/docwriter/xlink.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/xlink.py 2007-02-19 19:50:59 UTC (rev 1533)
+++ trunk/epydoc/src/epydoc/docwriter/xlink.py 2007-02-19 22:20:09 UTC (rev 1534)
@@ -365,7 +365,7 @@
# Get the resolver from the register and create an url from it.
try:
- url = api_register[n].get_url(text)
+ url = api_register[name].get_url(text)
except IndexError, exc:
msg = inliner.reporter.warning(str(exc), line=lineno)
if problematic:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-19 19:51:00
|
Revision: 1533
http://svn.sourceforge.net/epydoc/?rev=1533&view=rev
Author: dvarrazzo
Date: 2007-02-19 11:50:59 -0800 (Mon, 19 Feb 2007)
Log Message:
-----------
- Using Epydoc logger to report index file parsing errors.
- More robust index file parsing.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docwriter/xlink.py
Modified: trunk/epydoc/src/epydoc/docwriter/xlink.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/xlink.py 2007-02-19 01:23:58 UTC (rev 1532)
+++ trunk/epydoc/src/epydoc/docwriter/xlink.py 2007-02-19 19:50:59 UTC (rev 1533)
@@ -79,6 +79,8 @@
from docutils.parsers.rst import roles
from docutils import nodes, utils
+from epydoc import log
+
class UrlGenerator:
"""
Generate URL from an object name.
@@ -199,6 +201,11 @@
Prefix portion for the URL's returned by `get_url()`.
"""
+ self._filename = None
+ """
+ Not very important: only for logging.
+ """
+
def get_url(self, name):
cname = self.get_canonical_name(name)
url = self._exact_matches.get(cname, None)
@@ -206,13 +213,13 @@
# go for a partial match
vals = self._partial_names.get(cname)
- if len(vals) == 1:
- url = self._exact_matches[vals[0]]
-
- elif not vals:
+ if vals is None:
raise IndexError(
"no object named '%s' found" % (name))
+ elif len(vals) == 1:
+ url = self._exact_matches[vals[0]]
+
else:
raise self.IndexAmbiguous(
"found %d objects that '%s' may refer to: %s"
@@ -240,16 +247,27 @@
f : `str` or file
a file name or file-like object fron which read the index.
"""
+ self._filename = str(f)
+
if isinstance(f, basestring):
- f = file(f)
+ f = open(f)
self.load_records(self._iter_tuples(f))
def _iter_tuples(self, f):
"""Iterate on a file returning 2-tuples."""
- for row in f:
- yield row.rstrip().split('\t', 1)
+ for nrow, row in enumerate(f):
+ # skip blank lines
+ row = row.rstrip()
+ if not row: continue
+ rec = row.split('\t', 2)
+ if len(rec) == 2:
+ yield rec
+ else:
+ log.warning("invalid row in '%s' row %d: '%s'"
+ % (self._filename, nrow+1, row))
+
def load_records(self, records):
"""
Read a sequence of pairs name -> url and populate the internal maps.
@@ -261,8 +279,9 @@
for name, url in records:
cname = self.get_canonical_name(name)
if not cname:
- # Have to decide how to warn.
- raise NotImplementedError("WARNING NAME NOT VALID")
+ log.warning("invalid object name in '%s': '%s'"
+ % (self._filename, name))
+ continue
self._exact_matches[name] = url
self._exact_matches[cname] = url
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-19 01:23:59
|
Revision: 1532
http://svn.sourceforge.net/epydoc/?rev=1532&view=rev
Author: dvarrazzo
Date: 2007-02-18 17:23:58 -0800 (Sun, 18 Feb 2007)
Log Message:
-----------
- Added script apirst2html.py to the package.
Modified Paths:
--------------
trunk/epydoc/src/setup.py
Modified: trunk/epydoc/src/setup.py
===================================================================
--- trunk/epydoc/src/setup.py 2007-02-18 23:07:25 UTC (rev 1531)
+++ trunk/epydoc/src/setup.py 2007-02-19 01:23:58 UTC (rev 1532)
@@ -19,6 +19,8 @@
else:
SCRIPTS = ['scripts/epydoc', 'scripts/epydocgui']
+SCRIPTS.append('scripts/apirst2html.py')
+
setup(name="epydoc",
description="Edward Loper's API Documentation Generation Tool",
version=VERSION,
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-18 23:07:29
|
Revision: 1531
http://svn.sourceforge.net/epydoc/?rev=1531&view=rev
Author: dvarrazzo
Date: 2007-02-18 15:07:25 -0800 (Sun, 18 Feb 2007)
Log Message:
-----------
- Added interpreted text directives to refer to external API.
- Epydoc HTML writer generates an index file suitable to be referred to.
- Added a script wrapping a Docutils HTML writer with external API reference
support.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/cli.py
trunk/epydoc/src/epydoc/docwriter/html.py
trunk/epydoc/src/epydoc/markup/restructuredtext.py
Added Paths:
-----------
trunk/epydoc/src/epydoc/docwriter/xlink.py
trunk/epydoc/src/scripts/apirst2html.py
Modified: trunk/epydoc/src/epydoc/cli.py
===================================================================
--- trunk/epydoc/src/epydoc/cli.py 2007-02-18 14:05:45 UTC (rev 1530)
+++ trunk/epydoc/src/epydoc/cli.py 2007-02-18 23:07:25 UTC (rev 1531)
@@ -76,6 +76,12 @@
import ConfigParser
from epydoc.docwriter.html_css import STYLESHEETS as CSS_STYLESHEETS
+# This module is only available if Docutils are in the system
+try:
+ from epydoc.docwriter import xlink
+except:
+ xlink = None
+
INHERITANCE_STYLES = ('grouped', 'listed', 'included')
GRAPH_TYPES = ('classtree', 'callgraph', 'umlclasstree')
ACTIONS = ('html', 'text', 'latex', 'dvi', 'ps', 'pdf', 'check')
@@ -129,7 +135,8 @@
debug=epydoc.DEBUG, profile=False, graphs=[],
list_classes_separately=False, graph_font=None, graph_font_size=None,
include_source_code=True, pstat_files=[], simple_term=False, fail_on=None,
- exclude=[], exclude_parse=[], exclude_introspect=[])
+ exclude=[], exclude_parse=[], exclude_introspect=[],
+ external_api=[],external_api_file=[],external_api_root=[])
def parse_arguments():
# Construct the option parser.
@@ -212,7 +219,7 @@
"list of available help topics")
- generation_group = OptionGroup(optparser, 'Generation options')
+ generation_group = OptionGroup(optparser, 'Generation Options')
optparser.add_option_group(generation_group)
generation_group.add_option("--docformat",
@@ -279,7 +286,7 @@
help=("Include a page with the process log (epydoc-log.html)"))
- output_group = OptionGroup(optparser, 'Output options')
+ output_group = OptionGroup(optparser, 'Output Options')
optparser.add_option_group(output_group)
output_group.add_option("--name",
@@ -325,7 +332,19 @@
"its own section, instead of listing them under their "
"containing module."))
- graph_group = OptionGroup(optparser, 'Graph options')
+ # The group of external API options.
+ # Skip if the module couldn't be imported (usually missing docutils)
+ if xlink is not None:
+ link_group = OptionGroup(optparser,
+ xlink.ApiLinkReader.settings_spec[0])
+ optparser.add_option_group(link_group)
+
+ for help, names, opts in xlink.ApiLinkReader.settings_spec[2]:
+ opts = opts.copy()
+ opts['help'] = help
+ link_group.add_option(*names, **opts)
+
+ graph_group = OptionGroup(optparser, 'Graph Options')
optparser.add_option_group(graph_group)
graph_group.add_option('--graph',
@@ -363,7 +382,7 @@
"will be written to profile.out."))
- return_group = OptionGroup(optparser, 'Return value options')
+ return_group = OptionGroup(optparser, 'Return Value Options')
optparser.add_option_group(return_group)
return_group.add_option("--fail-on-error",
@@ -547,6 +566,14 @@
elif optname in ('separate-classes', 'separate_classes'):
options.list_classes_separately = _str_to_bool(val, optname)
+ # External API
+ elif optname in ('external-api', 'external_api'):
+ options.external_api.extend(val.replace(',', ' ').split())
+ elif optname in ('external-api-file', 'external_api_file'):
+ options.external_api_file.append(val)
+ elif optname in ('external-api-root', 'external_api_root'):
+ options.external_api_root.append(val)
+
# Graph options
elif optname == 'graph':
graphtypes = val.replace(',', '').split()
@@ -662,6 +689,14 @@
from epydoc import docstringparser
docstringparser.DEFAULT_DOCFORMAT = options.docformat
+ # Configure the external API linking
+ if xlink is not None:
+ try:
+ xlink.ApiLinkReader.read_configuration(options, problematic=False)
+ except Exception, exc:
+ log.error("Error while configuring external API linking: %s: %s"
+ % (exc.__class__.__name__, exc))
+
# Set the dot path
if options.dotpath:
from epydoc.docwriter import dotgraph
Modified: trunk/epydoc/src/epydoc/docwriter/html.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/html.py 2007-02-18 14:05:45 UTC (rev 1530)
+++ trunk/epydoc/src/epydoc/docwriter/html.py 2007-02-18 23:07:25 UTC (rev 1531)
@@ -430,7 +430,7 @@
if isinstance(doc, ModuleDoc) and is_src_filename(doc.filename):
self.modules_with_sourcecode.add(doc)
self._num_files = (len(self.class_list) + 2*len(self.module_list) +
- 12 + len(self.METADATA_INDICES))
+ 13 + len(self.METADATA_INDICES))
if self._incl_sourcecode:
self._num_files += len(self.modules_with_sourcecode)
if self._split_ident_index:
@@ -647,6 +647,9 @@
# Write the auto-redirect page.
self._write(self.write_redirect_page, directory, 'redirect.html')
+ # Write the mapping object name -> URL
+ self._write(self.write_api_list, directory, 'api-objects.txt')
+
# Write the index.html files.
# (this must be done last, since it might copy another file)
self._files_written += 1
@@ -2953,6 +2956,35 @@
# \------------------------------------------------------------/
#////////////////////////////////////////////////////////////
+ #{ URLs list
+ #////////////////////////////////////////////////////////////
+
+ def write_api_list(self, out):
+ """
+ Write a list of mapping name->url for all the documented objects.
+ """
+ # Construct a list of all the module & class pages that we're
+ # documenting. The redirect_url javascript will scan through
+ # this list, looking for a page name that matches the
+ # requested dotted name.
+ skip = (ModuleDoc, ClassDoc, type(UNKNOWN))
+ for val_doc in self.module_list:
+ self.write_url_record(out, val_doc)
+ for var in val_doc.variables.itervalues():
+ if not isinstance(var.value, skip):
+ self.write_url_record(out, var)
+
+ for val_doc in self.class_list:
+ self.write_url_record(out, val_doc)
+ for var in val_doc.variables.itervalues():
+ self.write_url_record(out, var)
+
+ def write_url_record(self, out, obj):
+ url = self.url(obj)
+ if url is not None:
+ out("%s\t%s\n" % (obj.canonical_name, url))
+
+ #////////////////////////////////////////////////////////////
#{ Helper functions
#////////////////////////////////////////////////////////////
Added: trunk/epydoc/src/epydoc/docwriter/xlink.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/xlink.py (rev 0)
+++ trunk/epydoc/src/epydoc/docwriter/xlink.py 2007-02-18 23:07:25 UTC (rev 1531)
@@ -0,0 +1,459 @@
+"""
+A Docutils_ interpreted text role for cross-API reference support.
+
+This module allows a Docutils_ document to refer to elements defined in
+external API documentation. It is possible to refer to many external API
+from the same document.
+
+Each API documentation is assigned a new interpreted text role: using such
+interpreted text, an user can specify an object name inside an API
+documentation. The system will convert such text into an url and generate a
+reference to it. For example, if the API ``db`` is defined, being a database
+package, then a certain method may be referred as::
+
+ :db:`Connection.cursor()`
+
+To define a new API, an *index file* must be provided. This file contains
+a mapping from the object name to the URL part required to resolve such object.
+
+Index file
+----------
+
+Each line in the the index file describes an object.
+
+Each line contains the fully qualified name of the object and the URL at which
+the documentation is located. The fields are separated by a ``<tab>``
+character.
+
+The URL's in the file are relative from the documentation root: the system can
+be configured to add a prefix in front of each returned URL.
+
+Allowed names
+-------------
+
+When a name is used in an API text role, it is split over any *separator*.
+The separators defined are '``.``', '``::``', '``->``'. All the text from the
+first noise char (neither a separator nor alphanumeric or '``_``') is
+discarded. The same algorithm is applied when the index file is read.
+
+First the sequence of name parts is looked for in the provided index file.
+If no matching name is found, a partial match against the trailing part of the
+names in the index is performed. If no object is found, or if the trailing part
+of the name may refer to many objects, a warning is issued and no reference
+is created.
+
+Configuration
+-------------
+
+This module provides the class `ApiLinkReader` a replacement for the Docutils
+standalone reader. Such reader specifies the settings required for the
+API canonical roles configuration. The same command line options are exposed by
+Epydoc.
+
+The script ``apirst2html.py`` is a frontend for the `ApiLinkReader` reader.
+
+API Linking Options::
+
+ --external-api=NAME
+ Define a new API document. A new interpreted text
+ role NAME will be added.
+ --external-api-file=NAME:FILENAME
+ Use records in FILENAME to resolve objects in the API
+ named NAME.
+ --external-api-root=NAME:STRING
+ Use STRING as prefix for the URL generated from the
+ API NAME.
+
+.. _Docutils: http://docutils.sourceforge.net/
+"""
+
+# $Id$
+__version__ = "$Revision$"[11:-2]
+__author__ = "Daniele Varrazzo"
+__copyright__ = "Copyright (C) 2007 by Daniele Varrazzo"
+__docformat__ = 'reStructuredText en'
+
+import re
+import sys
+
+from docutils.parsers.rst import roles
+from docutils import nodes, utils
+
+class UrlGenerator:
+ """
+ Generate URL from an object name.
+ """
+ class IndexAmbiguous(IndexError):
+ """
+ The name looked for is ambiguous
+ """
+
+ def get_url(self, name):
+ """Look for a name and return the matching URL documentation.
+
+ First look for a fully qualified name. If not found, try with partial
+ name.
+
+ If no url exists for the given object, return `None`.
+
+ :Parameters:
+ `name` : `str`
+ the name to look for
+
+ :return: the URL that can be used to reach the `name` documentation.
+ `None` if no such URL exists.
+ :rtype: `str`
+
+ :Exceptions:
+ - `IndexError`: no object found with `name`
+ - `DocUrlGenerator.IndexAmbiguous` : more than one object found with
+ a non-fully qualified name; notice that this is an ``IndexError``
+ subclass
+ """
+ raise NotImplementedError
+
+ def get_canonical_name(self, name):
+ """
+ Convert an object name into a canonical name.
+
+ the canonical name of an object is a tuple of strings containing its
+ name fragments, splitted on any allowed separator ('``.``', '``::``',
+ '``->``').
+
+ Noise such parenthesis to indicate a function is discarded.
+
+ :Parameters:
+ `name` : `str`
+ an object name, such as ``os.path.prefix()`` or ``lib::foo::bar``
+
+ :return: the fully qualified name such ``('os', 'path', 'prefix')`` and
+ ``('lib', 'foo', 'bar')``
+ :rtype: `tuple` of `str`
+ """
+ rv = []
+ for m in self._SEP_RE.finditer(name):
+ groups = m.groups()
+ if groups[0] is not None:
+ rv.append(groups[0])
+ elif groups[2] is not None:
+ break
+
+ return tuple(rv)
+
+ _SEP_RE = re.compile(r"""(?x)
+ # Tokenize the input into keyword, separator, noise
+ ([a-zA-Z0-9_]+) | # A keyword is a alphanum word
+ ( \. | \:\: | \-\> ) | # These are the allowed separators
+ (.) # If it doesn't fit, it's noise.
+ # Matching a single noise char is enough, because it
+ # is used to break the tokenization as soon as some noise
+ # is found.
+ """)
+
+
+class VoidUrlGenerator(UrlGenerator):
+ """
+ Don't actually know any url, but don't report any error.
+
+ Useful if an index file is not available, but a document linking to it
+ is to be generated, and warnings are to be avoided.
+
+ Don't report any object as missing, Don't return any url anyway.
+ """
+ def get_url(self, name):
+ return None
+
+
+class DocUrlGenerator(UrlGenerator):
+ """
+ Read a *documentation index* and generate URL's for it.
+ """
+ def __init__(self):
+ self._exact_matches = {}
+ """
+ A map from an object fully qualified name to its URL.
+
+ Values are both the name as tuple of fragments and as read from the
+ records (see `load_records()`), mostly to help `_partial_names` to
+ perform lookup for unambiguous names.
+ """
+
+ self._partial_names= {}
+ """
+ A map from partial names to the fully qualified names they may refer.
+
+ The keys are the possible left sub-tuples of fully qualified names,
+ the values are list of strings as provided by the index.
+
+ If the list for a given tuple contains a single item, the partial
+ match is not ambuguous. In this case the string can be looked up in
+ `_exact_matches`.
+
+ If the name fragment is ambiguous, a warning may be issued to the user.
+ The items can be used to provide an informative message to the user,
+ to help him qualifying the name in a unambiguous manner.
+ """
+
+ self.prefix = ''
+ """
+ Prefix portion for the URL's returned by `get_url()`.
+ """
+
+ def get_url(self, name):
+ cname = self.get_canonical_name(name)
+ url = self._exact_matches.get(cname, None)
+ if url is None:
+
+ # go for a partial match
+ vals = self._partial_names.get(cname)
+ if len(vals) == 1:
+ url = self._exact_matches[vals[0]]
+
+ elif not vals:
+ raise IndexError(
+ "no object named '%s' found" % (name))
+
+ else:
+ raise self.IndexAmbiguous(
+ "found %d objects that '%s' may refer to: %s"
+ % (len(vals), name, ", ".join(["'%s'" % n for n in vals])))
+
+ return self.prefix + url
+
+ #{ Content loading
+ # ---------------
+
+ def clear(self):
+ """
+ Clear the current class content.
+ """
+ self._exact_matches.clear()
+ self._partial_names.clear()
+
+ def load_index(self, f):
+ """
+ Read the content of an index file.
+
+ Populate the internal maps with the file content using `load_records()`.
+
+ :Parameters:
+ f : `str` or file
+ a file name or file-like object fron which read the index.
+ """
+ if isinstance(f, basestring):
+ f = file(f)
+
+ self.load_records(self._iter_tuples(f))
+
+ def _iter_tuples(self, f):
+ """Iterate on a file returning 2-tuples."""
+ for row in f:
+ yield row.rstrip().split('\t', 1)
+
+ def load_records(self, records):
+ """
+ Read a sequence of pairs name -> url and populate the internal maps.
+
+ :Parameters:
+ records : iterable
+ the sequence of pairs (*name*, *url*) to add to the maps.
+ """
+ for name, url in records:
+ cname = self.get_canonical_name(name)
+ if not cname:
+ # Have to decide how to warn.
+ raise NotImplementedError("WARNING NAME NOT VALID")
+
+ self._exact_matches[name] = url
+ self._exact_matches[cname] = url
+
+ # Link the different ambiguous fragments to the url
+ for i in range(1, len(cname)):
+ self._partial_names.setdefault(cname[i:], []).append(name)
+
+#{ API register
+# ------------
+
+api_register = {}
+"""
+Mapping from the API name to the `UrlGenerator` to be used.
+"""
+
+def register_api(name, generator=None):
+ """Register the API `name` into the `api_register`.
+
+ A registered API is available to the markup as the interpreted text
+ role ``name``.
+
+ If a `generator` is not provided, register a `VoidUrlGenerator` instance:
+ in this case no warning will be issued for missing names, but no URL will
+ be generated and all the dotted names will simply be rendered as literals.
+
+ :Parameters:
+ `name` : `str`
+ the name of the generator to be registered
+ `generator` : `UrlGenerator`
+ the object to register to translate names into URLs.
+ """
+ if generator is None:
+ generator = VoidUrlGenerator()
+
+ api_register[name] = generator
+
+def set_api_file(name, file):
+ """Set an URL generator populated with data from `file`.
+
+ Use `file` to populate a new `DocUrlGenerator` instance and register it
+ as `name`.
+
+ :Parameters:
+ `name` : `str`
+ the name of the generator to be registered
+ `file` : `str` or file
+ the file to parse populate the URL generator
+ """
+ generator = DocUrlGenerator()
+ generator.load_index(file)
+ register_api(name, generator)
+
+def set_api_root(name, prefix):
+ """Set the root for the URLs returned by a registered URL generator.
+
+ :Parameters:
+ `name` : `str`
+ the name of the generator to be updated
+ `prefix` : `str`
+ the prefix for the generated URL's
+
+ :Exceptions:
+ - `IndexError`: `name` is not a registered generator
+ """
+ api_register[name].prefix = prefix
+
+def create_api_role(name, problematic):
+ """
+ Create and register a new role to create links for an API documentation.
+
+ Create a role called `name`, which will use the ``name`` registered
+ URL resolver to create a link for an object.
+ """
+ def resolve_api_name(n, rawtext, text, lineno, inliner,
+ options={}, content=[]):
+
+ # node in monotype font
+ text = utils.unescape(text)
+ node = nodes.literal(rawtext, text, **options)
+
+ # Get the resolver from the register and create an url from it.
+ try:
+ url = api_register[n].get_url(text)
+ except IndexError, exc:
+ msg = inliner.reporter.warning(str(exc), line=lineno)
+ if problematic:
+ prb = inliner.problematic(rawtext, text, msg)
+ return [prb], [msg]
+ else:
+ return [node], []
+
+ if url is not None:
+ node = nodes.reference(rawtext, '', node, refuri=url, **options)
+ return [node], []
+
+ roles.register_local_role(name, resolve_api_name)
+
+
+#{ Command line parsing
+# --------------------
+
+#from docutils import SettingsSpec
+from optparse import OptionValueError
+
+def split_name(value):
+ """
+ Split an option in form ``NAME:VALUE`` and check if ``NAME`` exists.
+ """
+ parts = value.split(':', 1)
+ if len(parts) != 2:
+ raise OptionValueError(
+ "option value must be specified as NAME:VALUE; got '%s' instead"
+ % value)
+
+ name, val = parts
+
+ if name not in api_register:
+ raise OptionValueError(
+ "the name '%s' has not been registered; use --external-api"
+ % name)
+
+ return (name, val)
+
+from docutils.readers.standalone import Reader
+
+class ApiLinkReader(Reader):
+ """
+ A Docutils standalone reader allowing external documentation links.
+
+ The reader configure the url resolvers at the time `read()` is invoked the
+ first time.
+ """
+ #: The option parser configuration.
+ settings_spec = (
+ 'API Linking Options',
+ None,
+ ((
+ 'Define a new API document. A new interpreted text role NAME will be '
+ 'added.',
+ ['--external-api'],
+ {'metavar': 'NAME', 'action': 'append'}
+ ), (
+ 'Use records in FILENAME to resolve objects in the API named NAME.',
+ ['--external-api-file'],
+ {'metavar': 'NAME:FILENAME', 'action': 'append'}
+ ), (
+ 'Use STRING as prefix for the URL generated from the API NAME.',
+ ['--external-api-root'],
+ {'metavar': 'NAME:STRING', 'action': 'append'}
+ ),)) + Reader.settings_spec
+
+ def read(self, source, parser, settings):
+ self.read_configuration(settings, problematic=True)
+ return Reader.read(self, source, parser, settings)
+
+ def read_configuration(self, settings, problematic=True):
+ """
+ Read the configuration for the configured URL resolver.
+
+ Register a new role for each configured API.
+
+ :Parameters:
+ `settings`
+ the settings structure containing the options to read.
+ `problematic` : `bool`
+ if True, the registered role will create problematic nodes in
+ case of failed references. If False, a warning will be raised
+ anyway, but the output will appear as an ordinary literal.
+ """
+ # Read config only once
+ if hasattr(self, '_conf'):
+ return
+ ApiLinkReader._conf = True
+
+ try:
+ if settings.external_api is not None:
+ for name in settings.external_api:
+ register_api(name)
+ create_api_role(name, problematic=problematic)
+
+ if settings.external_api_file is not None:
+ for name, file in map(split_name, settings.external_api_file):
+ set_api_file(name, file)
+
+ if settings.external_api_root is not None:
+ for name, root in map(split_name, settings.external_api_root):
+ set_api_root(name, root)
+
+ except OptionValueError, exc:
+ print >>sys.stderr, "%s: %s" % (exc.__class__.__name__, exc)
+ sys.exit(2)
+
+ read_configuration = classmethod(read_configuration)
Property changes on: trunk/epydoc/src/epydoc/docwriter/xlink.py
___________________________________________________________________
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ native
Modified: trunk/epydoc/src/epydoc/markup/restructuredtext.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/restructuredtext.py 2007-02-18 14:05:45 UTC (rev 1530)
+++ trunk/epydoc/src/epydoc/markup/restructuredtext.py 2007-02-18 23:07:25 UTC (rev 1531)
@@ -88,6 +88,7 @@
from epydoc.markup import *
from epydoc.apidoc import ModuleDoc, ClassDoc
from epydoc.docwriter.dotgraph import *
+from epydoc.docwriter.xlink import ApiLinkReader
from epydoc.markup.doctest import doctest_to_html, doctest_to_latex, \
HTMLDoctestColorizer
@@ -207,7 +208,7 @@
def __repr__(self): return '<ParsedRstDocstring: ...>'
-class _EpydocReader(StandaloneReader):
+class _EpydocReader(ApiLinkReader):
"""
A reader that captures all errors that are generated by parsing,
and appends them to a list.
@@ -220,18 +221,18 @@
version = [int(v) for v in docutils.__version__.split('.')]
version += [ 0 ] * (3 - len(version))
if version < [0,4,0]:
- default_transforms = list(StandaloneReader.default_transforms)
+ default_transforms = list(ApiLinkReader.default_transforms)
try: default_transforms.remove(docutils.transforms.frontmatter.DocInfo)
except ValueError: pass
else:
def get_transforms(self):
- return [t for t in StandaloneReader.get_transforms(self)
+ return [t for t in ApiLinkReader.get_transforms(self)
if t != docutils.transforms.frontmatter.DocInfo]
del version
def __init__(self, errors):
self._errors = errors
- StandaloneReader.__init__(self)
+ ApiLinkReader.__init__(self)
def new_document(self):
document = new_document(self.source.source_path, self.settings)
Added: trunk/epydoc/src/scripts/apirst2html.py
===================================================================
--- trunk/epydoc/src/scripts/apirst2html.py (rev 0)
+++ trunk/epydoc/src/scripts/apirst2html.py 2007-02-18 23:07:25 UTC (rev 1531)
@@ -0,0 +1,41 @@
+#!/usr/bin/env python
+# -*- coding: iso-8859-1 -*-
+
+"""An HTML writer supporting link to external documentation.
+
+This module is a frontend for the Docutils_ HTML writer. It allows a document
+to reference objects documented in the API documentation generated by
+extraction tools such as Doxygen_ or Epydoc_.
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _Doxygen: http://www.doxygen.org/
+.. _Epydoc: http://epydoc.sourceforge.net/
+"""
+
+# $Id$
+__version__ = "$Revision$"[11:-2]
+__author__ = "Daniele Varrazzo"
+__copyright__ = "Copyright (C) 2007 by Daniele Varrazzo"
+__docformat__ = 'reStructuredText en'
+
+try:
+ import locale
+ locale.setlocale(locale.LC_ALL, '')
+except:
+ pass
+
+# We have to do some path magic to prevent Python from getting
+# confused about the difference between the ``epydoc.py`` script, and the
+# real ``epydoc`` package. So remove ``sys.path[0]``, which contains the
+# directory of the script.
+import sys, os.path
+script_path = os.path.abspath(sys.path[0])
+sys.path = [p for p in sys.path if os.path.abspath(p) != script_path]
+
+import epydoc.docwriter.xlink as xlink
+
+from docutils.core import publish_cmdline, default_description
+description = ('Generates (X)HTML documents with API documentation links. '
+ + default_description)
+publish_cmdline(reader=xlink.ApiLinkReader(), writer_name='html',
+ description=description)
Property changes on: trunk/epydoc/src/scripts/apirst2html.py
___________________________________________________________________
Name: svn:executable
+ *
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ native
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-18 14:05:47
|
Revision: 1530
http://svn.sourceforge.net/epydoc/?rev=1530&view=rev
Author: dvarrazzo
Date: 2007-02-18 06:05:45 -0800 (Sun, 18 Feb 2007)
Log Message:
-----------
- configuration file up-to-date with command line
- command line source code reformatted. Dropped those comments always
out of date...
Modified Paths:
--------------
trunk/epydoc/src/epydoc/cli.py
Modified: trunk/epydoc/src/epydoc/cli.py
===================================================================
--- trunk/epydoc/src/epydoc/cli.py 2007-02-18 12:34:08 UTC (rev 1529)
+++ trunk/epydoc/src/epydoc/cli.py 2007-02-18 14:05:45 UTC (rev 1530)
@@ -136,213 +136,252 @@
usage = '%prog [ACTION] [options] NAMES...'
version = "Epydoc, version %s" % epydoc.__version__
optparser = OptionParser(usage=usage, add_help_option=False)
- action_group = OptionGroup(optparser, 'Actions')
- generation_group = OptionGroup(optparser, 'Generation options')
- output_group = OptionGroup(optparser, 'Output options')
- graph_group = OptionGroup(optparser, 'Graph options')
- return_group = OptionGroup(optparser, 'Return value options')
- optparser.add_option(
- '--config', action='append', dest="configfiles", metavar='FILE',
+ optparser.add_option('--config',
+ action='append', dest="configfiles", metavar='FILE',
help=("A configuration file, specifying additional OPTIONS "
"and/or NAMES. This option may be repeated."))
- optparser.add_option( # --quiet
- "--quiet", "-q", action="count", dest="quiet",
+
+ optparser.add_option("--output", "-o",
+ dest="target", metavar="PATH",
+ help="The output directory. If PATH does not exist, then "
+ "it will be created.")
+
+ optparser.add_option("--quiet", "-q",
+ action="count", dest="quiet",
help="Decrease the verbosity.")
- optparser.add_option( # --verbose
- "--verbose", "-v", action="count", dest="verbose",
+
+ optparser.add_option("--verbose", "-v",
+ action="count", dest="verbose",
help="Increase the verbosity.")
- optparser.add_option( # --debug
- "--debug", action="store_true", dest="debug",
+
+ optparser.add_option("--debug",
+ action="store_true", dest="debug",
help="Show full tracebacks for internal errors.")
- optparser.add_option(
- "--simple-term", action="store_true", dest="simple_term",
+
+ optparser.add_option("--simple-term",
+ action="store_true", dest="simple_term",
help="Do not try to use color or cursor control when displaying "
"the progress bar, warnings, or errors.")
-
- # Add options -- Actions
- action_group.add_option( # --html
- "--html", action="store_const", dest="action", const="html",
+
+
+ action_group = OptionGroup(optparser, 'Actions')
+ optparser.add_option_group(action_group)
+
+ action_group.add_option("--html",
+ action="store_const", dest="action", const="html",
help="Write HTML output.")
- action_group.add_option( # --latex
- "--text", action="store_const", dest="action", const="text",
+
+ action_group.add_option("--text",
+ action="store_const", dest="action", const="text",
help="Write plaintext output. (not implemented yet)")
- action_group.add_option( # --latex
- "--latex", action="store_const", dest="action", const="latex",
+
+ action_group.add_option("--latex",
+ action="store_const", dest="action", const="latex",
help="Write LaTeX output.")
- action_group.add_option( # --dvi
- "--dvi", action="store_const", dest="action", const="dvi",
+
+ action_group.add_option("--dvi",
+ action="store_const", dest="action", const="dvi",
help="Write DVI output.")
- action_group.add_option( # --ps
- "--ps", action="store_const", dest="action", const="ps",
+
+ action_group.add_option("--ps",
+ action="store_const", dest="action", const="ps",
help="Write Postscript output.")
- action_group.add_option( # --pdf
- "--pdf", action="store_const", dest="action", const="pdf",
+
+ action_group.add_option("--pdf",
+ action="store_const", dest="action", const="pdf",
help="Write PDF output.")
- action_group.add_option( # --check
- "--check", action="store_const", dest="action", const="check",
+
+ action_group.add_option("--check",
+ action="store_const", dest="action", const="check",
help="Check completeness of docs.")
- action_group.add_option(
- "--pickle", action="store_const", dest="action", const="pickle",
+
+ action_group.add_option("--pickle",
+ action="store_const", dest="action", const="pickle",
help="Write the documentation to a pickle file.")
+
# Provide our own --help and --version options.
- action_group.add_option(
- "--version", action="store_const", dest="action", const="version",
+ action_group.add_option("--version",
+ action="store_const", dest="action", const="version",
help="Show epydoc's version number and exit.")
- action_group.add_option(
- "-h", "--help", action="store_const", dest="action", const="help",
+
+ action_group.add_option("-h", "--help",
+ action="store_const", dest="action", const="help",
help="Show this message and exit. For help on specific "
"topics, use \"--help TOPIC\". Use \"--help topics\" for a "
"list of available help topics")
- # Add options -- Generation
- generation_group.add_option( # --docformat
- "--docformat", dest="docformat", metavar="NAME",
+
+ generation_group = OptionGroup(optparser, 'Generation options')
+ optparser.add_option_group(generation_group)
+
+ generation_group.add_option("--docformat",
+ dest="docformat", metavar="NAME",
help="The default markup language for docstrings. Defaults "
"to \"%s\"." % DEFAULT_DOCFORMAT)
- generation_group.add_option( # --parse-only
- "--parse-only", action="store_false", dest="introspect",
+
+ generation_group.add_option("--parse-only",
+ action="store_false", dest="introspect",
help="Get all information from parsing (don't introspect)")
- generation_group.add_option( # --introspect-only
- "--introspect-only", action="store_false", dest="parse",
+
+ generation_group.add_option("--introspect-only",
+ action="store_false", dest="parse",
help="Get all information from introspecting (don't parse)")
- generation_group.add_option( # --exclude-introspect
- "--exclude", dest="exclude", metavar="PATTERN",
- action="append",
+
+ generation_group.add_option("--exclude",
+ dest="exclude", metavar="PATTERN", action="append",
help="Exclude modules whose dotted name matches "
"the regular expression PATTERN")
- generation_group.add_option( # --exclude-introspect
- "--exclude-introspect", dest="exclude_introspect", metavar="PATTERN",
- action="append",
+
+ generation_group.add_option("--exclude-introspect",
+ dest="exclude_introspect", metavar="PATTERN", action="append",
help="Exclude introspection of modules whose dotted name matches "
"the regular expression PATTERN")
- generation_group.add_option( # --exclude-parse
- "--exclude-parse", dest="exclude_parse", metavar="PATTERN",
- action="append",
+
+ generation_group.add_option("--exclude-parse",
+ dest="exclude_parse", metavar="PATTERN", action="append",
help="Exclude parsing of modules whose dotted name matches "
"the regular expression PATTERN")
- generation_group.add_option( # --inheritance
- "--inheritance", dest="inheritance", metavar="STYLE",
+
+ generation_group.add_option("--inheritance",
+ dest="inheritance", metavar="STYLE",
help="The format for showing inheritance objects. STYLE "
"should be one of: %s." % ', '.join(INHERITANCE_STYLES))
- generation_group.add_option( # --show-private
- "--show-private", action="store_true", dest="show_private",
+
+ generation_group.add_option("--show-private",
+ action="store_true", dest="show_private",
help="Include private variables in the output. (default)")
- generation_group.add_option( # --no-private
- "--no-private", action="store_false", dest="show_private",
+
+ generation_group.add_option("--no-private",
+ action="store_false", dest="show_private",
help="Do not include private variables in the output.")
- generation_group.add_option( # --show-imports
- "--show-imports", action="store_true", dest="show_imports",
+
+ generation_group.add_option("--show-imports",
+ action="store_true", dest="show_imports",
help="List each module's imports.")
- generation_group.add_option( # --no-imports
- "--no-imports", action="store_false", dest="show_imports",
+
+ generation_group.add_option("--no-imports",
+ action="store_false", dest="show_imports",
help="Do not list each module's imports. (default)")
- generation_group.add_option( # --show-sourcecode
- '--show-sourcecode', action='store_true', dest='include_source_code',
+
+ generation_group.add_option('--show-sourcecode',
+ action='store_true', dest='include_source_code',
help=("Include source code with syntax highlighting in the "
"HTML output. (default)"))
- generation_group.add_option( # --no-sourcecode
- '--no-sourcecode', action='store_false', dest='include_source_code',
+
+ generation_group.add_option('--no-sourcecode',
+ action='store_false', dest='include_source_code',
help=("Do not include source code with syntax highlighting in the "
"HTML output."))
- generation_group.add_option( # --include-log
- '--include-log', action='store_true', dest='include_log',
+
+ generation_group.add_option('--include-log',
+ action='store_true', dest='include_log',
help=("Include a page with the process log (epydoc-log.html)"))
- # Add options -- Output
- output_group.add_option( # --output
- "--output", "-o", dest="target", metavar="PATH",
- help="The output directory. If PATH does not exist, then "
- "it will be created.")
- output_group.add_option( # --css
- "--css", dest="css", metavar="STYLESHEET",
+
+ output_group = OptionGroup(optparser, 'Output options')
+ optparser.add_option_group(output_group)
+
+ output_group.add_option("--name",
+ dest="prj_name", metavar="NAME",
+ help="The documented project's name (for the navigation bar).")
+
+ output_group.add_option("--css",
+ dest="css", metavar="STYLESHEET",
help="The CSS stylesheet. STYLESHEET can be either a "
"builtin stylesheet or the name of a CSS file.")
- output_group.add_option( # --name
- "--name", dest="prj_name", metavar="NAME",
- help="The documented project's name (for the navigation bar).")
- output_group.add_option( # --url
- "--url", dest="prj_url", metavar="URL",
+
+ output_group.add_option("--url",
+ dest="prj_url", metavar="URL",
help="The documented project's URL (for the navigation bar).")
- output_group.add_option( # --navlink
- "--navlink", dest="prj_link", metavar="HTML",
+
+ output_group.add_option("--navlink",
+ dest="prj_link", metavar="HTML",
help="HTML code for a navigation link to place in the "
"navigation bar.")
- output_group.add_option( # --top
- "--top", dest="top_page", metavar="PAGE",
+
+ output_group.add_option("--top",
+ dest="top_page", metavar="PAGE",
help="The \"top\" page for the HTML documentation. PAGE can "
"be a URL, the name of a module or class, or one of the "
"special names \"trees.html\", \"indices.html\", or \"help.html\"")
- output_group.add_option( # --help-file
- "--help-file", dest="help_file", metavar="FILE",
+
+ output_group.add_option("--help-file",
+ dest="help_file", metavar="FILE",
help="An alternate help file. FILE should contain the body "
"of an HTML file -- navigation bars will be added to it.")
- output_group.add_option( # --frames
- "--show-frames", action="store_true", dest="show_frames",
+
+ output_group.add_option("--show-frames",
+ action="store_true", dest="show_frames",
help="Include frames in the HTML output. (default)")
- output_group.add_option( # --no-frames
- "--no-frames", action="store_false", dest="show_frames",
+
+ output_group.add_option("--no-frames",
+ action="store_false", dest="show_frames",
help="Do not include frames in the HTML output.")
- output_group.add_option( # --separate-classes
- '--separate-classes', action='store_true',
- dest='list_classes_separately',
+
+ output_group.add_option('--separate-classes',
+ action='store_true', dest='list_classes_separately',
help=("When generating LaTeX or PDF output, list each class in "
"its own section, instead of listing them under their "
"containing module."))
- # Add options -- Graph options
- graph_group.add_option(
- '--graph', action='append', dest='graphs', metavar='GRAPHTYPE',
+ graph_group = OptionGroup(optparser, 'Graph options')
+ optparser.add_option_group(graph_group)
+
+ graph_group.add_option('--graph',
+ action='append', dest='graphs', metavar='GRAPHTYPE',
help=("Include graphs of type GRAPHTYPE in the generated output. "
"Graphs are generated using the Graphviz dot executable. "
"If this executable is not on the path, then use --dotpath "
"to specify its location. This option may be repeated to "
"include multiple graph types in the output. GRAPHTYPE "
"should be one of: all, %s." % ', '.join(GRAPH_TYPES)))
- graph_group.add_option(
- "--dotpath", dest="dotpath", metavar='PATH',
+
+ graph_group.add_option("--dotpath",
+ dest="dotpath", metavar='PATH',
help="The path to the Graphviz 'dot' executable.")
- graph_group.add_option(
- '--graph-font', dest='graph_font', metavar='FONT',
+
+ graph_group.add_option('--graph-font',
+ dest='graph_font', metavar='FONT',
help=("Specify the font used to generate Graphviz graphs. (e.g., "
"helvetica or times)."))
- graph_group.add_option(
- '--graph-font-size', dest='graph_font_size', metavar='SIZE',
+
+ graph_group.add_option('--graph-font-size',
+ dest='graph_font_size', metavar='SIZE',
help=("Specify the font size used to generate Graphviz graphs, "
"in points."))
- graph_group.add_option(
- '--pstat', action='append', dest='pstat_files', metavar='FILE',
+
+ graph_group.add_option('--pstat',
+ action='append', dest='pstat_files', metavar='FILE',
help="A pstat output file, to be used in generating call graphs.")
+
# this option is for developers, not users.
- graph_group.add_option(
- "--profile-epydoc", action="store_true", dest="profile",
+ graph_group.add_option("--profile-epydoc",
+ action="store_true", dest="profile",
help=SUPPRESS_HELP or
("Run the hotshot profiler on epydoc itself. Output "
"will be written to profile.out."))
- return_group.add_option(
- "--fail-on-error", action="store_const", dest="fail_on",
- const=log.ERROR,
+
+ return_group = OptionGroup(optparser, 'Return value options')
+ optparser.add_option_group(return_group)
+
+ return_group.add_option("--fail-on-error",
+ action="store_const", dest="fail_on", const=log.ERROR,
help="Return a non-zero exit status, indicating failure, if any "
"errors are encountered.")
- return_group.add_option(
- "--fail-on-warning", action="store_const", dest="fail_on",
- const=log.WARNING,
+
+ return_group.add_option("--fail-on-warning",
+ action="store_const", dest="fail_on", const=log.WARNING,
help="Return a non-zero exit status, indicating failure, if any "
"errors or warnings are encountered (not including docstring "
"warnings).")
- return_group.add_option(
- "--fail-on-docstring-warning", action="store_const", dest="fail_on",
- const=log.DOCSTRING_WARNING,
+
+ return_group.add_option("--fail-on-docstring-warning",
+ action="store_const", dest="fail_on", const=log.DOCSTRING_WARNING,
help="Return a non-zero exit status, indicating failure, if any "
"errors or warnings are encountered (including docstring "
"warnings).")
- # Add the option groups.
- optparser.add_option_group(action_group)
- optparser.add_option_group(generation_group)
- optparser.add_option_group(output_group)
- optparser.add_option_group(graph_group)
- optparser.add_option_group(return_group)
# Set the option parser's defaults.
optparser.set_defaults(**OPTION_DEFAULTS)
@@ -445,27 +484,56 @@
for optname in configparser.options('epydoc'):
val = configparser.get('epydoc', optname, vars=os.environ).strip()
optname = optname.lower().strip()
+
if optname in ('modules', 'objects', 'values',
'module', 'object', 'value'):
names.extend(val.replace(',', ' ').split())
+ elif optname == 'target':
+ options.target = val
elif optname == 'output':
if val.lower() not in ACTIONS:
raise ValueError('"%s" expected one of: %s' %
(optname, ', '.join(ACTIONS)))
options.action = val.lower()
- elif optname == 'target':
- options.target = val
+ elif optname == 'verbosity':
+ options.verbosity = _str_to_int(val, optname)
+ elif optname == 'debug':
+ options.debug = _str_to_bool(val, optname)
+ elif optname in ('simple-term', 'simple_term'):
+ options.simple_term = _str_to_bool(val, optname)
+
+ # Generation options
+ elif optname == 'docformat':
+ options.docformat = val
+ elif optname == 'parse':
+ options.parse = _str_to_bool(val, optname)
+ elif optname == 'introspect':
+ options.introspect = _str_to_bool(val, optname)
+ elif optname == 'exclude':
+ options.exclude.append(val)
+ elif optname in ('exclude-parse', 'exclude_parse'):
+ options.exclude_parse.append(val)
+ elif optname in ('exclude-introspect', 'exclude_introspect'):
+ options.exclude_introspect.append(val)
elif optname == 'inheritance':
if val.lower() not in INHERITANCE_STYLES:
raise ValueError('"%s" expected one of: %s.' %
(optname, ', '.join(INHERITANCE_STYLES)))
options.inerhitance = val.lower()
- elif optname == 'docformat':
- options.docformat = val
+ elif optname =='private':
+ options.private = _str_to_bool(val, optname)
+ elif optname =='imports':
+ options.imports = _str_to_bool(val, optname)
+ elif optname == 'sourcecode':
+ options.include_source_code = _str_to_bool(val, optname)
+ elif optname in ('include-log', 'include_log'):
+ options.include_log = _str_to_bool(val, optname)
+
+ # Output options
+ elif optname == 'name':
+ options.prj_name = val
elif optname == 'css':
options.css = val
- elif optname == 'name':
- options.prj_name = val
elif optname == 'url':
options.prj_url = val
elif optname == 'link':
@@ -476,21 +544,10 @@
options.help_file = val
elif optname =='frames':
options.show_frames = _str_to_bool(val, optname)
- elif optname =='private':
- options.private = _str_to_bool(val, optname)
- elif optname =='imports':
- options.imports = _str_to_bool(val, optname)
- elif optname == 'verbosity':
- try:
- options.verbosity = int(val)
- except ValueError:
- raise ValueError('"%s" expected an int' % optname)
- elif optname == 'parse':
- options.parse = _str_to_bool(val, optname)
- elif optname == 'introspect':
- options.introspect = _str_to_bool(val, optname)
- elif optname == 'dotpath':
- options.dotpath = val
+ elif optname in ('separate-classes', 'separate_classes'):
+ options.list_classes_separately = _str_to_bool(val, optname)
+
+ # Graph options
elif optname == 'graph':
graphtypes = val.replace(',', '').split()
for graphtype in graphtypes:
@@ -498,18 +555,16 @@
raise ValueError('"%s" expected one of: all, %s.' %
(optname, ', '.join(GRAPH_TYPES)))
options.graphs.extend(graphtypes)
+ elif optname == 'dotpath':
+ options.dotpath = val
elif optname in ('graph-font', 'graph_font'):
options.graph_font = val
elif optname in ('graph-font-size', 'graph_font_size'):
- options.graph_font_size = int(val)
- elif optname in ('separate-classes', 'separate_classes'):
- options.list_classes_separately = _str_to_bool(val, optname)
- elif optname == 'sourcecode':
- options.include_source_code = _str_to_bool(val, optname)
+ options.graph_font_size = _str_to_int(val)
elif optname == 'pstat':
options.pstat_files.extend(val.replace(',', ' ').split())
- elif optname in ('simple-term', 'simple_term'):
- options.simple_term = _str_to_bool(val, optname)
+
+ # Return value options
elif optname in ('failon', 'fail-on', 'fail_on'):
if val.lower.strip() in ('error', 'errors'):
options.fail_on = log.ERROR
@@ -532,6 +587,12 @@
else:
raise ValueError('"%s" option expected a boolean' % optname)
+def _str_to_int(val, optname):
+ try:
+ return int(val)
+ except ValueError:
+ raise ValueError('"%s" option expected an int' % optname)
+
######################################################################
#{ Interface
######################################################################
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-18 12:34:10
|
Revision: 1529
http://svn.sourceforge.net/epydoc/?rev=1529&view=rev
Author: dvarrazzo
Date: 2007-02-18 04:34:08 -0800 (Sun, 18 Feb 2007)
Log Message:
-----------
- If there is no other info for a metadata variable, drop it as variable
- @newfield also add a metadata variable
- dropped __revision__ as alias for __version__. A new field can now be
defined.
Modified Paths:
--------------
trunk/epydoc/doc/fields.html
trunk/epydoc/src/epydoc/docstringparser.py
Modified: trunk/epydoc/doc/fields.html
===================================================================
--- trunk/epydoc/doc/fields.html 2007-02-18 11:20:10 UTC (rev 1528)
+++ trunk/epydoc/doc/fields.html 2007-02-18 12:34:08 UTC (rev 1529)
@@ -530,19 +530,20 @@
<p> Some module variables are commonly used as module metadata. Epydoc can
use the value provided by these variables as alternate form for tags. The
-following table lists the recognized variables and the tag they replace. </p>
+following table lists the recognized variables and the tag they replace.
+Customized metadata variables can be added using the method described
+in <a href="newfield">Adding New Fields</a>.</p>
<center>
<table border="1" cellspacing="0" cellpadding="3">
- <tr><th width="50%">Variable</th><th width="50%">Tag</th></tr>
+ <tr><th width="50%">Tag</th><th width="50%">Variable</th></tr>
<tr><td align="left" valign="top">
<b><code>@deprecated</code></b></td>
<td><code>__deprecated__</code></td></tr>
<tr><td align="left" valign="top">
<b><code>@version</code></b></td>
- <td><code>__version__</code><br/>
- <code>__revision__</code></td></tr>
+ <td><code>__version__</code></td></tr>
<tr><td align="left" valign="top">
<b><code>@date</code></b></td>
@@ -584,7 +585,12 @@
<p>Where <code><i>tag</i></code> is the new tag that's being defined;
<code><i>label</i></code> is a string that will be used to mark this
field in the generated output; and <code><i>plural</i></code> is the
-plural form of <code><i>label</i></code>, if different. The following
+plural form of <code><i>label</i></code>, if different.</p>
+
+<p>It will also be possibile to use the module variable
+<code>__<i>tag</i>__</code> to set the value for the newly defined tag.</p>
+
+<p>The following
example illustrates how the <code>@newfield</code> can be used: </p>
<table border="1" cellspacing="0" cellpadding="3" width="95%">
Modified: trunk/epydoc/src/epydoc/docstringparser.py
===================================================================
--- trunk/epydoc/src/epydoc/docstringparser.py 2007-02-18 11:20:10 UTC (rev 1528)
+++ trunk/epydoc/src/epydoc/docstringparser.py 2007-02-18 12:34:08 UTC (rev 1529)
@@ -72,7 +72,7 @@
"""
def __init__(self, tags, label, plural=None,
short=0, multivalue=1, takes_arg=0,
- varnames=[]):
+ varnames=None):
if type(tags) in (list, tuple):
self.tags = tuple(tags)
elif type(tags) is str:
@@ -84,7 +84,7 @@
self.multivalue = multivalue
self.short = short
self.takes_arg = takes_arg
- self.varnames = varnames
+ self.varnames = varnames or []
def __cmp__(self, other):
if not isinstance(other, DocstringField): return -1
@@ -109,7 +109,7 @@
# Status info
DocstringField(['version'], 'Version', multivalue=0,
- varnames=['__version__', '__revision__']),
+ varnames=['__version__']),
DocstringField(['date'], 'Date', multivalue=0,
varnames=['__date__']),
DocstringField(['status'], 'Status', multivalue=0),
@@ -274,8 +274,9 @@
for varname in field.varnames:
# Check if api_doc has a variable w/ the given name.
if varname not in api_doc.variables: continue
- if api_doc.variables[varname].value is UNKNOWN: continue
- val_doc = api_doc.variables[varname].value
+ var_doc = api_doc.variables[varname]
+ if var_doc.value is UNKNOWN: continue
+ val_doc = var_doc.value
value = []
# Try extracting the value from the pyval.
@@ -308,7 +309,11 @@
elt = unicode(elt)
elt = epytext.ParsedEpytextDocstring(
epytext.parse_as_para(elt))
+
+ # Add in the metadata and remove from the variables
api_doc.metadata.append( (field, varname, elt) )
+ if var_doc.docstring in (None, UNKNOWN):
+ del api_doc.variables[varname]
def initialize_api_doc(api_doc):
"""A helper function for L{parse_docstring()} that initializes
@@ -664,6 +669,7 @@
api_doc.extra_docstring_fields = []
try:
docstring_field = _descr_to_docstring_field(arg, descr)
+ docstring_field.varnames.append("__%s__" % arg)
api_doc.extra_docstring_fields.append(docstring_field)
except ValueError, e:
raise ValueError('Bad %s: %s' % (tag, e))
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-18 11:23:10
|
Revision: 1528
http://svn.sourceforge.net/epydoc/?rev=1528&view=rev
Author: dvarrazzo
Date: 2007-02-18 03:20:10 -0800 (Sun, 18 Feb 2007)
Log Message:
-----------
- Documented the fact that consolidated list don't require the term
being interpreted text
Modified Paths:
--------------
trunk/epydoc/doc/fields.html
Modified: trunk/epydoc/doc/fields.html
===================================================================
--- trunk/epydoc/doc/fields.html 2007-02-17 16:24:07 UTC (rev 1527)
+++ trunk/epydoc/doc/fields.html 2007-02-18 11:20:10 UTC (rev 1528)
@@ -665,7 +665,7 @@
href="http://docutils.sourceforge.net/docs/user/rst/quickref.html#inline-markup">interpreted
text</a>, 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, marked as interpreted text. The term
+contain the field's argument, (it is not mandatory for it being marked as interpreted text). 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
@@ -678,11 +678,11 @@
Return the maximum speed for a fox.
<code class="field">:Parameters:</code>
- `size`
+ size
The size of the fox (in meters)
- `weight` : float
+ weight : float
The weight of the fox (in stones)
- `age` : int
+ age : int
The age of the fox (in years)
"""</code>
<i>[...]</i>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-17 16:24:09
|
Revision: 1527
http://svn.sourceforge.net/epydoc/?rev=1527&view=rev
Author: dvarrazzo
Date: 2007-02-17 08:24:07 -0800 (Sat, 17 Feb 2007)
Log Message:
-----------
- Added documentation for 'permission' field.
Modified Paths:
--------------
trunk/epydoc/doc/fields.html
Modified: trunk/epydoc/doc/fields.html
===================================================================
--- trunk/epydoc/doc/fields.html 2007-02-17 04:30:49 UTC (rev 1526)
+++ trunk/epydoc/doc/fields.html 2007-02-17 16:24:07 UTC (rev 1527)
@@ -233,6 +233,12 @@
<code>@<b>change</b>:</code> ... </td><td>
A change log entry for this object.</td></tr>
+ <tr><td width="10%" align="left" valign="top">
+ <code>@<b>permission</b>:</code> ... </td><td>
+ The object access permission, for systems such Zope/Plone supporting
+ this concept. It may be used more than once to specify multiple
+ permissions.</td></tr>
+
<!-- ========== Formal Conditions ========== -->
<tr><th colspan="2" align="left">Formal Conditions</th></tr>
<tr><td width="10%" align="left" valign="top">
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-17 04:30:51
|
Revision: 1526
http://svn.sourceforge.net/epydoc/?rev=1526&view=rev
Author: dvarrazzo
Date: 2007-02-16 20:30:49 -0800 (Fri, 16 Feb 2007)
Log Message:
-----------
- Added variable docstring description (from the whatsnew).
- Added table for metadata variables.
- Added note about constructor parameters in class docstrings.
Modified Paths:
--------------
trunk/epydoc/doc/fields.html
trunk/epydoc/doc/othermarkup.html
Modified: trunk/epydoc/doc/fields.html
===================================================================
--- trunk/epydoc/doc/fields.html 2007-02-17 02:06:45 UTC (rev 1525)
+++ trunk/epydoc/doc/fields.html 2007-02-17 04:30:49 UTC (rev 1526)
@@ -33,34 +33,35 @@
<table border="1" cellspacing="0" cellpadding="3">
<tr>
<th width="33%">Epytext</th>
- <th width="33%">ReStructuredText</th>
+ <th width="33%">reStructuredText</th>
<th width="33%">Javadoc</th>
</tr>
<tr>
<td>
- <code>@<i>tag</i>: <i>body</i></code>...</br>
- <code>@<i>tag</i> <i>arg</i>: <i>body</i></code>...</br>
+ <code>@<i>tag</i>: <i>body</i></code>...<br/>
+ <code>@<i>tag</i> <i>arg</i>: <i>body</i></code>...<br/>
</td>
<td>
- <code>:<i>tag</i>: <i>body</i></code>...</br>
- <code>:<i>tag</i> <i>arg</i>: <i>body</i></code>...</br>
+ <code>:<i>tag</i>: <i>body</i></code>...<br/>
+ <code>:<i>tag</i> <i>arg</i>: <i>body</i></code>...<br/>
</td>
<td>
- <code>@<i>tag</i> <i>body</i></code>...</br>
- <code>@<i>tag</i> <i>arg</i> <i>body</i></code>...</br>
+ <code>@<i>tag</i> <i>body</i></code>...<br/>
+ <code>@<i>tag</i> <i>arg</i> <i>body</i></code>...<br/>
</td>
</tr>
<tr>
<td align="center"><a
href="epytext.html#fieldlist">Definition of<br/>epytext fields</a></td>
<td align="center"><a
-href="http://docutils.sourceforge.net/spec/rst/reStructuredText.html#field-lists">Definition of<br/>ReStructuredText fields</a></td>
+href="http://docutils.sourceforge.net/spec/rst/reStructuredText.html#field-lists">Definition of<br/>reStructuredText fields</a></td>
<td align="center"><a
href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html#javadoctags">Definition of<br/>Javadoc fields</a></td>
</tr>
</table>
</center>
+
<a name="fields"></a>
<h2> 2. Supported Fields</h2>
@@ -77,11 +78,12 @@
<tr><td width="10%" align="left" valign="top">
<code>@<b>param</b> <i>p</i>:</code> ... </td><td>
A description of the parameter <code><i>p</i></code> for a
- function or method. </td></tr>
+ function or method. It may appear in the class docstring to describe
+ a costructor parameter: mostly useful for C extensions.</td></tr>
<tr><td width="10%" align="left" valign="top">
<code>@<b>type</b> <i>p</i>:</code> ... </td><td>
- The expected type for the parameter
+ The expected type for the parameter.
<code><i>p</i></code>. </td></tr>
<tr><td width="10%" align="left" valign="top">
@@ -95,16 +97,19 @@
<tr><td width="10%" align="left" valign="top">
<code>@<b>keyword</b> <i>p</i>:</code> ... </td><td>
A description of the keyword parameter <code><i>p</i></code>.
- </td></tr>
+ It may appear in the class docstring to describe
+ a costructor keyword parameter.</td></tr>
<tr><td width="10%" align="left" valign="top">
<code>@<b>raise</b> <i>e</i>:</code> ... </td><td>
A description of the circumstances under which a function or
- method raises exception <code><i>e</i></code>. </td></tr>
+ method raises exception <code><i>e</i></code>.
+ It may appear in the class docstring to describe
+ an exception that can be raised by the costructor.</td></tr>
<!-- ========== Variables ========== -->
<tr><th colspan="2" align="left">Variables
- <i>(module or class docstrings)</i></th></tr>
+ <i>(module, class or <a href="#variable-docstring">variable</a> docstrings)</i></th></tr>
<tr><td width="10%" align="left" valign="top">
<code>@<b>ivar</b> <i>v</i>:</code> ... </td><td>
A description of the class instance variable
@@ -308,7 +313,7 @@
<code class="field">@keyword dig_deep:</code> Plant the seed deep under ground.
<code class="field">@keyword soak:</code> Soak the seed before planting it.
- """</code>
+ <code class="string">"""</code>
<i>[...]</i>
</pre></div>
</li>
@@ -323,7 +328,7 @@
<code class="field">@group Tools:</code> zip, zap, *_tool
<code class="field">@group Accessors:</code> get_*
<code class="field">@sort:</code> get_*, set_*, unpack_*, cut
- """</code>
+ <code class="string">"""</code>
<i>[...]</i>
</pre></div>
</li>
@@ -341,15 +346,90 @@
<code class="field">@type person:</code> L{Person} or L{Animal}
<code class="field">@param time:</code> How long they should think.
<code class="field">@type time:</code> C{int} or C{float}
- """</code>
+ <code class="string">"""</code>
<i>[...]</i>
</pre></div>
</li>
</ul>
-<h2>3. Field Synonyms</h2>
+<a name="locations"></a>
+<h2> 3. Where to Write Fields</h2>
+
+<p> Normally the fields are written in the docstring of the documented
+objects: this allows to add fields to modules, classes, function, properties.
+Where a docstring is not allowed, usually alternative options do exist.
+</p>
+
+<a name="variable-docstring"></a>
+<h3> 3.1. Variable docstrings </h3>
+
+<p> Python variables don't support docstrings. The variable can be described
+in the module or class where it is defined using the tags <code>@var</code>,
+<code>@ivar</code>, <code>@cvar</code>; but this only allows for a textual
+description: no further metadata can be added to the variable (except for the
+type, using the <code>@type</code> tag. </p>
+
+<p> Epydoc supports <i>variable docstrings</i>: if a variable
+assignment statement is immediately followed by a bare string literal,
+then that assignment is treated as a docstring for that variable. In
+classes, variable assignments at the class definition level are
+considered class variables; and assignments to instance variables in
+the constructor (<code>__init__</code>) are considered instance variables:<p>
+
+<div class="screen2"><pre>
+<code class="prompt">>>></code> <code class="keyword">class</code> A:
+<code class="prompt">...</code> x = 22
+<code class="prompt">...</code> <code class="string">"""Docstring for class variable A.x"""</code>
+<code class="prompt">...</code>
+<code class="prompt">...</code> <code class="keyword">def</code> <code class="function">__init__</code>(self, a):
+<code class="prompt">...</code> self.y = a
+<code class="prompt">...</code> <code class="string">"""Docstring for instance variable A.y</code>
+</pre></div>
+
+<p> Variables may also be documented using <i>comment docstrings</i>.
+If a variable assignment is immediately preceeded by a comment whose
+lines begin with the special marker "<code><b>#:</b></code>", or is
+followed on the same line by such a comment, then it is treated as a
+docstring for that variable: </p>
+
+<div class="screen2"><pre>
+<code class="prompt">>>></code> <code class="comment">#: docstring for x</code>
+<code class="prompt">...</code> x = 22
+<code class="prompt">>>></code> x = 22 <code class="comment">#: docstring for x</code>
+</pre></div>
+
+<p> A common Python idiom is to create instance variables settings their
+default value in the class instead of the constructor (hopefully if the default
+is immutable...). To avoid Epydoc to interpret such variable as a class
+variable, you can describe it using the tag <code>@ivar</code> in the
+context of a variable docstring:</p>
+
+<div class="screen2"><pre>
+<code class="prompt">>>></code> <code class="keyword">class</code> B:
+<code class="prompt">...</code> y = 42
+<code class="prompt">...</code> <code class="string">"""@ivar: This is an instance variable."""</code>
+</pre></div>
+
+<p> Notice that variable docstrings are only available for documentation
+when the source code is available for parsing: it is not possible to retrieve
+variable docstrings from introspection informations only. </p>
+
+
+<h3> 3.2. C Extensions </h3>
+
+<p> In a C extension module, extension classes cannot have a docstring attached
+to the <code>__init__</code> function; consequently it is not possible to
+document parameters and exceptions raised by the class constructor. To overcome
+this shortcoming, the tags <code>@param</code>, <code>@keyword</code>,
+<code>@type</code>, <code>@exception</code> are allowed to appear in the class
+docstring to refer to constructor parameters.
+</p>
+
+
+<h2>4. Field Synonyms</h2>
+
<p> Several fields have "synonyms," or alternate tags. The following
table lists all field synonyms. Field tags are written using epytext
markup; if you are using a different markup language, then you should
@@ -362,8 +442,8 @@
<tr><th width="50%">Name</th><th width="50%">Synonyms</th></tr>
<tr><td align="left" valign="top">
<b><code>@param <i>p</i>:</code> ...</b> </td>
- <td><code>@parameter <i>p</i>:</code> ...</br>
- <code>@arg <i>p</i>:</code> ...</br>
+ <td><code>@parameter <i>p</i>:</code> ...<br/>
+ <code>@arg <i>p</i>:</code> ...<br/>
<code>@argument <i>p</i>:</code> ...</td></tr>
<tr><td align="left" valign="top">
@@ -376,8 +456,8 @@
<tr><td align="left" valign="top">
<b><code>@raise <i>e</i>:</code> ...</b> </td>
- <td><code>@raises <i>e</i>:</code> ...</br>
- <code>@except <i>e</i>:</code> ...</br>
+ <td><code>@raises <i>e</i>:</code> ...<br/>
+ <code>@except <i>e</i>:</code> ...<br/>
<code>@exception <i>e</i>:</code> ...</td></tr>
<tr><td align="left" valign="top">
@@ -412,7 +492,7 @@
<tr><td align="left" valign="top">
<b><code>@requires:</code> ...</b> </td><td>
- <code>@require:</code> ... </br>
+ <code>@require:</code> ... <br/>
<code>@requirement:</code> ... </td></tr>
<tr><td align="left" valign="top">
@@ -438,9 +518,55 @@
</td></tr></table>
</center>
-<a name="newfield">
-<h2> 4. Adding New Fields</h2></a>
+<a name="metadata-variable"></a>
+<h3> 4.1. Metadata variables </h3>
+
+<p> Some module variables are commonly used as module metadata. Epydoc can
+use the value provided by these variables as alternate form for tags. The
+following table lists the recognized variables and the tag they replace. </p>
+
+<center>
+ <table border="1" cellspacing="0" cellpadding="3">
+ <tr><th width="50%">Variable</th><th width="50%">Tag</th></tr>
+ <tr><td align="left" valign="top">
+ <b><code>@deprecated</code></b></td>
+ <td><code>__deprecated__</code></td></tr>
+
+ <tr><td align="left" valign="top">
+ <b><code>@version</code></b></td>
+ <td><code>__version__</code><br/>
+ <code>__revision__</code></td></tr>
+
+ <tr><td align="left" valign="top">
+ <b><code>@date</code></b></td>
+ <td><code>__date__</code></td></tr>
+
+ <tr><td align="left" valign="top">
+ <b><code>@author</code></b><br/>
+ <b><code>@authors</code></b></td>
+ <td><code>__author__</code><br/>
+ <code>__authors__</code></td></tr>
+
+ <tr><td align="left" valign="top">
+ <b><code>@contact</code></b></td>
+ <td><code>__contact__</code></td></tr>
+
+ <tr><td align="left" valign="top">
+ <b><code>@copyright</code></b></td>
+ <td><code>__copyright__</code></td></tr>
+
+ <tr><td align="left" valign="top">
+ <b><code>@license</code></b></td>
+ <td><code>__license__</code></td></tr>
+
+ </table>
+</center>
+
+
+<a name="newfield"></a>
+<h2> 5. Adding New Fields</h2>
+
<p> New fields can be defined for the docstrings in a module using the
special <code>@newfield</code> tag (or its synonym,
<code>@deffield</code>). This tag has the following syntax:</p>
@@ -464,10 +590,10 @@
"""
<code class="keyword">def</code> <code class="function">example</code>():
- <code class="string">"""
+ <code class="string">"""</code>
<code class="field">@corpus:</code> Bob's wordlist.
<code class="field">@corpus:</code> The British National Corpus.
- """</code>
+ <code class="string">"""</code>
<i>[...]</i>
</pre>
</td><td>
@@ -484,7 +610,7 @@
<code>__extra_epydoc_fields__</code> is deprecated; use
<code>@newfield</code> instead.</p>
-<h2> 5. Markup-Specific Notes </h2>
+<h2> 6. Markup-Specific Notes </h2>
<p> For the most part, fields are treated identically, regardless of
what markup language is used to encode them. However, there are a few
@@ -492,7 +618,7 @@
for each markup language. In particular: </p>
<ul>
- <li> ReStructuredText supports an extra group of fields, called
+ <li> reStructuredText supports an extra group of fields, called
<i>consolidated fields</i>, which combine the documentation for
several objects into a single field. </li>
<li> Javadoc uses a special syntax for the body of the
@@ -504,9 +630,9 @@
below. </p>
<a name="rst"></a>
-<h3> 5.1. ReStructuredText Fields </h3>
+<h3> 6.1. reStructuredText Fields </h3>
-<p> In ReStructuredText, a single field can be used to encode the
+<p> In reStructuredText, a single field can be used to encode the
documentation for a group of related items. For example, a single
<code>:Parameters:</code> field is often used to describe all of the
parameters for a function or method: </p>
@@ -592,7 +718,7 @@
</center>
-<h3> 5.2. Javadoc Fields </h3>
+<h3> 6.2. Javadoc Fields </h3>
<p> For compatibility with Javadoc, every <code>@see</code> field is
assumed to contain a single crossreference link, unless its body
Modified: trunk/epydoc/doc/othermarkup.html
===================================================================
--- trunk/epydoc/doc/othermarkup.html 2007-02-17 02:06:45 UTC (rev 1525)
+++ trunk/epydoc/doc/othermarkup.html 2007-02-17 04:30:49 UTC (rev 1526)
@@ -16,7 +16,7 @@
<ul>
<li><b><a href="http://docutils.sourceforge.net/rst.html"
- >ReStructuredText</a></b> is an "easy-to-read,
+ >reStructuredText</a></b> 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
@@ -59,23 +59,23 @@
</pre></div>
<a name="restructuredtext">
-<h2>ReStructuredText</h2></a>
+<h2>reStructuredText</h2></a>
-<p> ReStructuredText is a markup language that was developed in
+<p> reStructuredText is a markup language that was developed in
conjunction with <a
href="http://docutils.sourceforge.net">Docutils</a>. In order to
-parse ReStructuredText docstrings, Docutils 0.3 or higher must be
-installed. If Docutils is not installed, then ReStructuredText
+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 <a
href="http://sourceforge.net/project/showfiles.php?group_id=38414">Docutils
SourceForge page</a>. </p>
<p> In addition to the <a href="fields.html#fields">standard set of
-fields</a>, the ReStructruedText parser also supports
+fields</a>, the reStructruedText parser also supports
<i>consolidated</i> fields, which combine the documentation for
several objects into a single field. For more information, see the
-markup-specific notes for <a href="fields.html#rst">ReStructuredText
+markup-specific notes for <a href="fields.html#rst">reStructuredText
fields</a>. </p>
<p> The epydoc reStructuredText reader also defines several custom <a
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-17 02:06:46
|
Revision: 1525
http://svn.sourceforge.net/epydoc/?rev=1525&view=rev
Author: dvarrazzo
Date: 2007-02-16 18:06:45 -0800 (Fri, 16 Feb 2007)
Log Message:
-----------
- Fixed reST URL.
Modified Paths:
--------------
trunk/epydoc/doc/index.html
Modified: trunk/epydoc/doc/index.html
===================================================================
--- trunk/epydoc/doc/index.html 2007-02-17 01:25:11 UTC (rev 1524)
+++ trunk/epydoc/doc/index.html 2007-02-17 02:06:45 UTC (rev 1525)
@@ -23,7 +23,7 @@
href="epytextintro.html">epytext</a> can be used to format docstrings, and
to add information about specific fields, such as parameters and
instance variables. Epydoc also understands docstrings written in
-<a href="http://docutils.sourceforge.net/docs/">reStructuredText</a>,
+<a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>,
Javadoc, and plaintext. For a more extensive example
of epydoc's output, see the API documentation for <a
href="http://epydoc.sourceforge.net/stdlib/">Python 2.4</a>. </p>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-17 01:25:18
|
Revision: 1524
http://svn.sourceforge.net/epydoc/?rev=1524&view=rev
Author: dvarrazzo
Date: 2007-02-16 17:25:11 -0800 (Fri, 16 Feb 2007)
Log Message:
-----------
- Added new features.
- There's a beta, there's a february...
Modified Paths:
--------------
trunk/epydoc/doc/whatsnew.html
Modified: trunk/epydoc/doc/whatsnew.html
===================================================================
--- trunk/epydoc/doc/whatsnew.html 2007-02-17 01:23:43 UTC (rev 1523)
+++ trunk/epydoc/doc/whatsnew.html 2007-02-17 01:25:11 UTC (rev 1524)
@@ -4,15 +4,14 @@
<link rel="stylesheet" href="epydoc.css" type="text/css"/>
</head>
<!-- $Id: faq.html 602 2003-09-07 23:49:56Z edloper $ -->
-<body>
<body>
<div class="body">
<h1> What's New in Epydoc </h1>
<div class="box">
-<h2 class="box-title">Epydoc 3.0 (alpha)</h2></td>
-<center><i>Alpha 3 released August 24, 2006</i></center>
+<h2 class="box-title">Epydoc 3.0 (beta)</h2>
+<center><i>Beta 1 released February, 2007</i></center>
<h3>Support for Parsing & Introspection</h3>
@@ -21,7 +20,7 @@
contents. Epydoc 3.0 still supports introspection, but is also
capable of extracting information about python modules by parsing
their source code. Furthermore, the new version of epydoc can combine
-these two sources of information (introspection & parsing). This is
+these two sources of information (introspection & parsing). This is
important because each source has its own advantages and disadvantages
with respect to the other. See the <a
href="faq.html#introspect_vs_parse">FAQ</a> for more information about
@@ -49,7 +48,7 @@
<p>Variables may also be documented using <i>comment docstrings</i>.
If a variable assignment is immediately preceeded by a comment whose
-lines begin with the specail marker "<code><b>#:</b></code>", or is
+lines begin with the special marker "<code><b>#:</b></code>", or is
followed on the same line by such a comment, then it is treated as a
docstring for that variable: </p>
@@ -59,7 +58,7 @@
<code class="prompt">>>></code> x = 22 <code class="comment">#: docstring for x</code>
</pre></div>
-<h3> Graphs & Diagrams </h3>
+<h3> Graphs & Diagrams </h3>
<p>Epydoc can automatically generate a variety of graphs, including
class tress, package trees, uml class graphs, and import graphs.
@@ -88,10 +87,15 @@
with epydoc. </a>.</li>
</ul>
+ <p> Epydoc can also generate <i>function call graphs</i>, showing the callers
+ and the callees for each function. To generate call graphs, Epydoc uses
+ data produced by a <a href="http://docs.python.org/lib/profile.html">Python
+ profiler</a> such <code>Profile</code> or <code>hotshot</code>. </p>
+
<p> For some examples of automatically generated graphs, see the <a
href="api/">API Documentation</a> for epydoc (including the page
for the <a href="api/epydoc.docwriter.dotgraph-module.html"
- ><code>epydoc.docwriter.dotgraph</code> module</a>. </p>
+ ><code>epydoc.docwriter.dotgraph</code> module</a>). </p>
<p> Graph generation requires the <a
href="http://www.graphviz.org/">Graphviz package</a>
@@ -113,7 +117,9 @@
listed, but no longer described in detail. E.g., if "object" is
used as a base class, then the methods inherited from "object" will
be listed at the bottom of the method summary table, but not
- described in detail.</li>
+ described in detail. Furthermore methods and variables not very detailed
+ (with at most a short docstring) are only shown in the summary, while
+ most detailed items also appear in a full detailed box. </li>
<li> The HTML output no longer contains separate pages for including
and excluding private variables. Instead, it uses CSS to
@@ -121,6 +127,15 @@
record the user's preference. (By default, private variables are
hidden.) </li>
+ <li> Additional pages are created, listing identifiers, documented
+ definitions, bugs and to-do items. An optional log page can also be
+ generated, reporting all the errors and warning raised during documentation
+ generation. </li>
+
+ <li> Improved variable values representation, using the parsed values if
+ the standard representation is not informative (such as <code><Foo
+ instance at ...></code>). Syntax highlight is used for values too,
+ including colorization for regular expressions. </li>
</ul>
<h3>Improved Documentation Extraction</h3>
@@ -128,8 +143,15 @@
<ul>
<li> Proper support for nested classes.</li>
<li> Full unicode support, including support for the <a href="http://www.python.org/peps/pep-0263.html">encoding directive</a>.</li>
+ <li> Variables conventionally used for modules metadata such as
+ <code>__version__</code> are recognized as modules fields.</li>
+ <li>The <code>__all__</code> attribute is used to decide whether objects
+ are public or private. If an object is listed in an <code>__all__</code>
+ list, it will appear defined in that module even if imported from elsewhere,
+ keeping the API safe from implementation changes.</li>
<li> Increased robustness in the face of a variety of "magic"
manipulations of namespaces.</li>
+ <li>Parsing or introspection can be prevented for problematic modules.</li>
</ul>
</div>
@@ -204,24 +226,25 @@
<li> Added --ignore-param-mismatch option, which supresses warnings about parameter mismatches </li>
<li> Fixed bug in path magic for epydoc.py and epydoc.pyw scripts </li>
<li> Replaced __epydoc_sort__ with @sort </li>
- <li> Changes to epytext:</li>
+ <li> Changes to epytext:
<ul>
<li> Epytext now supports symbols (S{...}) </li>
<li> Epydoc allows multi-word values for field arguments (eg for group names) </li>
<li> Fixeded several minor bugs</li>
- </ul>
- <li> --show-imports now lists imported vars & modules </li>
+ </ul>
+ </li>
+ <li> --show-imports now lists imported vars & modules </li>
<li> Improvements to error reporting </li>
<li> Improved sorting </li>
<li> Many bug fixes </li>
<li> General code clean-up </li>
<li> Added preliminary and partial implementation for man-style output (like pydoc) </li>
<li> Changed the definition of the --navlink parameter, to allow for more flexible encoding of the homepage link. </li>
- <li> Improvements to HTML output. </li>
+ <li> Improvements to HTML output.
<ul>
<li> Display variable values in variable summary table </li>
<li> Added tooltips for variable values, that show a more complete value (up to 600 characters) </li>
- <li> Minor tweaks & improvements </li>
+ <li> Minor tweaks & improvements </li>
<li> In the table of contents, only list objects from modules that were explicitly documented (don't list base classes from imported modules, etc)</li>
</ul>
</li>
@@ -230,7 +253,7 @@
<div class="box"><h2 class="box-title">Older Releases</h2>
<p>See the <a
-href="http://sourceforge.net/project/showfiles.php?group_id=32455&package_id=24617">Release
+href="http://sourceforge.net/project/showfiles.php?group_id=32455&package_id=24617">Release
Notes</a> on SourceForge.</p>
</div>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-17 01:23:46
|
Revision: 1523
http://svn.sourceforge.net/epydoc/?rev=1523&view=rev
Author: dvarrazzo
Date: 2007-02-16 17:23:43 -0800 (Fri, 16 Feb 2007)
Log Message:
-----------
- Added Docutils url
- Fixed reST capitalization
Modified Paths:
--------------
trunk/epydoc/doc/index.html
Modified: trunk/epydoc/doc/index.html
===================================================================
--- trunk/epydoc/doc/index.html 2007-02-16 23:22:33 UTC (rev 1522)
+++ trunk/epydoc/doc/index.html 2007-02-17 01:23:43 UTC (rev 1523)
@@ -23,7 +23,8 @@
href="epytextintro.html">epytext</a> can be used to format docstrings, and
to add information about specific fields, such as parameters and
instance variables. Epydoc also understands docstrings written in
-ReStructuredText, Javadoc, and plaintext. For a more extensive example
+<a href="http://docutils.sourceforge.net/docs/">reStructuredText</a>,
+Javadoc, and plaintext. For a more extensive example
of epydoc's output, see the API documentation for <a
href="http://epydoc.sourceforge.net/stdlib/">Python 2.4</a>. </p>
</div>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-16 23:23:09
|
Revision: 1522
http://svn.sourceforge.net/epydoc/?rev=1522&view=rev
Author: dvarrazzo
Date: 2007-02-16 15:22:33 -0800 (Fri, 16 Feb 2007)
Log Message:
-----------
- All the markup error solved.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/markup/doctest.py
trunk/epydoc/src/epydoc/markup/pyval_repr.py
trunk/epydoc/src/epydoc/markup/restructuredtext.py
Modified: trunk/epydoc/src/epydoc/markup/doctest.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/doctest.py 2007-02-16 17:38:35 UTC (rev 1521)
+++ trunk/epydoc/src/epydoc/markup/doctest.py 2007-02-16 23:22:33 UTC (rev 1522)
@@ -10,7 +10,7 @@
Syntax highlighting for doctest blocks. This module defines two
functions, L{doctest_to_html()} and L{doctest_to_latex()}, which can
be used to perform syntax highlighting on doctest blocks. It also
-defines the more general L{colorize_doctest()}, which could be used to
+defines the more general C{colorize_doctest()}, which could be used to
do syntac highlighting on doctest blocks with other output formats.
(Both C{doctest_to_html()} and C{doctest_to_latex()} are defined using
C{colorize_doctest()}.)
Modified: trunk/epydoc/src/epydoc/markup/pyval_repr.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/pyval_repr.py 2007-02-16 17:38:35 UTC (rev 1521)
+++ trunk/epydoc/src/epydoc/markup/pyval_repr.py 2007-02-16 23:22:33 UTC (rev 1522)
@@ -61,6 +61,8 @@
self.charpos = 0
self.lineno = 1
self.linebreakok = True
+
+ #: How good this represention is?
self.score = 0
def mark(self):
Modified: trunk/epydoc/src/epydoc/markup/restructuredtext.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/restructuredtext.py 2007-02-16 17:38:35 UTC (rev 1521)
+++ trunk/epydoc/src/epydoc/markup/restructuredtext.py 2007-02-16 23:22:33 UTC (rev 1522)
@@ -14,12 +14,13 @@
defined by L{ParsedDocstring}.
L{ParsedRstDocstring} is basically just a L{ParsedDocstring} wrapper
-for the L{docutils.nodes.document} class.
+for the C{docutils.nodes.document} class.
Creating C{ParsedRstDocstring}s
===============================
+
C{ParsedRstDocstring}s are created by the C{parse_document} function,
-using the L{docutils.core.publish_string()} method, with the following
+using the C{docutils.core.publish_string()} method, with the following
helpers:
- An L{_EpydocReader} is used to capture all error messages as it
@@ -27,7 +28,7 @@
- A L{_DocumentPseudoWriter} is used to extract the document itself,
without actually writing any output. The document is saved for
further processing. The settings for the writer are copied from
- L{docutils.writers.html4css1.Writer}, since those settings will
+ C{docutils.writers.html4css1.Writer}, since those settings will
be used when we actually write the docstring to html.
Using C{ParsedRstDocstring}s
@@ -147,11 +148,11 @@
@ivar _document: A ReStructuredText document, encoding the
docstring.
- @type _document: L{docutils.nodes.document}
+ @type _document: C{docutils.nodes.document}
"""
def __init__(self, document):
"""
- @type document: L{docutils.nodes.document}
+ @type document: C{docutils.nodes.document}
"""
self._document = document
@@ -261,7 +262,7 @@
recently processed document is available as the instance variable
C{document}
- @type document: L{docutils.nodes.document}
+ @type document: C{docutils.nodes.document}
@ivar document: The most recently processed document.
"""
def __init__(self):
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-16 17:38:38
|
Revision: 1521
http://svn.sourceforge.net/epydoc/?rev=1521&view=rev
Author: edloper
Date: 2007-02-16 09:38:35 -0800 (Fri, 16 Feb 2007)
Log Message:
-----------
- Fixed bug that was causing an extra blank line to get inserted
before ">>>" prompts in syntax-highlighted docstrings.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/markup/doctest.py
Modified: trunk/epydoc/src/epydoc/markup/doctest.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/doctest.py 2007-02-16 07:24:19 UTC (rev 1520)
+++ trunk/epydoc/src/epydoc/markup/doctest.py 2007-02-16 17:38:35 UTC (rev 1521)
@@ -197,11 +197,11 @@
# Example output:
if want:
if self.EXCEPT_RE.match(want):
- output += [self.markup(line, 'except')+'\n'
- for line in want.split('\n')]
+ output += '\n'.join([self.markup(line, 'except')
+ for line in want.split('\n')])
else:
- output += [self.markup(line, 'output')+'\n'
- for line in want.split('\n')]
+ output += '\n'.join([self.markup(line, 'output')
+ for line in want.split('\n')])
# Update charno
charno = m.end()
# Add any remaining post-example text.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-16 07:24:20
|
Revision: 1520
http://svn.sourceforge.net/epydoc/?rev=1520&view=rev
Author: edloper
Date: 2007-02-15 23:24:19 -0800 (Thu, 15 Feb 2007)
Log Message:
-----------
- Added pointers to new doctest files.
Modified Paths:
--------------
trunk/epydoc/doc/doctest/index.html
Modified: trunk/epydoc/doc/doctest/index.html
===================================================================
--- trunk/epydoc/doc/doctest/index.html 2007-02-16 07:24:02 UTC (rev 1519)
+++ trunk/epydoc/doc/doctest/index.html 2007-02-16 07:24:19 UTC (rev 1520)
@@ -33,8 +33,21 @@
<li> <a href="encoding.html">Unicode & Encodings</a> --
Tests for the processing of Python files that use non-ascii
encodings. </li>
- <li> <a href="epytext.html">Epytext</a> -- The default
+ <li> <a href="epytext.html">Epytext</a> -- Tests for epytext, the default
markup language used by epydoc.</li>
+ <li> <a href="javadoc.html">Javadoc</a> -- Tests for epydoc's support
+ of the Javadoc markup language.</li>
+ <li> <a href="plaintext.html">Plaintext</a> -- Tests for epydoc's support
+ of plaintext markup.</li>
+ <li> <a href="restructuredtext.html">reStructuredText</a> -- Tests
+ for epydoc's support of the reStructuredText markup language.</li>
+ <li> <a href="pyval_repr.html">Value Representations</a> -- Tests
+ for epydoc's formatting & syntax highlighting of variable's
+ values.</li>
+ <li> <a href="zope2.html">Zope 2</a> -- Tests for epydoc's support
+ for Zope 2.</li>
+ <li> <a href="zope3.html">Zope 3</a> -- Tests for epydoc's support
+ for Zope 3.</li>
</ul>
</div>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-16 07:24:06
|
Revision: 1519
http://svn.sourceforge.net/epydoc/?rev=1519&view=rev
Author: edloper
Date: 2007-02-15 23:24:02 -0800 (Thu, 15 Feb 2007)
Log Message:
-----------
- added 2 new faq entries (#url and #redirect)
Modified Paths:
--------------
trunk/epydoc/doc/faq.html
Modified: trunk/epydoc/doc/faq.html
===================================================================
--- trunk/epydoc/doc/faq.html 2007-02-16 07:23:36 UTC (rev 1518)
+++ trunk/epydoc/doc/faq.html 2007-02-16 07:24:02 UTC (rev 1519)
@@ -30,6 +30,8 @@
</a></li>
<li><a href="#is_epydoc_running">How can I test whether
epydoc is currently running?</a></li>
+ <li><a href="#speed">I'm documenting a large project. How can I make
+ epydoc go faster?</a></li>
</ul></p>
<p><b>Generated Output</b>
<ul class="nomargin">
@@ -41,13 +43,17 @@
generated documentation?</a></li>
<li><a href="#graphs">How can I include graphs in the generated output?
</a></li>
+ <li><a href="#urls">Why does epydoc add "<tt>-module</tt>" and
+ "<tt>-class</tt>" to the names of the HTML pages it generates?
+ </a></li>
+ <li><a href="#redirect">Is there a way to link to the API documentation
+ for objects using a simple URL based on the object's dotted name?
+ </a></li>
</ul></p>
<p><b>Development of Epydoc</b>
<ul class="nomargin">
<li><a href="#bug">I've found a bug in epydoc! Where should I report it?</a></li>
<li><a href="#help">I'd like to help! What can I do?</a></li>
- <li><a href="#speed">I'm documenting a large project. How can I make
- epydoc go faster?</a></li>
<!-- <li><a href="#"></a></li>-->
</ul></p>
<p><b><a href="mailto:ed...@gr...">Ask a new question...</a></b></p>
@@ -82,7 +88,7 @@
<dd><p>For many modules, <a href="epytextintro.html">epytext</a>
works well: it is very lightweight, so it won't get in the way; but
it lets you mark important information about objects. If you would
- like to use a more expressive markup language, then I recommend
+ like to use a more expressive markup language, then we recommend
using <a href="othermarkup.html">reStructuredText</a>, which is
easy to write, easy to read, and has support for a very wide array
of constructs.</p></dd>
@@ -197,6 +203,39 @@
</pre></div>
</dd>
+ <!-- QUESTION --><a name="speed" />
+ <dt><p><b>Q:</b> I'm documenting a large project. How can I make
+ epydoc go faster? </p></dt>
+ <dd><p>Try the following options: </p>
+ <table border="1" cellspacing="0" cellpadding="3">
+
+ <tr>
+ <th align="left"><code>−−no-sourcecode</code></th>
+ <td>Don't generate pages containing source code with syntax
+ highlighting.</td></tr>
+
+ <tr>
+ <th align="left"><code>−−no−private</code></th>
+ <td> Don't generate documentation for private objects.</td></tr>
+
+ <tr>
+ <th align="left"><code>−−introspect−only</code> or
+ <code>−−parse−only</code></th>
+ <td> Extract information about objects using introspection
+ <i>or</i> parsing (but not both). This may decrease the amount
+ of information that epydoc can extract from your
+ project.</td></tr>
+
+ <tr>
+ <th align="left"><code>−−docformat=plaintext</code></th>
+ <td> Format docstrings as plaintext, instead of epytext.
+ (Docstrings will be rendered verbatim).</td></tr>
+
+ </table>
+
+ <p>Also, note that including graphs in the output can
+ slow epydoc down significantly. </p></dd></dl>
+
</dl>
<!-- ==================== GENERATED OUTPUT ========================= -->
@@ -272,6 +311,38 @@
href="fields.html">fields</a> for
more information. </p></dd>
+ <!-- QUESTION --><a name="urls" />
+ <dt><p><b>Q:</b> Why does epydoc add "<tt>-module</tt>" and
+ "<tt>-class</tt>" to the names of the HTML pages it generates?
+ </p></dt>
+ <dd><p>There are two reasons. First, this ensures that the names of
+ module and class pages do not conflict with the names of existing
+ special pages. For example, if a module were named
+ "<tt>index</tt>", then naming its documentation page
+ "<tt>index.html</tt>" would interfere with the use of that name for
+ the documentation's main page. Second, it is possible to define a
+ package where a module and a class share the same name. In those
+ cases, this naming scheme ensures that the two object's pages do not
+ conflict.</p></dd>
+
+ <!-- QUESTION --><a name="redirect" />
+ <dt><p><b>Q:</b> Is there a way to link to the API documentation
+ for objects using a simple URL based on the object's dotted name?
+ </p></dt>
+
+ <dd><p>Epydoc creates a page named "<tt>redirect.html</tt>" that
+ uses javascript to automatically convert dotted names to the
+ corresponding URLs. In particular, loading the page
+ "<tt>redirect.html#<i>dotted.name</i></tt>" will automatically
+ redirect the user's browser to the URL for the object whose dotted
+ name is <tt><i>dotted.name</i></tt>. For example, a link to
+ <tt><<a href="api/redirect.html#epydoc.cli.HELP_TOPICS"
+ >redirect.html#epydoc.cli.HELP_TOPICS</a>></tt> automatically
+ redirects the browser to <tt><<a
+ href="api/epydoc.cli-module.html#HELP_TOPICS"
+ >epydoc.cli-module.html#HELP_TOPICS</a>></tt>. The redirect page can
+ be used for any object documented by epydoc, including modules,
+ classes, functions, varaibles, properties, etc. </p></dd>
</dl>
<!-- ==================== DEVELOPMENT ========================= -->
@@ -282,7 +353,7 @@
</p></dt>
<dd><p> Use the <a
href="http://sourceforge.net/tracker/?func=add&group_id=32455&atid=405618">Sourceforge
- bug tracker</a> to report bugs. If you want to hear back when I fix
+ bug tracker</a> to report bugs. If you want to hear back when we fix
it, be sure to either log in to Sourceforge, or include your email
address in the bug report.
</p></dd>
@@ -290,14 +361,14 @@
<dt><p><b>Q:</b> I'd like to help! What can I do?
</p></dt>
<dd><p> If there are any features that you want to add to Epydoc,
- I'd be happy to accept patches. Patches should be submitted with
+ we'd be happy to accept patches. Patches should be submitted with
the <a
href="http://sourceforge.net/tracker/?func=add&group_id=32455&atid=405620">Sourceforge
patch tracker</a> (be sure to describe what your patch does!). If
- you plan to make several changes, I could also add you as a
+ you plan to make several changes, we could also add you as a
developer on Sourceforge. Email me if you're interested. </p>
- <p> For a list of additions that I'd like to make to Epydoc, see
+ <p> For a list of additions that we'd like to make to Epydoc, see
the todo list in the <a href="api/">Epydoc reference
documentation</a>; or the SourceForge <a
href="http://sourceforge.net/tracker/?group_id=32455&atid=405621">feature
@@ -305,39 +376,6 @@
href="http://sourceforge.net/tracker/?group_id=32455&atid=405618">bug
tracker</a> </p></dd>
- <!-- QUESTION --><a name="speed" />
- <dt><p><b>Q:</b> I'm documenting a large project. How can I make
- epydoc go faster? </p></dt>
- <dd><p>Try the following options: </p>
- <table border="1" cellspacing="0" cellpadding="3">
-
- <tr>
- <th align="left"><code>−−no-sourcecode</code></th>
- <td>Don't generate pages containing source code with syntax
- highlighting.</td></tr>
-
- <tr>
- <th align="left"><code>−−no−private</code></th>
- <td> Don't generate documentation for private objects.</td></tr>
-
- <tr>
- <th align="left"><code>−−introspect−only</code> or
- <code>−−parse−only</code></th>
- <td> Extract information about objects using introspection
- <i>or</i> parsing (but not both). This may decrease the amount
- of information that epydoc can extract from your
- project.</td></tr>
-
- <tr>
- <th align="left"><code>−−docformat=plaintext</code></th>
- <td> Format docstrings as plaintext, instead of epytext.
- (Docstrings will be rendered verbatim).</td></tr>
-
- </table>
-
- <p>Also, note that including graphs in the output can
- slow epydoc down significantly. </p></dd></dl>
-
<!-- QUESTION TEMPLATE
<dt><p><b>Q: </b> ...</p></dt>
<dd><p> ... </p></dd> -->
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-16 07:23:37
|
Revision: 1518
http://svn.sourceforge.net/epydoc/?rev=1518&view=rev
Author: edloper
Date: 2007-02-15 23:23:36 -0800 (Thu, 15 Feb 2007)
Log Message:
-----------
- minor HTML change: in epydoc-log.html options table, use valign=top
Modified Paths:
--------------
trunk/epydoc/src/epydoc/cli.py
Modified: trunk/epydoc/src/epydoc/cli.py
===================================================================
--- trunk/epydoc/src/epydoc/cli.py 2007-02-16 06:13:56 UTC (rev 1517)
+++ trunk/epydoc/src/epydoc/cli.py 2007-02-16 07:23:36 UTC (rev 1518)
@@ -1289,8 +1289,9 @@
for (key, val) in opts]
for is_default, key, val in sorted(opts):
css = is_default and 'opt-default' or 'opt-changed'
- msg += ('<tr class="%s"><td>%s</td><td><tt> = '
- '</tt></td><td><tt>%s</tt></td></tr>' %
+ msg += ('<tr valign="top" class="%s"><td valign="top">%s</td>'
+ '<td valign="top"><tt> = </tt></td>'
+ '<td valign="top"><tt>%s</tt></td></tr>' %
(css, key, plaintext_to_html(repr(val))))
msg += '</table>\n'
self.out.write('<div class="log-info">\n%s</div>\n' % msg)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-16 06:14:00
|
Revision: 1517
http://svn.sourceforge.net/epydoc/?rev=1517&view=rev
Author: edloper
Date: 2007-02-15 22:13:56 -0800 (Thu, 15 Feb 2007)
Log Message:
-----------
- Fixed css bug that caused incorrect results in IE: "if you want
consistent rendering of lists between Explorer 5.x and Netscape 6.x,
you need to set both the left margin and left padding of the UL
element." -- <http://meyerweb.com/eric/css/list-indent.html>
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docwriter/html_css.py
Modified: trunk/epydoc/src/epydoc/docwriter/html_css.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/html_css.py 2007-02-16 05:37:14 UTC (rev 1516)
+++ trunk/epydoc/src/epydoc/docwriter/html_css.py 2007-02-16 06:13:56 UTC (rev 1517)
@@ -154,7 +154,7 @@
/* Fields */
dl.fields { margin-left: 2em; margin-top: 1em;
margin-bottom: 1em; }
-dl.fields dd ul { margin-left: -2em; }
+dl.fields dd ul { margin-left: 0em; padding-left: 0em; }
div.fields { margin-left: 2em; }
div.fields p { margin-bottom: 0.5em; }
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-16 05:37:16
|
Revision: 1516
http://svn.sourceforge.net/epydoc/?rev=1516&view=rev
Author: edloper
Date: 2007-02-15 21:37:14 -0800 (Thu, 15 Feb 2007)
Log Message:
-----------
- Updated the epydoc man page
Modified Paths:
--------------
trunk/epydoc/man/epydoc.1
Modified: trunk/epydoc/man/epydoc.1
===================================================================
--- trunk/epydoc/man/epydoc.1 2007-02-16 05:36:58 UTC (rev 1515)
+++ trunk/epydoc/man/epydoc.1 2007-02-16 05:37:14 UTC (rev 1516)
@@ -9,56 +9,11 @@
.SH SYNOPSIS
.HP 7
.B epydoc
-.RB [ \-\-html " | " \-\-latex " | " \-\-dvi " | " \-\-ps " | " \-\-pdf ]
-.RB [ \-o
-.IR dir ]
-.RB [ \-\-docformat
-.IR format ]
-.RB [ \-\-name
-.IR name ]
-.RB [ \-u
-.IR url ]
-.RB [ \-t
-.IR page ]
-.RB [ \-c
-.IR sheet ]
-.RB [ \-\-private\-css
-.IR sheet ]
-.RB [ \-\-navlink
-.IR html ]
-.RB [ \-\-help\-file
-.IR file ]
-.RB [ \-\-show\-private ]
-.RB [ \-\-no\-private ]
-.RB [ \-\-inheritance
-.IR style ]
-.RB [ \-\-show\-imports ]
-.RB [ \-\-ignore\-param\-mismatch ]
-.RB [ \-\-separate-classes ]
-.RB [ \-q ]
-.RB [ \-v ]
-.IB modules ...
-.HP 7
-.B epydoc
-.B \-\-check
-.RB [ \-\-tests
-.BR tests ]
-.RB [ \-\-show\-private ]
-.RB [ \-\-ignore\-param\-mismatch ]
-.RB [ \-q ]
-.RB [ \-v ]
-.IB modules ...
-.PP
-.B epydoc \-h
-.RI [ topic ]
-.PP
-.B epydoc \-V
+.RB [ action ]
+.RB [ options ]
+.IB names...
.\" ================== DESCRIPTION ====================
.SH DESCRIPTION
-.B This man page is somewhat outdated while epydoc is in alpha; run
-"epydoc --help"
-.B for a complete option list.
-.PP
.B epydoc
generates API documentation for Python modules and packages, based on
their docstrings. A lightweight markup language called
@@ -71,21 +26,24 @@
.PP
The HTML API documentation produced by
.B epydoc
-consists of a set of HTML files. Two subdirectories are created for
-the public and private documentation. Within each subdirectory,
-every class and module is documented in its own file. An index file,
-a trees file, a help file, and a frames-based table of contents are
-also created.
+consists of a set of HTML files, including: an API documentation page
+for each class and module; a syntax-highlighted source code page for
+each module; an identifier index page; a help page; and a frames-based
+table of contents. When appropriate,
+.B epydoc
+will also generate
+index pages for bugs, defined terms, and to-do items;
+a class hierarchy page; and a package hierarchy page.
.PP
The LaTeX API documentation produced by
.B epydoc
consists of a main LaTeX file, and a LaTeX file for each module. If
-you use the
+you use
.BR \-\-dvi ,
.BR \-\-ps ,
or
-.B \-\-pdf
-options, then
+.B \-\-pdf ,
+then
.B epydoc
will invoke external commands to convert the LaTeX output to the
requested format. Note that the LaTeX files containing the
@@ -97,8 +55,6 @@
.B \-\-separate\-classes
option to produce a separate LaTeX file for each class.
.PP
-.B LaTeX API output is not yet implemented in this alpha release.
-.PP
.B epydoc
can also be used to check the completeness of the API documentation.
By default, it checks that every public package, module, class,
@@ -106,89 +62,83 @@
.B \-\-tests
option can be used to specify additional tests to perform.
.PP
-.B Completeness checking is not yet implemented in this alpha release.
.\" ================== OPTIONS ====================
.SH OPTIONS
-Options are divided into five categories: action selection options;
-HTML documentation generation options; LaTeX documentation generation
-options; documentation checking options; and other options. All
-options must preceed the list of modules.
+Epydoc's options are divided into six categories: basic options,
+actions, generation options, output options, graph options, and return
+value options.
.PP
-.B ACTION SELECTION OPTIONS
+.\"--------------------------------------------------
+.B BASIC OPTIONS
.RS 4
.TP
-.B \-\-html
-Generate HTML output. (default)
+.IR names ...
+The list of objects that should be documented. Objects can be
+specified using Python dotted names (such as
+.BR os.path ),
+filenames (such as
+.BR epydoc/epytext.py ),
+or directory names (such as
+.BR epydoc/ ).
+Directory names specify packages, and are expanded to include
+all sub-modules and sub-packages. If you wish to exclude
+certain sub-modules or sub-packages, use the
+.B --exclude
+option (described below).
+.\" --config
.TP
-.B \-\-latex
-Generate LaTeX output.
-.B (Not yet implemented in this alpha release)
+.BI "\-\-config " file
+A configuration file, specifying additional
+.BR options "and/or" names "."
+This option may be repeated.
+.\" --quiet
.TP
-.B \-\-dvi
-Generate dvi output. This option first creates LaTeX output, and then
-uses
-.B latex
-and
-.B makeindex
-to convert the LaTeX files into a single
-.B dvi
-file.
-.B (Not yet implemented in this alpha release)
+.B \-\-q, \-\-quiet, \-\-v, \-\-verbose
+Produce quite (or verbose) output. If used multiple times, this
+option produces successively more quiet (or verbose) output.
+.\" --debug
.TP
-.B \-\-ps
-Generate postscript output. This option first creates LaTeX output,
-and then uses
-.BR latex ,
-.BR makeindex ,
-and
-.BR dvips
-to convert the LaTeX files into a single postscript file.
-.B (Not yet implemented in this alpha release)
+.B \-\-debug
+Show full tracebacks for internal errors.
+.\" --simple-term
.TP
+.B \-\-simple\-term
+Do not try to use color or cursor control when displaying the progress
+bar, warnings, or errors.
+.RE
+.PP
+.\"--------------------------------------------------
+.B ACTIONS
+.RS 4
+.TP 10
+.B \-\-html
+Write HTML output.
+.B [default]
+.TP 10
+.B \-\-latex
+Write LaTeX output.
+.TP 10
+.B \-\-dvi
+Write DVI output.
+.TP 10
+.B \-\-ps
+Write Postscript output.
+.TP 10
.B \-\-pdf
-Generate Adobe Acrobat
-.RB ( pdf )
-output. This option first creates LaTeX output, and then uses
-.BR latex ,
-.BR makeindex ,
-.BR dvips ,
-and
-.BR ps2pdf
-to convert the LaTeX files into a single
-.B pdf
-file.
-.B (Not yet implemented in this alpha release)
-.TP
+Write Adobe Acrobat (pdf) output.
+.TP 10
.B \-\-check
Perform completeness checks on the documentation.
-.B (Not yet implemented in this alpha release)
+.TP 10
+.B \-\-pickle
+Write the documentation to a pickle file.
.RE
.PP
-.B HTML DOCUMENTATION GENERATION OPTIONS
+.\"--------------------------------------------------
+.B GENERATION OPTIONS
.RS 4
+.\" --docformat
.TP
-.IR modules ...
-The list of the modules that should be documented. Modules can be
-specified using module names (such as
-.BR os.path ),
-filenames (such as
-.BR epydoc/epytext.py ),
-or directory names (such as
-.BR epydoc/ ).
-Directory names specify packages, and are expanded to include
-all sub-modules and sub-packages.
-.TP
-.BI "\-c " sheet ", \-\-css " sheet
-CSS stylesheet for HTML files containing public API documentation. If
-.I sheet
-is a file, then the stylesheet is copied from that file; otherwise,
-.I sheet
-is taken to be the name of a built\-in stylesheet. For a list of
-the built\-in stylesheets, run
-.BR "epydoc \-\-help css" .
-If a CSS stylesheet is not specified, then the default stylesheet is
-used.
-.TP
.BI "\-\-docformat " format
Set the default value for
.B __docformat__
@@ -202,19 +152,43 @@
for English). For a list of the markup languages currently recognized
by epydoc, run
.BR "epydoc \-\-help docformat" .
+.\" --parse-only
.TP
-.BI "\-\-help\-file " file
-A file containing the body of the help page for the HTML output.
-Navigation bars will be added at the top and bottom of this help file.
-If no file is specified, then a default help file is used.
+.BI "\-\-parse-only"
+Gather all information about the documented objects by parsing the
+relevant Python source code; in particular, do
+.I not
+use introspection to gather information about the documented objects.
+This option should be used when epydoc is run on untrusted code; or on
+code that can not be introspected because of missing dependencies, or
+because importing it would cause undesired side-effects.
+.\" --introspect-only
.TP
-.B \-\-ignore\-param\-mismatch
-Do not issue warnings when a method's parameters do not match the
-parameters of the base class method that it overrides.
+.BI "\-\-introspect-only"
+Gather all information about the documented objects by introspection;
+in particular, do
+.I not
+gather information by parsing the object's Python source code.
+.\" --exclude=PATTERN
.TP
+.BI "\-\-exclude " PATTERN
+Do not document any object whose name matches the given regular
+expression pattern.
+.\" --exclude-introspect=PATTERN
+.TP
+.BI "\-\-exclude-introspect " PATTERN
+Do not use introspection to gather information about any object whose
+name matches the given regular expression.
+.\" --exclude-parse=PATTERN
+.TP
+.BI "\-\-exclude-parse " PATTERN
+Do not use Python source code parsing to gather information about any
+object whose name matches the given regular expression.
+.\" --inheritance
+.TP
.BI "\-\-inheritance " format
The format that should be used to display inherited methods,
-variables, and properties in the "summary" tables.
+variables, and properties in the generated "summary" tables.
If
.I format
is "grouped," then inherited objects are gathered into groups, based
@@ -225,274 +199,165 @@
.I format
is "included," then inherited objects are mixed in with non-inherited
objects. The default format for HTML output is "grouped."
+.\" --show-private, --no-private
.TP
-.BI "\-\-name " name
-The name of the project whose documentation is being generated. This
-is used in the index page's title, and in the help page. It is also
-used to create the homepage link on the navigation bar, if the
-.B \-\-navlink
-option is not used.
+.B \-\-show\-private, \-\-no\-private
+These options control whether documentation is generated for private
+objects. By default, the generated documentation includes private
+objects, and users can choose whether to view private objects or not,
+by clicking on "show private" and "hide private" links. But if you
+want to discourage users from directly accessing private objects, then
+you may prefer not to generate documentation for private objects.
+.\" --show-imports
.TP
-.BI "\-\-navlink " html
-HTML code for the homepage link on the navigation bar. If this HTML
-code contains any hyperlinks
-.RB ( "<a href=...>" ),
-then it will be inserted verbatim. If
-it does not contain any hperlinks, and a project url is specified
-(with
-.BR \-\-url ),
-then a hyperlink to the specified URL is added to the link.
+.B \-\-show-imports, \-\-no\-imports
+These options control whether module imports are included in the
+generated documentation. By default, imports are not included.
+.\" --show-sourcecode
.TP
-.B \-\-no\-frames
-Do not display the frames-based table of contents on the main
-API documentation page
-.RB ( index.html ).
-This option just changes the default view; the user can still access
-the frames-based table of contents by clicking on
-.B frames
-in the navigation bar.
+.B \-\-show\-sourcecode, \-\-no\-sourcecode
+These options control whether or not epydoc should generate
+syntax-highlighted pages containing the souce code of each module in
+the HTML output. By default, the sourcecode pages are generated.
+.\" --include-log
.TP
+.B \-\-include\-log
+Generate an HTML page
+.B epydoc\-log.html
+containing all error and warning messages that are generated by
+epydoc, and include it in the generated output.
+.RE
+.PP
+.\"--------------------------------------------------
+.B OUTPUT OPTIONS
+.RS 4
+.\" --output
+.TP
.BI "\-o " dir ", \-\-output " dir
-The output directory for HTML files. By default, HTML files are
-written to the
+The output directory. If
+.B dir
+does not exist, then it will be created. If no output directory is
+specified, then the action name (e.g.,
+.BR html " or " pdf ).
.B html
-directory.
+.\" --css
.TP
-.B \-\-show\-private, \-\-no\-private
-These options control whether documentation is generated for private
-objects. By default, HTML documentation includes private objects, and
-users can choose whether to view private objects or not, by clicking
-on "show private" and "hide private" links. But if you want to
-discourage users from directly accessing private objects, then you may
-prefer not to generate documentation for private objects. The
-.B \-\-no\-private
-option is also useful if you want to generate documentation more
-quickly, since epydoc will only need to produce half as many HTML
-pages.
-.TP
-.BI "\-\-private\-css " sheet
-CSS stylesheet for HTML files containing private API documentation.
-If
+.BI "\-c " sheet ", \-\-css " sheet
+CSS stylesheet for HTML output files. If
.I sheet
-is a file, then the stylesheet is copied from that file;
-otherwise,
+is a file, then the stylesheet is copied from that file; otherwise,
.I sheet
-is taken to be the name of a built\-in stylesheet. For a list of the
-built\-in stylesheets, run
+is taken to be the name of a built\-in stylesheet. For a list of
+the built\-in stylesheets, run
.BR "epydoc \-\-help css" .
-If a CSS stylesheet is not specified, then epydoc
-copies the stylesheet for public API documentation (see
-.BR \-\-css ).
+If a CSS stylesheet is not specified, then the default stylesheet is
+used.
+.\" --name
.TP
-.B \-q, \-\-quiet
-Produce quiet output. If
-.B \-q
-is used multiple times, it produces successively more quiet output (by
-suppressing warning messages).
+.BI "\-\-name " name
+The name of the project whose documentation is being generated.
+.\" --url
.TP
-.B \-\-show\-imports
-Include a list of the classes, functions, and variables that each
-module imports on the module documentation pages.
-.TP
-.BI "\-t " page ", \-\-top " page
-The top page for the documentation.
-.I page
-can be the name of a documented module or a class; the name of a file
-containing a documented module; an absolute URL (starting
-with "http:"); or one of the special names
-.BR trees.html ,
-.BR indices.html ", or"
-.BR help.html ,
-indicating the corresponding API documentation pages.
-.TP
.BI "\-u " url ", \-\-url " url
-The URL of the project's homepage. This URL is used by the homepage
-link on the navigation bar.
+The URL of the project's homepage.
.TP
-.B \-v, \-\-verbose
-Produce verbose output. If
-.B \-v
-is used multiple times, it produces successively more verbose output.
-.RE
-.PP
-.B LATEX DOCUMENTATION GENERATION OPTIONS
-.RS 4
-LaTeX documentation generation options are used when producing LaTeX,
-postscript (ps), or pdf output.
+.\" --navlink
.TP
-.IR modules ...
-The list of the modules that should be documented. Modules can be
-specified using module names (such as
-.BR os.path ),
-filenames (such as
-.BR epydoc/epytext.py ),
-or directory names (such as
-.BR epydoc/ ).
-Directory names specify packages, and are expanded to include
-all sub-modules and sub-packages.
+.BI "\-\-navlink " html
+HTML code for the homepage link on the HTML navigation bar. If this
+HTML code contains any hyperlinks
+.RB ( "<a href=...>" ),
+then it will be inserted verbatim. If
+it does not contain any hyperlinks, and a project url is specified
+(with
+.BR \-\-url ),
+then a hyperlink to the specified URL is added to the link.
+.\" --help-file
.TP
-.B \-\-builtins
-Add the builtin modules (as defined by sys.builtin_module_names) to
-the list of modules to document.
+.BI "\-\-help\-file " file
+An alternate help file.
+.B file
+should contain the body of an HTML file -- navigation bars will be
+added to it.
+.\" --show-frames, --no-frames
.TP
-.BI "\-\-docformat " format
-Set the default value for
-.B __docformat__
-to
-.IR format .
-.B __docformat__
-is a module variable that specifies the markup language for the
-docstrings in a module. Its value consists of the name of a markup
-language, optionally followed by a language code (such as
-.B en
-for English). For a list of the markup languages currently recognized
-by epydoc, run
-.BR "epydoc \-\-help docformat" .
+.B \-\-show\-frames, \-\-no\-frames
+These options control whether HMTL output will include a frames-base
+table of contents page. By default, the frames-based table of
+contents is included.
+.\" --separate-classes
.TP
-.B \-\-ignore\-param\-mismatch
-Do not issue warnings when a method's parameters do not match the
-parameters of the base class method that it overrides.
-.TP
-.BI "\-\-inheritance " format
-The format that should be used to display inherited methods,
-variables, and properties.
-If
-.I format
-is "grouped," then inherited objects are gathered into groups, based
-on which class that they are inherited from. If
-.I format
-is "listed," then inherited objects are listed in a short list at the
-end of their section. If
-.I format
-is "included," then inherited objects are mixed in with non-inherited
-objects. The default format for LaTeX output is "listed."
-.TP
-.BI "\-\-name " name
-The name of the project whose documentation is being generated. This
-is used on the title page, in the page header, and in the pdf metadata.
-.TP
-.BI "\-o " dir ", \-\-output " dir
-The output directory. By default, HTML files are
-written to the
-.B html
-directory, and LaTeX files are written to the
-.B latex
-directory.
-.TP
-.B \-\-show\-private, \-\-no\-private
-These options control whether documentation is generated for private
-objects. By default, LaTeX output only includes documentation for
-public objects.
-.TP
-.B \-q, \-\-quiet
-Produce quiet output. If
-.B \-q
-is used multiple times, it produces successively more quiet output (by
-suppressing warning messages).
-.TP
.B \-\-separate\-classes
-Describe all classes in a separate section of the documentation,
-instead of including them in the documentation for their modules.
-This creates a separate LaTeX file for each class, so it can also be
-useful if you want to include the documentation for one or two classes
-as sections of your own LaTeX document.
-.TP
-.B \-v, \-\-verbose
-Produce verbose output. If
-.B \-v
-is used multiple times, it produces successively more verbose output.
+In the LaTeX output, describe each class in a separate section of the
+documentation, instead of including them in the documentation for
+their modules. This creates a separate LaTeX file for each class, so
+it can also be useful if you want to include the documentation for one
+or two classes as sections of your own LaTeX document.
.RE
.PP
-.B DOCUMENTATION COMPLETENESS CHECKING OPTIONS
+.\"--------------------------------------------------
+.B GRAPH OPTIONS
.RS 4
-The
-.B \-\-check
-option is used to perform completeness checks on the documentation of
-your project. By default, epydoc checks to make sure that all public
-objects have docstrings. Additional checks can be added with the
-.B \-\-tests
-option.
+.\" --graph
.TP
-.IR modules ...
-The list of the modules whose documentation should be checked.
-Modules can be specified using module names (such as
-.BR os.path ),
-filenames (such as
-.BR epydoc/epytext.py ),
-or directory names (such as
-.BR epydoc/ ).
-Directory names specify packages, and are expanded to include
-all sub-modules and sub-packages.
+.BI "\-\-graph " graphtype
+Include graphs of type
+.B graphtype
+in the generated output. Graphs are generated using the Graphviz dot
+executable. If this executable is not on the path, then use
+.B \-\-dotpath
+to specify its location. This option may be repeated to include
+multiple graph types in the output.
+.B graphtype
+should be one of:
+.BR all ", " classtree ", " callgraph ", or " umlclasstree .
+.\" --dotpath
.TP
-.B \-\-ignore\-param\-mismatch
-Do not issue warnings when a method's parameters do not match the
-parameters of the base class method that it overrides.
+.BI "\-\-dotpath " path
+The path to the Graphviz
+.BR dot
+executable.
+.\"--graph-font
.TP
-.B \-\-private
-Perform checks on private objects
+.BI "--graph-font " font
+The name of the font used to generate Graphviz graphs. (e.g.,
+helvetica or times).
+.\"--graph-font-size
.TP
-.B \-q, \-\-quiet
-Produce quiet output. If
-.B \-q
-is used multiple times, it produces successively more quiet output (by
-suppressing warning messages).
+.BI "--graph-font-size " size
+The size of the font used to generate Graphviz graphs, in points.
+.\"--pstat
.TP
-.BI "\-\-tests " tests ", \-\-checks " tests
-Perform additional tests on the documentation. For a list of the
-additional tests that are available, run
-.BR "epydoc --help tests" .
-.TP
-.B \-v, \-\-verbose
-Produce verbose output. If
-.B \-v
-is used multiple times, it produces successively more verbose output.
+.BI "--pstat " file
+A pstat output file, to be used in generating call graphs.
.RE
.PP
-.B OTHER OPTIONS
+.\"--------------------------------------------------
+.B RETURN VALUE OPTIONS
.RS 4
+.\" --fail-on-error
.TP
-.B \-h, \-\-help, \-\-usage, \-?
-Display a usage message.
+.B \-\-fail\-on\-error
+Return a non\-zero exit status, indicating failure, if any errors are
+encountered.
+.\" --fail-on-warning
.TP
-.BI "\-h " topic ", \-\-help " topic
-Display information about a specific topic. Currently,
-information is available about the following topics:
-.BR css ", " version ", and " usage .
+.B \-\-fail\-on\-warning
+Return a non\-zero exit status, indicating failure, if any errors or
+warnings are encountered (not including docstring warnings).
+.\" --fail-on-docstring-warning
.TP
-.B \-V, \-\-version
-Print the version of Epydoc.
+.B \-\-fail\-on\-docstring\-warning
+Return a non\-zero exit status, indicating failure, if any errors or
+warnings are encountered (including docstring warnings).
.RE
-.\" ================== EXAMPLES ====================
-.SH EXAMPLES
-.TP
-.BR "epydoc \-n " epydoc " \-u " "http://epydoc.sf.net epydoc/"
-Generate the HTML API documentation for the epydoc package and all of
-its submodules, and write the output to the
-.B html
-directory. In the headers and footers, use
-.B epydoc
-as the project name, and
-.B http://epydoc.sf.net
-as the project URL.
-.TP
-.BR "epydoc \-\-pdf \-n " epydoc " epydoc/"
-Generate the LaTeX API documentation for the epydoc package and all of
-its submodules, and write the output to the
-.B latex
-directory.
-.TP
-.BR "epydoc \-o "api " \-\-css " blue " \-\-private\-css " "green sys"
-Generate API documentation for the
-.B sys
-module, and write the output to the
-.B api
-directory. Use different stylesheets for the public and private
-versions of the documentation.
.\" ================== HTML FILES ====================
.SH HTML FILES
The HTML API documentation produced by
.B epydoc
consists of the following files:
+.PP
+.B OBJECT DOCUMENTATION PAGES
.RS 4
.TP
.B index.html
@@ -524,16 +389,78 @@
or
.BR array.ArrayType .
.TP
-.B trees.html
-The module and class hierarchies.
+.IB module \-pysrc.html
+A syntax-highlighted page containing the Python source code for
+.IR module .
+This page includes links back to the API documentation pages.
.TP
-.B indices.html
-The term and identifier indices.
+.B module-tree.html
+The module hierarchy.
.TP
-.B help.html
-The help page for the project. This page explains how to use and
-navigate the webpage produced by epydoc.
+.B class-tree.html
+The class hierarchy. This page is only generated if at least one
+class is documented.
+.PP
+.RE
+.B INDICES
+.RS 4
.TP
+.B identifier-index.html
+An index of all documented identifiers. If the identifier index
+contains more than 3,000 entries, then it will be split into separate
+pages for each letter, named
+.BR identifier-index-a.html ,
+.BR identifier-index-b.html ", etc."
+.TP
+.B term-index.html
+An index of all explicitly marked definitional terms. This page is
+only generated if at least one definition term is marked in a
+formatted docstring.
+.TP
+.B bug-index.html
+An index of all explicitly marked
+.B @bug
+fields. This page is only
+generated if at least one
+.B @bug
+field is listed in a formatted docstring.
+.TP
+.B todo-index.html
+An index of all explicitly marked
+.B @todo
+fields. This page is only
+generated if at least one
+.B @todo
+field is listed in a formatted docstring.
+.TP
+.B changed-index.html
+An index of all explicitly marked
+.B @changed
+fields. This page is only
+generated if at least one
+.B @changed
+field is listed in a formatted docstring.
+.TP
+.B deprecated-index.html
+An index of all explicitly marked
+.B @deprecated
+fields. This page is only
+generated if at least one
+.B @deprecated
+field is listed in a formatted docstring.
+.TP
+.B since-index.html
+An index of all explicitly marked
+.B @since
+fields. This page is only
+generated if at least one
+.B @since
+field is listed in a formatted docstring.
+.RE
+.PP
+.B FRAMES-BASED TABLE OF CONTENTS
+.RS 4
+.TP
.B frames.html
The main frames file. Two frames on the left side of the window
contain a table of contents, and the main frame on the right side of
@@ -567,22 +494,33 @@
.B sys
or
.BR epydoc.epytext .
+.RE
+.PP
+.B OTHER PAGES
+.RS 4
.TP
+.B help.html
+The help page for the project. This page explains how to use and
+navigate the webpage produced by epydoc.
+.TP
+.B redirect.html
+This page uses javascript to translate dotted names to their
+corresponding URLs. For example, in epydoc's documentation,
+loading the page
+.B <redirect.html#epydoc.apidoc.DottedName>
+will automatically redirect the browser to
+.BR <epydoc.apidoc-module.html#DottedName> .
+.TP
.B epydoc.css
The CSS stylesheet used to display all HTML pages.
-.RE
-.PP
-By default,
-.B epydoc
-creates two subdirectories in the output directory:
-.B public
-and
-.BR private .
-Each directory contains all of the files specified above.
-But if the
-.B \-\-no\-private
-option is used, then no subdirectories are created, and the public
-documentation is written directly to the output directory.
+.TP
+.B epydoc.js
+A javascript file used to define javascript functions used by epydoc.
+.TP
+.B epydoc\-log.html
+A page containing a log of all warnings and errors that were generated
+by epydoc, along with a table listing all of the options that were
+used.
.\" ================== LATEX FILES ====================
.SH LATEX FILES
The LaTeX API documentation produced by
@@ -638,51 +576,12 @@
.RE
.\" ================== DIAGNOSTICS ====================
.SH DIAGNOSTICS
-Errors are divided into five categories: import errors; epytext
-errors; epytext warnings; field warnings; and inspection errors.
-Whenver epydoc encounters an error, it issues a warning message that
-describes the error, and attempts to continue generating
-documentation.
-.PP
-Import errors indicate that epydoc was unable to import a module.
-Import errors typically prevent epydoc from generating documentation
-for the module in question. Epydoc can generate the following import
-errors:
+.B EPYTEXT MARKUP WARNING MESSAGES
.RS 4
-.TP
-.BI "Bad module name " module
-Epydoc attempted to import
-.IR module ,
-but
-.I module
-is not a valid name for a Python module.
-.TP
-.BI "Could not find a UID for " link-target
-Epydoc was unable to find the object referred to by an inline link
-construction
-.RB ( "L{...}" ).
-This is usually caused by a typo in the link.
-.TP
-.BI "Could not import " module
-Epydoc attempted to import
-.IR module ,
-but it failed. This typically occurs when
-.I module
-raises an exception.
-.TP
-.IB file " does not exist"
-Epydoc attempted to import the module contained in
-.IR file ,
-but
-.I file
-does not exist.
-.RE
-.PP
Epytext errors are caused by epytext docstrings that contain invalid
markup. Whenever an epytext error is detected, the docstring in
question is treated as a plaintext docstring. Epydoc can generate the
following epytext errors:
-.RS 4
.TP
.B Bad link target.
The target specified for an inline link contruction
@@ -754,14 +653,6 @@
indicate an appopriate section level. The "=" character should be
used to underline sections; "-" for subsections; and "~" for
subsubsections.
-.RE
-.PP
-Epytext warnings are caused by epytext docstrings that contain
-questionable or suspicious markup. Epytext warnings do
-.B not
-prevent the docstring in question from being parsed. Epydoc can
-generate the following epytext warnings:
-.RS 4
.TP
.B Possible mal-formatted field item.
Epytext detected a line that looks like a field item, but is not
@@ -775,10 +666,11 @@
match exactly for them to be considered a heading.
.RE
.PP
-Field warnings are caused by epytext docstrings containing invalid
-fields. The contents of the invalid field are generally ignored.
-Epydoc can generate the following field warnings:
+.B FIELD WARNINGS
.RS 4
+Field warnings are caused by docstrings containing invalid fields.
+The contents of the invalid field are generally ignored. Epydoc can
+generate the following field warnings:
.TP
.BI "@param for unknown parameter " param .
A @param field was used to specify the type for a parameter that is
@@ -816,75 +708,24 @@
.I field
can only take a single value.
.RE
-.PP
-Inspection errors are generated if epydoc encounters problems while
-attempting to inspect the properties of a documented object. Most of
-inspection errors do not prevent epydoc from documenting the object in
-question. Epydoc can generate the following inspection errors:
-.RS 4
+.\" ================== EXAMPLES ====================
+.SH EXAMPLES
.TP
-.BI "The parameters of " inhmethod " do not match " basemethod .
-The parameters of the undocumented method
-.I inhmethod
-do not match the parameters of the base class method
-.I basemethod
-that it overrides. As a result,
-.I inhmethod
-does not inherit documentation from
-.IR basemethod .
-If the difference in parameters is intentional, then you can eliminate
-the warning by adding a (possibly empty) docstring to
-.IR inhmethod .
+.BR "epydoc \-n " epydoc " \-u " "http://epydoc.sf.net epydoc/"
+Generate the HTML API documentation for the epydoc package and all of
+its submodules, and write the output to the
+.B html
+directory. In the headers and footers, use
+.B epydoc
+as the project name, and
+.B http://epydoc.sf.net
+as the project URL.
.TP
-.BI "Docmap cannot add a " type
-Epydoc attempted to document an object with an unknown type. This
-error is typically generated by packages and modules that manipulate
-the import mechanism, such that importing a module produces some other
-type of object.
-.TP
-.BI "UID conflict detected: " uid
-Two different objects were assigned the same unique identifier by
-epydoc. This can cause epydoc to substitute the documentation of one
-object with the documentation of another object that is assigned the
-same unique identifier. However, this will usually only cause
-problems if the two objects with the same unique identifiers are both
-modules or classes, in which case the API documentation page for one
-object will overwrite the API documentation page for the other object.
-.TP
-.IB object " appears in multiple builtin modules"
-While attempting to determine which module defines the builtin object
-.IR object ,
-epydoc encountered multiple candidates, and was unable to decide which
-candidate was correct. In this case, epydoc arbitrarily chooses the
-first candidate that it finds.
-.TP
-.IB object " appears in multiple .py modules"
-While attempting to determine which module defines the builtin object
-.IR object ,
-epydoc encountered multiple candidates, and was unable to decide which
-candidate was correct. In this case, epydoc arbitrarily chooses the
-first candidate that it finds.
-.TP
-.IB object " appears in multiple .so modules"
-While attempting to determine which module defines the builtin object
-.IR object ,
-epydoc encountered multiple candidates, and was unable to decide which
-candidate was correct. In this case, epydoc arbitrarily chooses the
-first candidate that it finds.
-.TP
-.BI "Could not find a module for " object
-Epydoc was unable to determine which module defines
-.IR object .
-If
-.I object
-is a function, then this will prevent epydoc from generating any
-documentation for
-.IR object ,
-since it does not know what page to put the documentation on.
-Otherwise, this will prevent the documentation for
-.I object
-from including a link to its containing module.
-.RE
+.BR "epydoc \-\-pdf \-n " epydoc " epydoc/"
+Generate the LaTeX API documentation for the epydoc package and all of
+its submodules, and write the output to the
+.B latex
+directory.
.\" ================== EXIT STATUS ====================
.SH EXIT STATUS
.TP
@@ -894,6 +735,13 @@
.B 1
Usage error.
.TP
+.B 2
+Epydoc generated an error or warning, and one of the options
+.BI \-\-fail\-on\-error ,
+.BI \-\-fail\-on\-warning ", or"
+.B \-\-fail\-on\-docstring\-warning
+was specified.
+.TP
.B other
Internal error (Python exception).
.\" ================== AUTHOR ====================
@@ -902,7 +750,7 @@
written by Moshe Zadka, and is currently maintained by Edward Loper.
.\" ================== BUGS ====================
.SH BUGS
-Report bugs to <ed...@gr...>.
+Report bugs to <ed...@us...>.
.\" ================== SEE ALSO ====================
.SH SEE ALSO
.BR epydocgui (1)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-16 05:37:01
|
Revision: 1515
http://svn.sourceforge.net/epydoc/?rev=1515&view=rev
Author: edloper
Date: 2007-02-15 21:36:58 -0800 (Thu, 15 Feb 2007)
Log Message:
-----------
- Added support for "--help TOPIC"
- If the target directory does not exist when the --include-log option
is used, then create it.
- Changed exit status for --fail-on-error etc from 1 to 2. When
exiting because of an internal error, use exit status 3.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/cli.py
Modified: trunk/epydoc/src/epydoc/cli.py
===================================================================
--- trunk/epydoc/src/epydoc/cli.py 2007-02-16 05:35:01 UTC (rev 1514)
+++ trunk/epydoc/src/epydoc/cli.py 2007-02-16 05:36:58 UTC (rev 1515)
@@ -74,6 +74,7 @@
from epydoc.apidoc import UNKNOWN
from epydoc.compat import *
import ConfigParser
+from epydoc.docwriter.html_css import STYLESHEETS as CSS_STYLESHEETS
INHERITANCE_STYLES = ('grouped', 'listed', 'included')
GRAPH_TYPES = ('classtree', 'callgraph', 'umlclasstree')
@@ -82,6 +83,42 @@
PROFILER = 'hotshot' #: Which profiler to use: 'hotshot' or 'profile'
######################################################################
+#{ Help Topics
+######################################################################
+
+DOCFORMATS = ('epytext', 'plaintext', 'restructuredtext', 'javadoc')
+HELP_TOPICS = {
+ 'docformat': textwrap.dedent('''\
+ __docformat__ is a module variable that specifies the markup
+ language for the docstrings in a module. Its value is a
+ string, consisting the name of a markup language, optionally
+ followed by a language code (such as "en" for English). Epydoc
+ currently recognizes the following markup language names:
+ ''' + ', '.join(DOCFORMATS)),
+ 'inheritance': textwrap.dedent('''\
+ The following inheritance formats are currently supported:
+ - grouped: inherited objects are gathered into groups,
+ based on what class they were inherited from.
+ - listed: inherited objects are listed in a short list
+ at the end of their section.
+ - included: inherited objects are mixed in with
+ non-inherited objects.'''),
+ 'css': textwrap.dedent(
+ 'The following built-in CSS stylesheets are available:\n' +
+ '\n'.join([' %10s: %s' % (key, descr)
+ for (key, (sheet, descr))
+ in CSS_STYLESHEETS.items()])),
+ #'checks': textwrap.dedent('''\
+ #
+ # '''),
+ }
+
+
+HELP_TOPICS['topics'] = wordwrap(
+ 'Epydoc can provide additional help for the following topics: ' +
+ ', '.join(['%r' % topic for topic in HELP_TOPICS.keys()]))
+
+######################################################################
#{ Argument & Config File Parsing
######################################################################
@@ -96,9 +133,9 @@
def parse_arguments():
# Construct the option parser.
- usage = '%prog ACTION [options] NAMES...'
+ usage = '%prog [ACTION] [options] NAMES...'
version = "Epydoc, version %s" % epydoc.__version__
- optparser = OptionParser(usage=usage, version=version)
+ optparser = OptionParser(usage=usage, add_help_option=False)
action_group = OptionGroup(optparser, 'Actions')
generation_group = OptionGroup(optparser, 'Generation options')
output_group = OptionGroup(optparser, 'Output options')
@@ -122,7 +159,7 @@
"--simple-term", action="store_true", dest="simple_term",
help="Do not try to use color or cursor control when displaying "
"the progress bar, warnings, or errors.")
-
+
# Add options -- Actions
action_group.add_option( # --html
"--html", action="store_const", dest="action", const="html",
@@ -148,6 +185,15 @@
action_group.add_option(
"--pickle", action="store_const", dest="action", const="pickle",
help="Write the documentation to a pickle file.")
+ # Provide our own --help and --version options.
+ action_group.add_option(
+ "--version", action="store_const", dest="action", const="version",
+ help="Show epydoc's version number and exit.")
+ action_group.add_option(
+ "-h", "--help", action="store_const", dest="action", const="help",
+ help="Show this message and exit. For help on specific "
+ "topics, use \"--help TOPIC\". Use \"--help topics\" for a "
+ "list of available help topics")
# Add options -- Generation
generation_group.add_option( # --docformat
@@ -191,9 +237,6 @@
generation_group.add_option( # --no-imports
"--no-imports", action="store_false", dest="show_imports",
help="Do not list each module's imports. (default)")
- generation_group.add_option( # --include-log
- '--include-log', action='store_true', dest='include_log',
- help=("Include a page with the process log (epydoc-log.html)"))
generation_group.add_option( # --show-sourcecode
'--show-sourcecode', action='store_true', dest='include_source_code',
help=("Include source code with syntax highlighting in the "
@@ -202,6 +245,9 @@
'--no-sourcecode', action='store_false', dest='include_source_code',
help=("Do not include source code with syntax highlighting in the "
"HTML output."))
+ generation_group.add_option( # --include-log
+ '--include-log', action='store_true', dest='include_log',
+ help=("Include a page with the process log (epydoc-log.html)"))
# Add options -- Output
output_group.add_option( # --output
@@ -303,6 +349,22 @@
# Parse the arguments.
options, names = optparser.parse_args()
+
+ # Print help message, if requested. We also provide support for
+ # --help [topic]
+ if options.action == 'help':
+ names = set([n.lower() for n in names])
+ for (topic, msg) in HELP_TOPICS.items():
+ if topic.lower() in names:
+ print '\n' + msg.rstrip() + '\n'
+ sys.exit(0)
+ optparser.print_help()
+ sys.exit(0)
+
+ # Print version message, if requested.
+ if options.action == 'version':
+ print version
+ sys.exit(0)
# Process any config files.
if options.configfiles:
@@ -529,6 +591,8 @@
if options.include_log:
if options.action == 'html':
+ if not os.path.exists(options.target):
+ os.mkdir(options.target)
log.register_logger(HTMLLogger(options.target, options))
else:
log.warning("--include-log requires --html")
@@ -628,11 +692,11 @@
logger.print_times()
# If we encountered any message types that we were requested to
- # fail on, then exit with status 1.
+ # fail on, then exit with status 2.
if options.fail_on is not None:
max_reported_message_level = max(logger.reported_message_levels)
if max_reported_message_level >= options.fail_on:
- sys.exit(1)
+ sys.exit(2)
def write_html(docindex, options):
from epydoc.docwriter.html import HTMLWriter
@@ -800,6 +864,7 @@
print >>sys.stderr, ('\nUNEXPECTED ERROR:\n'
'%s\n' % (str(e) or e.__class__.__name__))
print >>sys.stderr, 'Use --debug to see trace information.'
+ sys.exit(3)
def _profile():
# Hotshot profiler.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-16 05:35:04
|
Revision: 1514
http://svn.sourceforge.net/epydoc/?rev=1514&view=rev
Author: edloper
Date: 2007-02-15 21:35:01 -0800 (Thu, 15 Feb 2007)
Log Message:
-----------
- Fixed docstring typo
Modified Paths:
--------------
trunk/epydoc/src/epydoc/markup/pyval_repr.py
Modified: trunk/epydoc/src/epydoc/markup/pyval_repr.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/pyval_repr.py 2007-02-16 02:34:36 UTC (rev 1513)
+++ trunk/epydoc/src/epydoc/markup/pyval_repr.py 2007-02-16 05:35:01 UTC (rev 1514)
@@ -22,7 +22,7 @@
because maxlines is typically around 5, so it's really not worth it.
The syntax-highlighted output is encoded using a
-L{ParsedEpydocDocstring}, which can then be used to generate output in
+L{ParsedEpytextDocstring}, which can then be used to generate output in
a variety of formats.
"""
__docformat__ = 'epytext en'
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-16 02:34:58
|
Revision: 1513
http://svn.sourceforge.net/epydoc/?rev=1513&view=rev
Author: dvarrazzo
Date: 2007-02-15 18:34:36 -0800 (Thu, 15 Feb 2007)
Log Message:
-----------
- Something has been merged. No need for further space crunching.
Removed Paths:
-------------
branches/exp-compact-html/
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
