epydoc-commits Mailing List for Python API documentation generation tool (Page 11)
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-27 09:57:26
|
Revision: 1562
http://svn.sourceforge.net/epydoc/?rev=1562&view=rev
Author: dvarrazzo
Date: 2007-02-27 01:57:25 -0800 (Tue, 27 Feb 2007)
Log Message:
-----------
- Fixed broken link.
Modified Paths:
--------------
trunk/epydoc/doc/index.html
Modified: trunk/epydoc/doc/index.html
===================================================================
--- trunk/epydoc/doc/index.html 2007-02-27 07:23:12 UTC (rev 1561)
+++ trunk/epydoc/doc/index.html 2007-02-27 09:57:25 UTC (rev 1562)
@@ -41,7 +41,7 @@
<ul id="epydoc-manual">
<li> <a href="manual-install.html">Installing Epydoc</a> </li>
<li> <a href="manual-usage.html">Using Epydoc</a> </li>
- <li> <a href="manual-docstrings.html">Python Docstrings</a> </li>
+ <li> <a href="manual-docstring.html">Python Docstrings</a> </li>
<li> <a href="manual-epytext.html">The Epytext Markup Language</a> </li>
<li> <a href="manual-fields.html">Epydoc Fields</a> </li>
<li> <a href="manual-othermarkup.html">reStructuredText and
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-27 07:23:15
|
Revision: 1561
http://svn.sourceforge.net/epydoc/?rev=1561&view=rev
Author: edloper
Date: 2007-02-26 23:23:12 -0800 (Mon, 26 Feb 2007)
Log Message:
-----------
- Updated for 3.0beta release
Modified Paths:
--------------
trunk/epydoc/doc/index.html
Modified: trunk/epydoc/doc/index.html
===================================================================
--- trunk/epydoc/doc/index.html 2007-02-27 06:43:44 UTC (rev 1560)
+++ trunk/epydoc/doc/index.html 2007-02-27 07:23:12 UTC (rev 1561)
@@ -94,7 +94,7 @@
<h2 class="box-title">Latest Release</h2>
<ul>
-<li> The latest testing release is <a href="http://sourceforge.net/project/showfiles.php?group_id=32455&package_id=24617&release_id=441763">Epydoc 3.0 alpha 3</a>. </li>
+<li> The latest testing release is <a href="http://sourceforge.net/project/platformdownload.php?group_id=32455">Epydoc 3.0 beta 1</a>. </li>
<li>The
latest stable release is <a href="http://sourceforge.net/project/showfiles.php?group_id=32455&package_id=24617&release_id=225095">Epydoc 2.1</a>. </li>
@@ -130,9 +130,9 @@
<div class="box">
<h2 class="box-title">News</h2>
-<p><b>Epydoc 3.0 alpha 3 released [August 2006]</b></br /> The third
-alpha release of epydoc 3.0 is now available on the <a
-href="http://sourceforge.net/project/showfiles.php?group_id=32455">SourceForge
+<p><b>Epydoc 3.0 beta 1 released [February 2007]</b></br /> The first
+beta release of epydoc 3.0 is now available on the <a
+href="http://sourceforge.net/project/platformdownload.php?group_id=32455">SourceForge
download page</a>. See the <a href="whatsnew.html">What's New</a>
page for details. Epydoc is under active development; if you wish to
keep up on the latest developments, you can get epydoc from the <a
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-27 06:43:45
|
Revision: 1560
http://svn.sourceforge.net/epydoc/?rev=1560&view=rev
Author: edloper
Date: 2007-02-26 22:43:44 -0800 (Mon, 26 Feb 2007)
Log Message:
-----------
- Minor css change
Modified Paths:
--------------
trunk/epydoc/doc/custom.css
Modified: trunk/epydoc/doc/custom.css
===================================================================
--- trunk/epydoc/doc/custom.css 2007-02-27 06:42:46 UTC (rev 1559)
+++ trunk/epydoc/doc/custom.css 2007-02-27 06:43:44 UTC (rev 1560)
@@ -83,7 +83,8 @@
div.epydoc-usage { border: 1px solid #708890;
background: #e8f0f8; margin: 1em; padding: 0.5em}
-table.option-list { background: none !important; }
+table.option-list { background: none !important;
+ border: 0px solid black; }
table.option-list td { border: none !important; }
div.note {
@@ -146,4 +147,4 @@
<td>3.0b1</td></tr>
</tbody>
</table>
-<div class="abstract topic">*/
\ No newline at end of file
+<div class="abstract topic">*/
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-27 06:42:48
|
Revision: 1559
http://svn.sourceforge.net/epydoc/?rev=1559&view=rev
Author: edloper
Date: 2007-02-26 22:42:46 -0800 (Mon, 26 Feb 2007)
Log Message:
-----------
- Fixed typo
Modified Paths:
--------------
trunk/epydoc/doc/manual.txt
Modified: trunk/epydoc/doc/manual.txt
===================================================================
--- trunk/epydoc/doc/manual.txt 2007-02-27 05:28:35 UTC (rev 1558)
+++ trunk/epydoc/doc/manual.txt 2007-02-27 06:42:46 UTC (rev 1559)
@@ -32,7 +32,6 @@
.. contents::
.. section-numbering::
-.. def:: singlepage
.. Include the document chapters
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-27 05:28:39
|
Revision: 1558
http://svn.sourceforge.net/epydoc/?rev=1558&view=rev
Author: edloper
Date: 2007-02-26 21:28:35 -0800 (Mon, 26 Feb 2007)
Log Message:
-----------
- Bumped version alpha3 -> beta1
Modified Paths:
--------------
trunk/epydoc/doc/installing.html
trunk/epydoc/src/epydoc/__init__.py
Modified: trunk/epydoc/doc/installing.html
===================================================================
--- trunk/epydoc/doc/installing.html 2007-02-27 05:22:21 UTC (rev 1557)
+++ trunk/epydoc/doc/installing.html 2007-02-27 05:28:35 UTC (rev 1558)
@@ -83,13 +83,13 @@
<div class="screen"><pre>
<code class="prompt">[/tmp]$</code> <code class="user">su</code>
Password:
-<code class="prompt">[/tmp]#</code> <code class="user">rpm -i epydoc-3.0alpha3.noarch.rpm</code>
+<code class="prompt">[/tmp]#</code> <code class="user">rpm -i epydoc-3.0beta1.noarch.rpm</code>
</pre></div></li>
<li> Once epydoc is installed, you can delete the RPM file.
<div class="screen"><pre>
-<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0alpha3.rpm</code>
+<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0beta1.rpm</code>
</pre></div> </li>
</ol>
@@ -97,7 +97,7 @@
<h2> Installing from the Windows Installer </h2>
<ol>
- <li> Download and run <code>epydoc-3.0alpha3.win32.exe</code>. </li>
+ <li> Download and run <code>epydoc-3.0beta1.win32.exe</code>. </li>
<li> Follow the on-screen instructions. Epydoc will be installed in
the <code>epydoc</code> subdirectory of your Python installation
directory (typically <code>C:\Python23\</code>). </li>
@@ -109,7 +109,7 @@
scripts to more convenient locations (such as your desktop or start
menu). </li>
<li> Once epydoc is installed, you can delete
- <code>epydoc-3.0alpha3.win32.exe</code>. </li>
+ <code>epydoc-3.0beta1.win32.exe</code>. </li>
</ol>
<a name="src"></a>
@@ -120,19 +120,19 @@
to a directory of your choice, and uncompress it.
<div class="screen"><pre>
-<code class="prompt">[/tmp]$</code> <code class="user">wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0alpha3.tar.gz</code>
-<code class="prompt">[/tmp]$</code> <code class="user">gunzip epydoc-3.0alpha3.tar.gz</code>
-<code class="prompt">[/tmp]$</code> <code class="user">tar -xvf epydoc-3.0alpha3.tar</code>
+<code class="prompt">[/tmp]$</code> <code class="user">wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0beta1.tar.gz</code>
+<code class="prompt">[/tmp]$</code> <code class="user">gunzip epydoc-3.0beta1.tar.gz</code>
+<code class="prompt">[/tmp]$</code> <code class="user">tar -xvf epydoc-3.0beta1.tar</code>
</pre></div></li>
- <li> Use "<code>make install</code>" in the <code>eydoc-3.0alpha3/</code>
+ <li> Use "<code>make install</code>" in the <code>eydoc-3.0beta1/</code>
directory to install epydoc.
<div class="screen"><pre>
-<code class="prompt">[/tmp]$</code> <code class="user">cd epydoc-3.0alpha3/</code>
-<code class="prompt">[/tmp/epydoc-3.0alpha3]$</code> <code class="user">su</code>
+<code class="prompt">[/tmp]$</code> <code class="user">cd epydoc-3.0beta1/</code>
+<code class="prompt">[/tmp/epydoc-3.0beta1]$</code> <code class="user">su</code>
Password:
-<code class="prompt">[/tmp/epydoc-3.0alpha3]#</code> <code class="user">make install</code>
+<code class="prompt">[/tmp/epydoc-3.0beta1]#</code> <code class="user">make install</code>
running install
running build
<i>[...]</i>
@@ -150,16 +150,16 @@
running "<code>make installdocs</code>".
<div class="screen"><pre>
-<code class="prompt">[/tmp/epydoc-3.0alpha3]#</code> <code class="user">make installdocs</code>
+<code class="prompt">[/tmp/epydoc-3.0beta1]#</code> <code class="user">make installdocs</code>
</pre></div></li>
<li> Once epydoc is installed, you can delete the installation
directory and the source distribution file.
<div class="screen"><pre>
-<code class="prompt">[/tmp/epydoc-3.0alpha3]#</code> <code class="user">cd ..</code>
-<code class="prompt">[/tmp]#</code> <code class="user">rm -r epydoc-3.0alpha3</code>
-<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0alpha3.tar</code>
+<code class="prompt">[/tmp/epydoc-3.0beta1]#</code> <code class="user">cd ..</code>
+<code class="prompt">[/tmp]#</code> <code class="user">rm -r epydoc-3.0beta1</code>
+<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0beta1.tar</code>
</pre></div> </li>
</ol>
@@ -171,25 +171,25 @@
to a directory of your choice, and uncompress it.
<div class="screen"><pre>
-<code class="prompt">[/tmp]$</code> <code class="user">wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0alpha3.tar.gz</code>
-<code class="prompt">[/tmp]$</code> <code class="user">gunzip epydoc-3.0alpha3.tar.gz</code>
-<code class="prompt">[/tmp]$</code> <code class="user">tar -xvf epydoc-3.0alpha3.tar</code>
+<code class="prompt">[/tmp]$</code> <code class="user">wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0beta1.tar.gz</code>
+<code class="prompt">[/tmp]$</code> <code class="user">gunzip epydoc-3.0beta1.tar.gz</code>
+<code class="prompt">[/tmp]$</code> <code class="user">tar -xvf epydoc-3.0beta1.tar</code>
</pre></div></li>
<li> Use the <code>setup.py</code> script in the
- <code>eydoc-3.0alpha3/</code> directory to install epydoc.
+ <code>eydoc-3.0beta1/</code> directory to install epydoc.
<div class="screen"><pre>
-<code class="prompt">[/tmp]$</code> <code class="user">cd epydoc-3.0alpha3/</code>
-<code class="prompt">[/tmp/epydoc-3.0alpha3]$</code> <code class="user">su</code>
+<code class="prompt">[/tmp]$</code> <code class="user">cd epydoc-3.0beta1/</code>
+<code class="prompt">[/tmp/epydoc-3.0beta1]$</code> <code class="user">su</code>
Password:
-<code class="prompt">[/tmp/epydoc-3.0alpha3]#</code> <code class="user">python setup.py install</code>
+<code class="prompt">[/tmp/epydoc-3.0beta1]#</code> <code class="user">python setup.py install</code>
running install
running build
<i>[...]</i>
copying build/scripts/epydoc -> /usr/bin
changing mode of /usr/bin/epydoc to 100775
-<code class="prompt">[/tmp/epydoc-3.0alpha3]#</code> <code class="user">cd ..</code>
+<code class="prompt">[/tmp/epydoc-3.0beta1]#</code> <code class="user">cd ..</code>
<code class="prompt">[/tmp]#</code>
</pre></div></li>
@@ -199,16 +199,16 @@
as <code>/usr/share/man/</code>.
<div class="screen"><pre>
-<code class="prompt">[/tmp]#</code> <code class="user">cp -r epydoc-3.0alpha3/doc/ /usr/share/doc/epydoc/</code>
-<code class="prompt">[/tmp]#</code> <code class="user">cp epydoc-3.0alpha3/man/* /usr/share/man/</code>
+<code class="prompt">[/tmp]#</code> <code class="user">cp -r epydoc-3.0beta1/doc/ /usr/share/doc/epydoc/</code>
+<code class="prompt">[/tmp]#</code> <code class="user">cp epydoc-3.0beta1/man/* /usr/share/man/</code>
</pre></div> </li>
<li> Once epydoc is installed, you can delete the installation
directory and the source distribution file.
<div class="screen"><pre>
-<code class="prompt">[/tmp]#</code> <code class="user">rm -r epydoc-3.0alpha3</code>
-<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0alpha3.tar</code>
+<code class="prompt">[/tmp]#</code> <code class="user">rm -r epydoc-3.0beta1</code>
+<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0beta1.tar</code>
</pre></div> </li>
</ol>
Modified: trunk/epydoc/src/epydoc/__init__.py
===================================================================
--- trunk/epydoc/src/epydoc/__init__.py 2007-02-27 05:22:21 UTC (rev 1557)
+++ trunk/epydoc/src/epydoc/__init__.py 2007-02-27 05:28:35 UTC (rev 1558)
@@ -167,7 +167,7 @@
:author: `Edward Loper <ed...@gr...>`__
:requires: Python 2.3+
-:version: 3.0 alpha 2
+:version: 3.0 beta 1
:see: `The epydoc webpage <http://epydoc.sourceforge.net>`__
:see: `The epytext markup language
manual <http://epydoc.sourceforge.net/epytext.html>`__
@@ -200,7 +200,7 @@
"""
__docformat__ = 'restructuredtext en'
-__version__ = '3.0alpha3'
+__version__ = '3.0beta1'
"""The version of epydoc"""
__author__ = 'Edward Loper <ed...@gr...>'
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-27 05:22:26
|
Revision: 1557
http://svn.sourceforge.net/epydoc/?rev=1557&view=rev
Author: edloper
Date: 2007-02-26 21:22:21 -0800 (Mon, 26 Feb 2007)
Log Message:
-----------
- Minor updates to what's new page
Modified Paths:
--------------
trunk/epydoc/doc/whatsnew.html
Modified: trunk/epydoc/doc/whatsnew.html
===================================================================
--- trunk/epydoc/doc/whatsnew.html 2007-02-27 05:16:41 UTC (rev 1556)
+++ trunk/epydoc/doc/whatsnew.html 2007-02-27 05:22:21 UTC (rev 1557)
@@ -56,7 +56,7 @@
<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>
+</pre></div> <!-- " -->
<h3> Graphs & Diagrams </h3>
@@ -132,10 +132,20 @@
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>
+ <li> Improved variable values representation, using the parsed
+ values if the standard representation is not informative (such
+ as <code><Foo instance at 0x...></code>). Syntax highlighting
+ is used for introspected values, including colorization for regular
+ expressions. </li>
+
+ <li> Improved support for adding links into the generated
+ documentation. A new API,
+ <a href="api/epydoc.docwriter.xlink-module.html"
+ ><code>epydoc.docwriter.xlink</code></a>, can be used to determine
+ the correct URL for any object name; and a new redirect page named
+ named "<code>redirect.html"</code> uses javascript to automatically
+ redirect the user to the correct URL for any given object name. See
+ the <a href="faq.html#redirect">FAQ</a> for more information.
</ul>
<h3>Improved Documentation Extraction</h3>
@@ -151,7 +161,10 @@
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>
+ <li> Fine-grained control over exactly which modules should be parsed,
+ introspected, or both. </li>
+ <li> Support for Zope 3.x InterfaceClass and Zope 2.x ExtensionClass
+ objects. </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-27 05:16:43
|
Revision: 1556
http://svn.sourceforge.net/epydoc/?rev=1556&view=rev
Author: edloper
Date: 2007-02-26 21:16:41 -0800 (Mon, 26 Feb 2007)
Log Message:
-----------
- Don't fail if docutils module isn't available -- the DocUrlGenerator
class may still be useful.
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-27 04:00:10 UTC (rev 1555)
+++ trunk/epydoc/src/epydoc/docwriter/xlink.py 2007-02-27 05:16:41 UTC (rev 1556)
@@ -75,10 +75,8 @@
import re
import sys
+from optparse import OptionValueError
-from docutils.parsers.rst import roles
-from docutils import nodes, utils
-
from epydoc import log
class UrlGenerator:
@@ -353,6 +351,17 @@
"""
api_register[name].prefix = prefix
+######################################################################
+# Below this point requires docutils.
+try:
+ import docutils
+ from docutils.parsers.rst import roles
+ from docutils import nodes, utils
+ from docutils.readers.standalone import Reader
+except ImportError:
+ docutils = roles = nodes = utils = None
+ class Reader: settings_spec = ()
+
def create_api_role(name, problematic):
"""
Create and register a new role to create links for an API documentation.
@@ -362,6 +371,8 @@
"""
def resolve_api_name(n, rawtext, text, lineno, inliner,
options={}, content=[]):
+ if docutils is None:
+ raise AssertionError('requires docutils')
# node in monotype font
text = utils.unescape(text)
@@ -388,8 +399,6 @@
#{ Command line parsing
# --------------------
-#from docutils import SettingsSpec
-from optparse import OptionValueError
def split_name(value):
"""
@@ -410,7 +419,6 @@
return (name, val)
-from docutils.readers.standalone import Reader
class ApiLinkReader(Reader):
"""
@@ -438,6 +446,11 @@
{'metavar': 'NAME:STRING', 'action': 'append'}
),)) + Reader.settings_spec
+ def __init__(self, *args, **kwargs):
+ if docutils is None:
+ raise AssertionError('requires docutils')
+ Reader.__init__(self, *args, **kwargs)
+
def read(self, source, parser, settings):
self.read_configuration(settings, problematic=True)
return Reader.read(self, source, parser, settings)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-27 04:00:11
|
Revision: 1555
http://svn.sourceforge.net/epydoc/?rev=1555&view=rev
Author: edloper
Date: 2007-02-26 20:00:10 -0800 (Mon, 26 Feb 2007)
Log Message:
-----------
formatting changes to the webpage
Modified Paths:
--------------
trunk/epydoc/doc/epydoc.css
trunk/epydoc/doc/index.html
Modified: trunk/epydoc/doc/epydoc.css
===================================================================
--- trunk/epydoc/doc/epydoc.css 2007-02-27 03:31:56 UTC (rev 1554)
+++ trunk/epydoc/doc/epydoc.css 2007-02-27 04:00:10 UTC (rev 1555)
@@ -64,9 +64,20 @@
/*===================================================================*/
/* Lists. */
-ul.nomargin { margin-top: 0; margin-bottom: 0em; }
+ul.nomargin { margin-top: 0; margin-bottom: 0; }
/*===================================================================*/
+/* Index page. */
+
+#documentation-box table { margin-top: 0.7em; }
+#documentation-box ul, #documentation-box ol
+ { margin: 0; padding: 0 0 0 2em; font-size: 90%;}
+#documentation-box td { padding: 0 0 1em 0; }
+#documentation-box p { margin: 0; padding: 0; }
+#feedback-box ul
+ { margin: 0.5em 0 0.7em 2em; padding: 0; }
+
+/*===================================================================*/
/* Link colors. */
a:link { background: transparent; color: #104060; }
Modified: trunk/epydoc/doc/index.html
===================================================================
--- trunk/epydoc/doc/index.html 2007-02-27 03:31:56 UTC (rev 1554)
+++ trunk/epydoc/doc/index.html 2007-02-27 04:00:10 UTC (rev 1555)
@@ -30,48 +30,50 @@
</div>
<!-- ================= Documentation ================= -->
-<div class="box">
+<div class="box" id="documentation-box">
<h2 class="box-title">Documentation</h2>
<table class="transparent" cellpadding="0">
<tr valign="top"><td class="transparent">
-<p><b>Using Epydoc</b>
-<ul class="nomargin">
- <li><a href="epydoc.html">Epydoc manual</a> </li>
- <li><a href="faq.html">Frequently Asked Questions</a>
- <li><a href="api/">API Documentation</a></li>
-</ul></p>
-
-<p><b>Manual Chapters</b>
-<ul class="nomargin">
+<p class="small-top-margin no-bot-margin"
+><b><a href="epydoc.html">Epydoc manual</a></b></p>
+<ul id="epydoc-manual">
<li> <a href="manual-install.html">Installing Epydoc</a> </li>
<li> <a href="manual-usage.html">Using Epydoc</a> </li>
<li> <a href="manual-docstrings.html">Python Docstrings</a> </li>
<li> <a href="manual-epytext.html">The Epytext Markup Language</a> </li>
<li> <a href="manual-fields.html">Epydoc Fields</a> </li>
- <li> <a href="manual-othermarkup.html">reStructuredText and Javadoc</a> </li>
- <li> <a href="manual-reference.html">References</a> </li>
-</ul></p>
+ <li> <a href="manual-othermarkup.html">reStructuredText and
+ Javadoc</a> </li>
+ <li><a href="manual-reference.html">Reference Documentation</a></li>
+</ul>
</td><td class="transparent">
-<p><b>Related Information</b>
-<ul class="nomargin">
+<p class="small-top-margin no-bot-margin"><b>Related Information</b></p>
+<ul id="related-information">
<li> <a href="license.html">Open Source License</a></li>
<li> <a href="whatsnew.html">Change Log</a></li>
<li> <a href="history.html">History</a> </li>
<li> <a href="future.html">Future Directions</a> </li>
<li> <a href="relatedprojects.html">Related Projects</a> </li>
<li> <a href="doctest/index.html">Regression Tests</a> </li>
-</ul></p>
+</ul>
-</tr></table>
+</td></tr><tr valign="top"><td class="transparent">
+<p><b><a href="api/">API
+Documentation</a></b></p>
+</td><td class="transparent">
+<p><b><a href="faq.html">Frequently Asked
+Questions</a></b></p>
+</td></tr></table>
+
</div>
<!-- ================= Documentation ================= -->
-<div class="box">
+<div class="box" id="feedback-box">
<h2 class="box-title">Feedback</h2>
<ul>
<li> <a
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-27 03:31:58
|
Revision: 1554
http://svn.sourceforge.net/epydoc/?rev=1554&view=rev
Author: edloper
Date: 2007-02-26 19:31:56 -0800 (Mon, 26 Feb 2007)
Log Message:
-----------
- Various formatting & css changes for the manual
- Added navbar to the bottom of generated manual html pages
Modified Paths:
--------------
trunk/epydoc/Makefile
trunk/epydoc/doc/custom.css
trunk/epydoc/doc/manual-fields.txt
trunk/epydoc/doc/manual-usage.txt
trunk/epydoc/doc/manual.txt
Added Paths:
-----------
trunk/epydoc/doc/rst-template.txt
trunk/epydoc/doc/rst-template2.txt
Modified: trunk/epydoc/Makefile
===================================================================
--- trunk/epydoc/Makefile 2007-02-27 00:07:56 UTC (rev 1553)
+++ trunk/epydoc/Makefile 2007-02-27 03:31:56 UTC (rev 1554)
@@ -111,14 +111,13 @@
manual-html: $(MANUAL_HTML_FILES)
$(HTML_MANUAL)/epydoc.html: doc/manual.txt $(MANUAL_SRC)
- $(RST2HTML) doc/manual.txt $@
+ $(RST2HTML) doc/manual.txt $@ --template=doc/rst-template.txt
$(HTML_MANUAL)/manual-%.html: doc/manual-%.txt
- echo .. contents:: > doc/tmp.txt
- echo .. include:: ../$< >> doc/tmp.txt
+ echo ".. include:: ../$<" > doc/tmp.txt
$(MKDISPATCH) $(MANUAL_SRC) >> doc/tmp.txt
- $(RST2HTML) doc/tmp.txt $@
-
+ $(RST2HTML) doc/tmp.txt $@ --template=doc/rst-template.txt
+
checkdoc: checkdocs
checkdocs:
epydoc --check --tests=vars,types $(PY_SRC)
@@ -166,7 +165,8 @@
mkdir -p $(HTML_DOCTEST)
$(HTML_DOCTEST)/%.html: src/epydoc/test/%.doctest
mkdir -p $(HTML_DOCTEST)
- $(RST2HTML) --stylesheet=../custom.css $< $@
+ $(RST2HTML) --stylesheet=../custom.css $< $@ \
+ --template=doc/rst-template2.txt
examples: .examples.up2date
.examples.up2date: $(EXAMPLES_SRC) $(PY_SRCFILES)
Modified: trunk/epydoc/doc/custom.css
===================================================================
--- trunk/epydoc/doc/custom.css 2007-02-27 00:07:56 UTC (rev 1553)
+++ trunk/epydoc/doc/custom.css 2007-02-27 03:31:56 UTC (rev 1554)
@@ -7,13 +7,34 @@
@import url("docutils.css");
+/*===================================================================*/
+/* Navigation box */
+
+table.navbox {
+ border-right: 1px solid black;
+ border-left: 1px solid black;
+ border-bottom: 1px solid black;
+}
+td.nav {
+ border: 2px outset #70b0ff;
+ background: #70b0ff; color: black;
+ font-weight: bold;
+}
+td.navselect {
+ background: #4888d8; color: white;
+}
+
+a.nav:link { text-decoration: none; }
+a.nav:visited { text-decoration: none; }
+
/*======================================================================*/
/* Source code colorization */
pre.py-doctest { padding: .5em; margin: 1em;
background: #e8f0f8; color: #000000;
border: 1px solid #708890; }
-table pre.py-doctest { background: #dce4ec;
- color: #000000; }
+table.docutils pre.py-doctest { background: #dce4ec;
+ color: #000000;
+ border: 1px solid #708890; }
.py-prompt { color: #005050; font-weight: bold;}
.py-string { color: #006030; }
.py-comment { color: #003060; }
@@ -44,13 +65,85 @@
h1.title { font-size: 180%; font-weight: bold; text-align: center;
padding: .1em; margin: 0; border-bottom: 2px solid black;}
+h2.subtitle { font-size: 100%; text-align: center;
+ font-style: italic; font-weight: normal; margin-top: 0; }
+
pre.literal-block { padding: .5em; margin: 1em;
background: #e8f0f8; color: #000000;
border: 1px solid #708890; }
-table.docutils { background: #e8f0f8; border: 1px solid black; }
+table.docutils {
+ border: 1px solid black; background: #e8f0f8;
+ margin-top: 6px; border-collapse: collapse;
+}
+table.docutils th, table.docutils td {
+ border: 1px solid black;
+ padding: 0 .5em 0 .5em; }
table.docutils th { background: #70b0ff; }
+div.epydoc-usage { border: 1px solid #708890;
+ background: #e8f0f8; margin: 1em; padding: 0.5em}
+table.option-list { background: none !important; }
+table.option-list td { border: none !important; }
+
+div.note {
+ border: 1px solid black; background: #e8f0f8;
+ margin-top: 6px;
+ border-collapse: collapse;
+ padding: 0 10px 10px 10px;
+}
+div.note p.admonition-title {
+ background: #a0f0c0; margin: 0 -10px; padding: 6px 6px 3px 6px;
+ border-bottom: 1px solid black;
+ }
+
+#the-epytext-markup-language table.docutils { width: 95%; }
+
+table.docutils pre { border: 0px solid black; }
+
+div.note { }
+
+
+
/* For the "Sections" example in the manual */
p.h1 { font-size: 150%; font-weight: bold; }
p.h2 { font-size: 125%; font-weight: bold; }
+
+table.docinfo { margin: 0 0 0.5em 0; font-size: 90%; }
+
+div.abstract { margin: 0; padding: 0.5em 1em;
+ border: 1px solid black;
+ background: #e8f0f8; color: black; }
+div.abstract p { margin: 0; }
+div.abstract p.topic-title { display: none; }
+
+#contents {
+ background: #e8f0f8; color: black;
+ border: 1px solid #000000;
+ margin: 1em 0 1em 0;
+ padding: 0 10px 0 10px;
+}
+
+#contents p.topic-title {
+ background: #70b0ff;
+ text-align: center;
+ font-weight: bold;
+ font-size: 125%;
+ margin: 0 -10px 0 -10px;
+ padding: 0 10px 0 10px;
+ border-bottom: 1px solid black;
+}
+
+/*
+
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr><th class="docinfo-name">Author:</th>
+<td><a class="first last reference" href="mailto:edloper@gradient.cis.upenn.edu">Edward Loper</a></td></tr>
+<tr><th class="docinfo-name">Version:</th>
+<td>3.0b1</td></tr>
+</tbody>
+</table>
+<div class="abstract topic">*/
\ No newline at end of file
Modified: trunk/epydoc/doc/manual-fields.txt
===================================================================
--- trunk/epydoc/doc/manual-fields.txt 2007-02-27 00:07:56 UTC (rev 1553)
+++ trunk/epydoc/doc/manual-fields.txt 2007-02-27 03:31:56 UTC (rev 1554)
@@ -90,7 +90,7 @@
of function and methods. These tags are usually put in the the docstring of the
function to be documented.
-.. note:: constructor parameters
+.. note:: **constructor parameters**
In C extension modules, extension classes cannot have a docstring attached
to the ``__init__`` function; consequently it is not possible to document
@@ -210,7 +210,7 @@
"""
#[...]
-.. note:: group markers
+.. note:: **group markers**
It is also possible to group set of related items enclosing them
into special comment starting with the *group markers* '``#{``' and '``#}``'
Modified: trunk/epydoc/doc/manual-usage.txt
===================================================================
--- trunk/epydoc/doc/manual-usage.txt 2007-02-27 00:07:56 UTC (rev 1553)
+++ trunk/epydoc/doc/manual-usage.txt 2007-02-27 03:31:56 UTC (rev 1554)
@@ -39,66 +39,68 @@
as ``epydoc/epytext.py``), or package directory names (such as ``epydoc/``).
Packages are expanded to include all sub-modules and sub-packages.
---html
- Generate HTML output. (default)
---pdf
- Generate Adobe Acrobat (PDF) output, using LaTeX.
--o DIR, --output DIR, --target DIR
- The output directory.
---parse-only, --introspect-only
- By default, epydoc will gather information about each Python object using
- two methods: parsing the object's source code; and importing the object and
- directly introspecting it. Epydoc combines the information obtained from
- these two methods to provide more complete and accurate documentation.
- However, if you wish, you can tell epydoc to use only one or the other of
- these methods. For example, if you are running epydoc on untrusted code,
- you should use the ``--parse-only`` option.
--v, -q
- Increase (``-v``) or decrease (``-q``) the verbosity of the output. These
- options may be repeated to further increase or decrease verbosity.
- Docstring markup warnings are supressed unless ``-v`` is used at least once.
---name NAME
- The documented project's name.
---url URL
- The documented project's URL.
---docformat NAME
- The markup language that should be used by default to process modules'
- docstrings. This is only used for modules that do not define the special
- ``__docformat__`` variable; it is recommended that you explicitly specify
- ``__docformat__`` in all your modules.
---graph GRAPHTYPE
- 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. To include
- all graphs, use ``--graph all``. The available graph types are:
+.. container:: epydoc-usage
- * **classtree**: displays each class's base classes and subclasses;
- * **callgraph**: displays the callers and callees of each function or
- method. These graphs are based on profiling information, which must be
- specified using the ``--pstate`` option.
- * **umlclass**: displays each class's base classes and subclasses, using
- UML style. Methods and attributes are listed in the classes where they
- are defined. If type information is available about attributes (via the
- ``@type`` field), then those types are displayed as separate classes, and
- the attributes are displayed as associations.
---inheritance STYLE
- The format that should be used to display inherited methods, variables, and
- properties. Currently, three styles are supported. To see an example of each style,
- click on it:
-
- * grouped_: Inherited objects are gathered into groups, based on which
- class they are inherited from.
- * listed_: Inherited objects are listed in a short list at the end of the
- summary table.
- * included_: Inherited objects are mixed in with non-inherited objects.
-
---config FILE
- Read the given configuration file, which can contain both options and
- Python object names. This option may be used multiple times, if you wish
- to use multiple configuration files. See `Configuration Files`_ for more
- information.
-
+ --html
+ Generate HTML output. (default)
+ --pdf
+ Generate Adobe Acrobat (PDF) output, using LaTeX.
+ -o DIR, --output DIR, --target DIR
+ The output directory.
+ --parse-only, --introspect-only
+ By default, epydoc will gather information about each Python object using
+ two methods: parsing the object's source code; and importing the object and
+ directly introspecting it. Epydoc combines the information obtained from
+ these two methods to provide more complete and accurate documentation.
+ However, if you wish, you can tell epydoc to use only one or the other of
+ these methods. For example, if you are running epydoc on untrusted code,
+ you should use the ``--parse-only`` option.
+ -v, -q
+ Increase (``-v``) or decrease (``-q``) the verbosity of the output. These
+ options may be repeated to further increase or decrease verbosity.
+ Docstring markup warnings are supressed unless ``-v`` is used at least once.
+ --name NAME
+ The documented project's name.
+ --url URL
+ The documented project's URL.
+ --docformat NAME
+ The markup language that should be used by default to process modules'
+ docstrings. This is only used for modules that do not define the special
+ ``__docformat__`` variable; it is recommended that you explicitly specify
+ ``__docformat__`` in all your modules.
+ --graph GRAPHTYPE
+ 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. To include
+ all graphs, use ``--graph all``. The available graph types are:
+
+ * **classtree**: displays each class's base classes and subclasses;
+ * **callgraph**: displays the callers and callees of each function or
+ method. These graphs are based on profiling information, which must be
+ specified using the ``--pstate`` option.
+ * **umlclass**: displays each class's base classes and subclasses, using
+ UML style. Methods and attributes are listed in the classes where they
+ are defined. If type information is available about attributes (via the
+ ``@type`` field), then those types are displayed as separate classes, and
+ the attributes are displayed as associations.
+ --inheritance STYLE
+ The format that should be used to display inherited methods, variables, and
+ properties. Currently, three styles are supported. To see an example of each style,
+ click on it:
+
+ * grouped_: Inherited objects are gathered into groups, based on which
+ class they are inherited from.
+ * listed_: Inherited objects are listed in a short list at the end of the
+ summary table.
+ * included_: Inherited objects are mixed in with non-inherited objects.
+
+ --config FILE
+ Read the given configuration file, which can contain both options and
+ Python object names. This option may be used multiple times, if you wish
+ to use multiple configuration files. See `Configuration Files`_ for more
+ information.
+
.. _grouped: http://epydoc.sourceforge.net/examples/grouped/
inh_example.Programmer-class.html
.. _listed: http://epydoc.sourceforge.net/examples/listed/
Modified: trunk/epydoc/doc/manual.txt
===================================================================
--- trunk/epydoc/doc/manual.txt 2007-02-27 00:07:56 UTC (rev 1553)
+++ trunk/epydoc/doc/manual.txt 2007-02-27 03:31:56 UTC (rev 1554)
@@ -32,6 +32,7 @@
.. contents::
.. section-numbering::
+.. def:: singlepage
.. Include the document chapters
Added: trunk/epydoc/doc/rst-template.txt
===================================================================
--- trunk/epydoc/doc/rst-template.txt (rev 0)
+++ trunk/epydoc/doc/rst-template.txt 2007-02-27 03:31:56 UTC (rev 1554)
@@ -0,0 +1,36 @@
+%(head_prefix)s
+%(head)s
+%(stylesheet)s
+%(body_prefix)s
+%(body_pre_docinfo)s
+%(docinfo)s
+%(body)s
+</div>
+<table width="100%%" class="navbox" cellpadding="1" cellspacing="0">
+ <tr>
+ <a class="nav" href="index.html">
+ <td align="center" width="20%%" class="nav">
+ <a class="nav" href="index.html">
+ Home</a></td></a>
+ <a class="nav" href="installing.html">
+ <td align="center" width="20%%" class="nav">
+ <a class="nav" href="installing.html">
+ Installing Epydoc</a></td></a>
+ <a class="nav" href="using.html">
+ <td align="center" width="20%%" class="nav">
+ <a class="nav" href="using.html">
+ Using Epydoc</a></td></a>
+ <a class="nav" href="epytext.html">
+ <td align="center" width="20%%" class="nav">
+ <a class="nav" href="epytext.html">
+ Epytext</a></td></a>
+ <td align="center" width="20%%" class="nav">
+
+ <A href="http://sourceforge.net/projects/epydoc">
+ <IMG src="sflogo.png"
+ width="88" height="26" border="0" alt="SourceForge"
+ align="top"/></A></td>
+ </tr>
+</table>
+</body>
+</html>
Added: trunk/epydoc/doc/rst-template2.txt
===================================================================
--- trunk/epydoc/doc/rst-template2.txt (rev 0)
+++ trunk/epydoc/doc/rst-template2.txt 2007-02-27 03:31:56 UTC (rev 1554)
@@ -0,0 +1,36 @@
+%(head_prefix)s
+%(head)s
+%(stylesheet)s
+%(body_prefix)s
+%(body_pre_docinfo)s
+%(docinfo)s
+%(body)s
+</div>
+<table width="100%%" class="navbox" cellpadding="1" cellspacing="0">
+ <tr>
+ <a class="nav" href="../index.html">
+ <td align="center" width="20%%" class="nav">
+ <a class="nav" href="../index.html">
+ Home</a></td></a>
+ <a class="nav" href="../installing.html">
+ <td align="center" width="20%%" class="nav">
+ <a class="nav" href="../installing.html">
+ Installing Epydoc</a></td></a>
+ <a class="nav" href="../using.html">
+ <td align="center" width="20%%" class="nav">
+ <a class="nav" href="../using.html">
+ Using Epydoc</a></td></a>
+ <a class="nav" href="../epytext.html">
+ <td align="center" width="20%%" class="nav">
+ <a class="nav" href="../epytext.html">
+ Epytext</a></td></a>
+ <td align="center" width="20%%" class="nav">
+
+ <A href="http://sourceforge.net/projects/epydoc">
+ <IMG src="../sflogo.png"
+ width="88" height="26" border="0" alt="SourceForge"
+ align="top"/></A></td>
+ </tr>
+</table>
+</body>
+</html>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-27 00:07:58
|
Revision: 1553
http://svn.sourceforge.net/epydoc/?rev=1553&view=rev
Author: edloper
Date: 2007-02-26 16:07:56 -0800 (Mon, 26 Feb 2007)
Log Message:
-----------
- VariableDoc's containing routines with overrides != None should
return true for is_detailed()
Modified Paths:
--------------
trunk/epydoc/src/epydoc/apidoc.py
Modified: trunk/epydoc/src/epydoc/apidoc.py
===================================================================
--- trunk/epydoc/src/epydoc/apidoc.py 2007-02-26 23:12:41 UTC (rev 1552)
+++ trunk/epydoc/src/epydoc/apidoc.py 2007-02-27 00:07:56 UTC (rev 1553)
@@ -681,6 +681,10 @@
if pval or self.value in (None, UNKNOWN):
return pval
+ if (self.overrides not in (None, UNKNOWN) and
+ isinstance(self.value, RoutineDoc)):
+ return True
+
if isinstance(self.value, GenericValueDoc):
# [XX] This is a little hackish -- we assume that the
# summary lines will have SUMMARY_REPR_LINELEN chars,
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-26 23:12:44
|
Revision: 1552
http://svn.sourceforge.net/epydoc/?rev=1552&view=rev
Author: edloper
Date: 2007-02-26 15:12:41 -0800 (Mon, 26 Feb 2007)
Log Message:
-----------
- Added missing import statements (SF bug 1669525)
Modified Paths:
--------------
trunk/epydoc/src/epydoc/markup/epytext.py
Modified: trunk/epydoc/src/epydoc/markup/epytext.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/epytext.py 2007-02-25 16:13:17 UTC (rev 1551)
+++ trunk/epydoc/src/epydoc/markup/epytext.py 2007-02-26 23:12:41 UTC (rev 1552)
@@ -1861,6 +1861,7 @@
from epydoc.docwriter.dotgraph import class_tree_graph
return class_tree_graph(bases, linker, context)
elif graph_type == 'packagetree':
+ from epydoc.apidoc import ModuleDoc
if graph_args:
packages = [docindex.find(name, context)
for name in graph_args]
@@ -1873,6 +1874,7 @@
from epydoc.docwriter.dotgraph import package_tree_graph
return package_tree_graph(packages, linker, context)
elif graph_type == 'importgraph':
+ from epydoc.apidoc import ModuleDoc
modules = [d for d in docindex.root if isinstance(d, ModuleDoc)]
from epydoc.docwriter.dotgraph import import_graph
return import_graph(modules, docindex, linker, context)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-25 16:13:19
|
Revision: 1551
http://svn.sourceforge.net/epydoc/?rev=1551&view=rev
Author: dvarrazzo
Date: 2007-02-25 08:13:17 -0800 (Sun, 25 Feb 2007)
Log Message:
-----------
- Added :term: reST iterpreted text role to create indexed terms as X{...}
epytext markup.
Modified Paths:
--------------
trunk/epydoc/doc/manual-othermarkup.txt
trunk/epydoc/src/epydoc/markup/restructuredtext.py
Modified: trunk/epydoc/doc/manual-othermarkup.txt
===================================================================
--- trunk/epydoc/doc/manual-othermarkup.txt 2007-02-25 14:35:15 UTC (rev 1550)
+++ trunk/epydoc/doc/manual-othermarkup.txt 2007-02-25 16:13:17 UTC (rev 1551)
@@ -390,6 +390,41 @@
package with direct links to its API.
+Indexed Terms in reStructuredText
+'''''''''''''''''''''''''''''''''
+
+Epydoc uses `indexed terms`_ to create a table of terms definitions. Indexed
+terms are created using the epytext markup ``X{...}``.
+
+If you want to create indexed terms in reStructuredText modules,
+you can use the ``term`` `interpreted text role`_. For example:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ An :term:`index term` is a term that
+ should be included in the index.
+ """
+ #[...]
+
+ - An *index term* is a term that should be included in the index.
+
+ ============ ==============
+ Index
+ ===========================
+ index term *example*
+ x intercept *x_intercept*
+ y intercept *x_intercept*
+ ============ ==============
+
+
Javadoc
-------
Modified: trunk/epydoc/src/epydoc/markup/restructuredtext.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/restructuredtext.py 2007-02-25 14:35:15 UTC (rev 1550)
+++ trunk/epydoc/src/epydoc/markup/restructuredtext.py 2007-02-25 16:13:17 UTC (rev 1551)
@@ -78,7 +78,7 @@
from docutils.nodes import NodeVisitor, Text, SkipChildren
from docutils.nodes import SkipNode, TreeCopyVisitor
from docutils.frontend import OptionParser
-from docutils.parsers.rst import directives
+from docutils.parsers.rst import directives, roles
import docutils.nodes
import docutils.transforms.frontmatter
import docutils.transforms
@@ -208,6 +208,11 @@
def __repr__(self): return '<ParsedRstDocstring: ...>'
+ def index_terms(self):
+ visitor = _TermsExtractor(self._document)
+ self._document.walkabout(visitor)
+ return visitor.terms
+
class _EpydocReader(ApiLinkReader):
"""
A reader that captures all errors that are generated by parsing,
@@ -318,6 +323,45 @@
def unknown_visit(self, node):
'Ignore all unknown nodes'
+class _TermsExtractor(NodeVisitor):
+ """
+ A docutils node visitor that extracts the terms from documentation.
+
+ Terms are created using the C{:term:} interpreted text role.
+ """
+ def __init__(self, document):
+ NodeVisitor.__init__(self, document)
+
+ self.terms = None
+ """
+ The terms currently found.
+ @type: C{list}
+ """
+
+ def visit_document(self, node):
+ self.terms = []
+ self._in_term = False
+
+ def visit_emphasis(self, node):
+ if 'term' in node.get('classes'):
+ self._in_term = True
+
+ def depart_emphasis(self, node):
+ if 'term' in node.get('classes'):
+ self._in_term = False
+
+ def visit_Text(self, node):
+ if self._in_term:
+ doc = self.document.copy()
+ doc[:] = [node.copy()]
+ self.terms.append(ParsedRstDocstring(doc))
+
+ def unknown_visit(self, node):
+ 'Ignore all unknown nodes'
+
+ def unknown_departure(self, node):
+ 'Ignore all unknown nodes'
+
class _SplitFieldsTranslator(NodeVisitor):
"""
A docutils translator that removes all fields from a document, and
@@ -653,6 +697,17 @@
directives.register_directive('python', python_code_directive)
+def term_role(name, rawtext, text, lineno, inliner,
+ options={}, content=[]):
+
+ text = docutils.utils.unescape(text)
+ node = docutils.nodes.emphasis(rawtext, text, **options)
+ node.attributes['classes'].append('term')
+
+ return [node], []
+
+roles.register_local_role('term', term_role)
+
######################################################################
#{ Graph Generation Directives
######################################################################
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-25 14:35:18
|
Revision: 1550
http://svn.sourceforge.net/epydoc/?rev=1550&view=rev
Author: dvarrazzo
Date: 2007-02-25 06:35:15 -0800 (Sun, 25 Feb 2007)
Log Message:
-----------
- Fixed --no-frames option: frames and relative links are really not generated.
- Don't generate links for toggle_private() when --no-private option is used.
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docwriter/html.py
Modified: trunk/epydoc/src/epydoc/docwriter/html.py
===================================================================
--- trunk/epydoc/src/epydoc/docwriter/html.py 2007-02-24 16:23:49 UTC (rev 1549)
+++ trunk/epydoc/src/epydoc/docwriter/html.py 2007-02-25 14:35:15 UTC (rev 1550)
@@ -429,8 +429,11 @@
for doc in self.module_list:
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) +
- 13 + len(self.METADATA_INDICES))
+ self._num_files = (len(self.class_list) + len(self.module_list) +
+ 10 + len(self.METADATA_INDICES))
+ if self._frames_index:
+ self._num_files += len(self.module_list) + 3
+
if self._incl_sourcecode:
self._num_files += len(self.modules_with_sourcecode)
if self._split_ident_index:
@@ -610,12 +613,13 @@
self._write(self.write_help, directory,'help.html')
# Write the frames-based table of contents.
- self._write(self.write_frames_index, directory, 'frames.html')
- self._write(self.write_toc, directory, 'toc.html')
- self._write(self.write_project_toc, directory, 'toc-everything.html')
- for doc in self.module_list:
- filename = 'toc-%s' % urllib.unquote(self.url(doc))
- self._write(self.write_module_toc, directory, filename, doc)
+ if self._frames_index:
+ self._write(self.write_frames_index, directory, 'frames.html')
+ self._write(self.write_toc, directory, 'toc.html')
+ self._write(self.write_project_toc, directory, 'toc-everything.html')
+ for doc in self.module_list:
+ filename = 'toc-%s' % urllib.unquote(self.url(doc))
+ self._write(self.write_module_toc, directory, filename, doc)
# Write the object documentation.
for doc in self.module_list:
@@ -1426,15 +1430,15 @@
for(var i=0; i<elts.length; i++) {
if (elts[i].className == "privatelink") {
cmd = elts[i].innerHTML;
- elts[i].innerHTML = ((cmd=="show private")?"hide private":
- "show private");
+ elts[i].innerHTML = ((cmd && cmd.substr(0,4)=="show")?
+ "hide private":"show private");
}
}
// Update all DIVs containing private objects.
var elts = document.getElementsByTagName("div");
for(var i=0; i<elts.length; i++) {
if (elts[i].className == "private") {
- elts[i].style.display = ((cmd=="hide private")?"none":"block");
+ elts[i].style.display = ((cmd && cmd.substr(0,4)=="hide")?"none":"block");
}
}
// Update all table rowss containing private objects. Note, we
@@ -1444,21 +1448,22 @@
var elts = document.getElementsByTagName("tr");
for(var i=0; i<elts.length; i++) {
if (elts[i].className == "private") {
- elts[i].style.display = ((cmd=="hide private")?"none":"");
+ elts[i].style.display = ((cmd && cmd.substr(0,4)=="hide")?"none":"");
}
}
// Update all list items containing private objects.
var elts = document.getElementsByTagName("li");
for(var i=0; i<elts.length; i++) {
if (elts[i].className == "private") {
- elts[i].style.display = ((cmd=="hide private")?"none":"list-item");
+ elts[i].style.display = ((cmd && cmd.substr(0,4)=="hide")?
+ "none":"list-item");
}
}
// Update all list items containing private objects.
var elts = document.getElementsByTagName("ul");
for(var i=0; i<elts.length; i++) {
if (elts[i].className == "private") {
- elts[i].style.display = ((cmd=="hide private")?"none":"block");
+ elts[i].style.display = ((cmd && cmd.substr(0,4)=="hide")?"none":"block");
}
}
// Set a cookie to remember the current option.
@@ -1503,7 +1508,7 @@
HIDE_PRIVATE_JS = '''
function checkCookie() {
var cmd=getCookie("EpydocPrivate");
- if (cmd!="show private" && location.href.indexOf("#_") < 0)
+ if (cmd && cmd.substr(0,4)!="show" && location.href.indexOf("#_") < 0)
toggle_private();
}
'''.strip()
@@ -1860,10 +1865,12 @@
>>> if self._show_private:
<tr><td align="right">$self.PRIVATE_LINK$</td></tr>
>>> #endif
+ >>> if self._frames_index:
<tr><td align="right"><span class="options"
>[<a href="frames.html" target="_top">frames</a
>] | <a href="$context_url$"
target="_top">no frames</a>]</span></td></tr>
+ >>> #endif
</table>
</td>
</tr>
@@ -3007,7 +3014,7 @@
cellspacing="0" width="100%" bgcolor="white">
>>> if heading is not None:
<tr bgcolor="#70b0f0" class="table-header">
- >>> if private_link:
+ >>> if private_link and self._show_private:
<td colspan="$colspan$" class="table-header">
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr valign="top">
@@ -3032,7 +3039,7 @@
PRIVATE_LINK = '''
<span class="options">[<a href="javascript:void(0);" class="privatelink"
- onclick="toggle_private();">hide private</a>]</span>
+ onclick="toggle_private();">hide private</a>]</span>
'''.strip()
write_group_header = compile_template(
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-24 16:23:51
|
Revision: 1549
http://svn.sourceforge.net/epydoc/?rev=1549&view=rev
Author: dvarrazzo
Date: 2007-02-24 08:23:49 -0800 (Sat, 24 Feb 2007)
Log Message:
-----------
- Fixed a couple of bugs in config file parsing
- Fixed config example for fail-on option
Modified Paths:
--------------
trunk/epydoc/doc/manual-reference.txt
trunk/epydoc/src/epydoc/cli.py
Modified: trunk/epydoc/doc/manual-reference.txt
===================================================================
--- trunk/epydoc/doc/manual-reference.txt 2007-02-22 00:25:40 UTC (rev 1548)
+++ trunk/epydoc/doc/manual-reference.txt 2007-02-24 16:23:49 UTC (rev 1549)
@@ -219,28 +219,28 @@
**### Output options**
*# The documented project's name.*
- **name: Example**
+ **#name: Example**
*# The CSS stylesheet for HTML output. Can be the name of a builtin*
*# stylesheet, or the name of a file.*
**css: white**
*# The documented project's URL.*
- **url: http://some.project/**
+ **#url: http://some.project/**
*# HTML code for the project link in the navigation bar. If left*
*# unspecified, the project link will be generated based on the*
*# project's name and URL.*
- **link: <a href="somewhere">My Cool Project</a>**
+ **#link: <a href="somewhere">My Cool Project</a>**
*# The "top" page for the documentation. Can be a URL, the name*
*# of a module or class, or one of the special names "trees.html",*
*# "indices.html", or "help.html"*
- **top: os.path**
+ **#top: os.path**
*# An alternative help file. The named file should contain the*
*# body of an HTML file; navigation bars will be added to it.*
- **help: my_helpfile.html**
+ **#help: my_helpfile.html**
*# Whether or not to include a frames-based table of contents.*
**frames: yes**
@@ -283,27 +283,17 @@
*# (e.g., helvetica or times).*
**graph-font: Helvetica**
- *# Specify the font size used to generate Graphviz*
+ *# Specify the font size used to generate Graphviz graphs.*
**graph-font-size: 10**
**### Return value options**
- *# If true, return a non-zero exit status, indicating failure,*
- *# if any errors are encountered.*
- **fail-on-error: false**
+ *# The condition upon which Epydoc should exit with a non-zero*
+ *# exit status. Possible values are error, warning, docstring_warning*
+ **#fail-on: error**
- *# If true, return a non-zero exit status, indicating failure,*
- *# if any errors or warnings are encountered (not including*
- *# docstring warnings).*
- **fail-on-warning: false**
-
- *# Return a non-zero exit status, indicating failure, if any*
- *# errors or warnings are encountered (including docstring*
- *# warnings).*
- **fail-on-docstring-warning: false**
-
Warnings and Errors
-------------------
Modified: trunk/epydoc/src/epydoc/cli.py
===================================================================
--- trunk/epydoc/src/epydoc/cli.py 2007-02-22 00:25:40 UTC (rev 1548)
+++ trunk/epydoc/src/epydoc/cli.py 2007-02-24 16:23:49 UTC (rev 1549)
@@ -587,18 +587,18 @@
elif optname in ('graph-font', 'graph_font'):
options.graph_font = val
elif optname in ('graph-font-size', 'graph_font_size'):
- options.graph_font_size = _str_to_int(val)
+ options.graph_font_size = _str_to_int(val, optname)
elif optname == 'pstat':
options.pstat_files.extend(val.replace(',', ' ').split())
# Return value options
elif optname in ('failon', 'fail-on', 'fail_on'):
- if val.lower.strip() in ('error', 'errors'):
+ if val.lower().strip() in ('error', 'errors'):
options.fail_on = log.ERROR
- elif val.lower.strip() in ('warning', 'warnings'):
+ elif val.lower().strip() in ('warning', 'warnings'):
options.fail_on = log.WARNING
- elif val.lower.strip() in ('docstring_warning',
- 'docstring_warnings'):
+ elif val.lower().strip() in ('docstring_warning',
+ 'docstring_warnings'):
options.fail_on = log.DOCSTRING_WARNING
else:
raise ValueError("%r expected one of: error, warning, "
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-22 00:25:44
|
Revision: 1548
http://svn.sourceforge.net/epydoc/?rev=1548&view=rev
Author: dvarrazzo
Date: 2007-02-21 16:25:40 -0800 (Wed, 21 Feb 2007)
Log Message:
-----------
- Some manual fixes
- Manual on the homepage.
Modified Paths:
--------------
trunk/epydoc/doc/index.html
trunk/epydoc/doc/manual-docstring.txt
trunk/epydoc/doc/manual-fields.txt
trunk/epydoc/doc/manual.txt
Modified: trunk/epydoc/doc/index.html
===================================================================
--- trunk/epydoc/doc/index.html 2007-02-21 17:34:54 UTC (rev 1547)
+++ trunk/epydoc/doc/index.html 2007-02-22 00:25:40 UTC (rev 1548)
@@ -38,20 +38,20 @@
<p><b>Using Epydoc</b>
<ul class="nomargin">
- <li><a href="installing.html">Installing Epydoc</a> </li>
- <li><a href="using.html">Using Epydoc</a> </li>
+ <li><a href="epydoc.html">Epydoc manual</a> </li>
<li><a href="faq.html">Frequently Asked Questions</a>
<li><a href="api/">API Documentation</a></li>
</ul></p>
-<p><b>Docstring Markup</b>
+<p><b>Manual Chapters</b>
<ul class="nomargin">
- <li> <a href="docstrings.html">Python Docstrings</a> </li>
- <li> <a href="epytextintro.html">Introduction to
- Epytext Markup</a> </li>
- <li> <a href="epytext.html">Epytext Markup Language Manual</a> </li>
- <li> <a href="othermarkup.html">ReStructuredText and Javadoc</a> </li>
- <li> <a href="fields.html">Epydoc Fields</a> </li>
+ <li> <a href="manual-install.html">Installing Epydoc</a> </li>
+ <li> <a href="manual-usage.html">Using Epydoc</a> </li>
+ <li> <a href="manual-docstrings.html">Python Docstrings</a> </li>
+ <li> <a href="manual-epytext.html">The Epytext Markup Language</a> </li>
+ <li> <a href="manual-fields.html">Epydoc Fields</a> </li>
+ <li> <a href="manual-othermarkup.html">reStructuredText and Javadoc</a> </li>
+ <li> <a href="manual-reference.html">References</a> </li>
</ul></p>
</td><td class="transparent">
Modified: trunk/epydoc/doc/manual-docstring.txt
===================================================================
--- trunk/epydoc/doc/manual-docstring.txt 2007-02-21 17:34:54 UTC (rev 1547)
+++ trunk/epydoc/doc/manual-docstring.txt 2007-02-22 00:25:40 UTC (rev 1548)
@@ -1,66 +1,72 @@
-Docstrings and coding issues
-============================
+Python Docstrings
+=================
.. $Id$
-..
- This paragraph is introdictory: this chapter should explain advanced details.
+Python documentation strings (or *docstrings*) provide a convenient way of
+associating documentation with Python modules, functions, classes, and methods.
+An object's docsting is defined by including a string constant as the first
+statement in the object's definition. For example, the following function
+defines a docstring:
+.. python::
- Python docstrings
- -----------------
+ def x_intercept(m, b):
+ """
+ Return the x intercept of the line y=m*x+b. The x intercept of a
+ line is the point at which it crosses the x axis (y=0).
+ """
+ return -b/m
- Docstrings are a standard method that can be used by Python developers to
- attach documentation pieces to most Python objects.
+Docstrings can be accessed from the interpreter and from Python programs
+using the "``__doc__``" attribute:
- Here is an example module showing different docstrings:
+.. python::
- .. python::
+ >>> print x_intercept.__doc__
+ Return the x intercept of the line y=m*x+b. The x intercept of a
+ line is the point at which it crosses the x axis (y=0).
- #!/usr/bin/python
- # -*- coding: latin-1 -*-
- """A Sample Module.
+The pydoc_ module, which became part of `the standard library`__ in Python 2.1,
+can be used to display information about a Python object, including its
+docstring:
- The first string in the module, starting after the *hashbang* and the
- encoding definition comment, is the module docstring.
- """
+.. _pydoc: http://web.lfw.org/python/pydoc.html
+.. __: http://www.python.org/doc/current/lib/module-pydoc.html
- class Foo:
- """
- This is a testing class.
+.. python::
- It doesn't do much stuff, but it's pretty documented. This, for
- example, is the class docstring.
- """
+ >>> from pydoc import help
- def getMagic(self):
- """
- A function returning a magic number.
+ >>> help(x_intercept)
+ Help on function x_intercept in module __main__:
- This is the function documentation.
- """
- return 42
+ x_intercept(m, b)
+ Return the x intercept of the line y=m*x+b. The x intercept of a
+ line is the point at which it crosses the x axis (y=0).
- the_number = property(
- fget=getMagic,
- doc="""This is the property docstring.""")
+For more information about Python docstrings, see the `Python Tutorial`__ or
+the O'Reilly Network article `Python Documentation Tips and Tricks`__.
- Some guidelines for docstring standardization have been published, see for
- example :PEP:`257` for some higl-level convention. No docstring structure
- is enforced anyway by official documentation.
+.. __: http://www.python.org/doc/current/tut/node6.html#docstrings
+.. __: http://www.onlamp.com/lpt/a/python/2001/05/17/docstrings.html
Variable docstrings
-------------------
-Python variables don't support docstrings. The variable can be described in the
-module or class where it is defined using the tags ``@var``, ``@ivar``,
-``@cvar``; but this only allows for a textual description: no further metadata
-can be added to the variable (except for the type, using the ``@type`` tag).
+..
+ [xx] this should be somewhere else, i guess...
-Epydoc supports *variable docstrings*: 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
+Python don't support directly docstrings on variables: there is no attribute
+that can be attached to variables and retrieved interactively like the
+``__doc__`` attribute on modules, classes and functions.
+
+While the language doesn't directly provides for them, Epydoc supports
+*variable docstrings*: 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 (``__init__``) are considered instance variables:
.. python::
@@ -84,21 +90,8 @@
x = 22
x = 22 #: docstring for x
-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 ``@ivar`` in the context of a variable
-docstring:
-
-.. python::
-
- class B:
- y = 42
- """@ivar: This is an instance variable."""
-
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.
Items visibility
Modified: trunk/epydoc/doc/manual-fields.txt
===================================================================
--- trunk/epydoc/doc/manual-fields.txt 2007-02-21 17:34:54 UTC (rev 1547)
+++ trunk/epydoc/doc/manual-fields.txt 2007-02-22 00:25:40 UTC (rev 1548)
@@ -1,4 +1,4 @@
-Epydoc fields
+Epydoc Fields
=============
.. $Id$
@@ -149,11 +149,26 @@
``@type`` *v*: ...
The type of the variable *v*.
-These tags are usually put in a module or class docstring. If fthe sources can
+These tags are usually put in a module or class docstring. If the sources can
be parsed by Epydoc it is also possible to document the variable in their own
docstrings: see `variable docstrings`_
+Epydoc considers class variables the ones defined directly defined in the
+class body. 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...).
+If you want to force Epydoc to classify as instance variable one whose default
+value is set at class level, you can describe it using the tag ``@ivar`` in the
+context of a variable docstring:
+
+.. python::
+
+ class B:
+ y = 42
+ """@ivar: This is an instance variable."""
+
+
Properties parameters
'''''''''''''''''''''
Modified: trunk/epydoc/doc/manual.txt
===================================================================
--- trunk/epydoc/doc/manual.txt 2007-02-21 17:34:54 UTC (rev 1547)
+++ trunk/epydoc/doc/manual.txt 2007-02-22 00:25:40 UTC (rev 1548)
@@ -9,9 +9,7 @@
:Author: `Edward Loper <ed...@gr...>`__
-:Data: $Date$
-:Versione: 3.0b1
-:Revisione: $Revision$
+:Version: 3.0b1
:Abstract:
Epydoc is a tool for generating API documentation for Python modules,
@@ -40,8 +38,8 @@
.. include:: manual-install.txt
.. include:: manual-usage.txt
+.. include:: manual-docstring.txt
.. include:: manual-epytext.txt
.. include:: manual-fields.txt
.. include:: manual-othermarkup.txt
-.. include:: manual-docstring.txt
.. include:: manual-reference.txt
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-21 17:34:58
|
Revision: 1547
http://svn.sourceforge.net/epydoc/?rev=1547&view=rev
Author: dvarrazzo
Date: 2007-02-21 09:34:54 -0800 (Wed, 21 Feb 2007)
Log Message:
-----------
- The manual can be created both as a single document and many pages.
The single chapters may be linked from the homepage.
Modified Paths:
--------------
trunk/epydoc/Makefile
trunk/epydoc/doc/manual-epytext.txt
trunk/epydoc/doc/manual-othermarkup.txt
trunk/epydoc/doc/manual-reference.txt
trunk/epydoc/doc/manual.txt
trunk/epydoc/src/tools/rst2html.py
Added Paths:
-----------
trunk/epydoc/src/tools/mkdispatch.py
Property Changed:
----------------
trunk/epydoc/doc/
Modified: trunk/epydoc/Makefile
===================================================================
--- trunk/epydoc/Makefile 2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/Makefile 2007-02-21 17:34:54 UTC (rev 1547)
@@ -14,7 +14,7 @@
EXAMPLES_SRC = $(wildcard doc/*.py)
DOCS = $(wildcard doc/*)
DOCTESTS = $(wildcard src/epydoc/test/*.doctest)
-MANUAL_SRC = $(wildcard doc/manual*.txt)
+MANUAL_SRC = $(wildcard doc/manual-*.txt)
# What version of python to use?
PYTHON = python
@@ -32,6 +32,7 @@
HTML = html
# Output subdirectories
+HTML_MANUAL = $(HTML)
HTML_API = $(HTML)/api
HTML_EXAMPLES = $(HTML)/examples
HTML_STDLIB = $(HTML)/stdlib
@@ -44,12 +45,13 @@
# Options for rst->html converter
RST2HTML = $(PYTHON) src/tools/rst2html.py
+MKDISPATCH = $(PYTHON) src/tools/mkdispatch.py
DOCTEST_HTML_FILES := \
$(DOCTESTS:src/epydoc/test/%.doctest=$(HTML_DOCTEST)/%.html)
-manual-html: $(MANUAL_SRC)
- $(RST2HTML) doc/manual.txt $(HTML)/epydoc.html
+MANUAL_HTML_FILES := $(HTML_MANUAL)/epydoc.html \
+ $(MANUAL_SRC:doc/manual-%.txt=$(HTML_MANUAL)/manual-%.html)
##//////////////////////////////////////////////////////////////////////
## Usage
@@ -106,16 +108,29 @@
rm -rf /var/www/epydoc/*
cp -r $(WEBDIR)/* /var/www/epydoc
+manual-html: $(MANUAL_HTML_FILES)
+
+$(HTML_MANUAL)/epydoc.html: doc/manual.txt $(MANUAL_SRC)
+ $(RST2HTML) doc/manual.txt $@
+
+$(HTML_MANUAL)/manual-%.html: doc/manual-%.txt
+ echo .. contents:: > doc/tmp.txt
+ echo .. include:: ../$< >> doc/tmp.txt
+ $(MKDISPATCH) $(MANUAL_SRC) >> doc/tmp.txt
+ $(RST2HTML) doc/tmp.txt $@
+
checkdoc: checkdocs
checkdocs:
epydoc --check --tests=vars,types $(PY_SRC)
.webpage.up2date: .api-html.up2date .examples.up2date .api-pdf.up2date \
$(DOCTEST_HTML_FILES) doc/epydoc-man.html \
- doc/epydocgui-man.html $(DOCS)
+ doc/epydocgui-man.html $(DOCS) $(MANUAL_HTML_FILES)
rm -rf $(WEBDIR)
mkdir -p $(WEBDIR)
cp -r $(DOCS) $(WEBDIR)
+ cp -r $(HTML_MANUAL)/epydoc.html $(WEBDIR)
+ cp -r $(HTML_MANUAL)/manual*.html $(WEBDIR)
cp -r $(HTML_API) $(WEBDIR)/api
cp -r $(HTML_EXAMPLES) $(WEBDIR)/examples
cp -r $(HTML_DOCTEST)/* $(WEBDIR)/doctest
@@ -151,7 +166,7 @@
mkdir -p $(HTML_DOCTEST)
$(HTML_DOCTEST)/%.html: src/epydoc/test/%.doctest
mkdir -p $(HTML_DOCTEST)
- $(RST2HTML) $< $@
+ $(RST2HTML) --stylesheet=../custom.css $< $@
examples: .examples.up2date
.examples.up2date: $(EXAMPLES_SRC) $(PY_SRCFILES)
Property changes on: trunk/epydoc/doc
___________________________________________________________________
Name: svn:ignore
- *-man.html
api
*.pyc
examples
+ *-man.html
api
*.pyc
tmp.txt
examples
Modified: trunk/epydoc/doc/manual-epytext.txt
===================================================================
--- trunk/epydoc/doc/manual-epytext.txt 2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/doc/manual-epytext.txt 2007-02-21 17:34:54 UTC (rev 1547)
@@ -3,9 +3,58 @@
.. $Id$
-Overview
---------
+A Brief Introduction
+--------------------
+Epytext is a simple lightweight markup language that lets you add formatting
+and structue to docstrings. Epydoc uses that formatting and structure to
+produce nicely formatted API documentation. The following example (which has
+an unusually high ratio of documentaiton to code) illustrates some of the
+basic features of epytext:
+
+.. python::
+
+ def x_intercept(m, b):
+ """
+ Return the x intercept of the line M{y=m*x+b}. The X{x intercept}
+ of a line is the point at which it crosses the x axis (M{y=0}).
+
+ This function can be used in conjuction with L{z_transform} to
+ find an arbitrary function's zeros.
+
+ @type m: number
+ @param m: The slope of the line.
+ @type b: number
+ @param b: The y intercept of the line. The X{y intercept} of a
+ line is the point at which it crosses the y axis (M{x=0}).
+ @rtype: number
+ @return: the x intercept of the line M{y=m*x+b}.
+ """
+ return -b/m
+
+You can compare this function definition with the `API documentation`__
+generated by epydoc. Note that:
+
+* Paragraphs are separated by blank lines.
+* Inline markup has the form "*x*\ ``{``\ ...\ ``}``", where "*x*" is a
+ single capital letter. This example uses inline markup to mark mathematical
+ expressions ("``M{...}``"); terms that should be indexed ("``X{...}``");
+ and links to the documentation of other objects ("``L{...}``").
+* Descriptions of parameters, return values, and types are marked with
+ "``@``\ *field*\ ``:``" or "``@``\ *field arg*\ ``:``", where "*field*"
+ identifies the kind of description, and "*arg*" specifies what object is
+ described.
+
+.. __: http://epydoc.sourceforge.net/
+ examples/epytext_example-module.html#x_intercept
+
+Epytext is intentionally very lightweight. If you wish to use a more
+expressive markup language, I recommend reStructuredText_.
+
+
+Epytext Language Overview
+-------------------------
+
Epytext is a lightweight markup language for Python docstrings. The epytext
markup language is used by epydoc to parse docstrings and create structured API
documentation. Epytext markup is broken up into the following categories:
Modified: trunk/epydoc/doc/manual-othermarkup.txt
===================================================================
--- trunk/epydoc/doc/manual-othermarkup.txt 2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/doc/manual-othermarkup.txt 2007-02-21 17:34:54 UTC (rev 1547)
@@ -3,11 +3,13 @@
.. $Id$
-Epydoc's default markup language is epytext_, a lightweight markup language
+Epydoc's default markup language is epytext__, a lightweight markup language
that's easy to write and to understand. But if epytext is not powerful enough
for you, or doesn't suit your needs, epydoc also supports three alternate
markup languages:
+.. __: `The Epytext Markup Language`_
+
reStructuredText__
is an "easy-to-read, what-you-see-is-what-you-get plaintext markup syntax".
It is more powerful than epytext (e.g., it includes markup for tables and
Modified: trunk/epydoc/doc/manual-reference.txt
===================================================================
--- trunk/epydoc/doc/manual-reference.txt 2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/doc/manual-reference.txt 2007-02-21 17:34:54 UTC (rev 1547)
@@ -140,6 +140,8 @@
various options that you can set. Lines beginning with ``#`` or ``;`` are
treated as comments.
+.. _ConfigParser: http://docs.python.org/lib/module-ConfigParser.html
+
.. parsed-literal::
**[epydoc]** *# Epydoc section marker (required by ConfigParser)*
Modified: trunk/epydoc/doc/manual.txt
===================================================================
--- trunk/epydoc/doc/manual.txt 2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/doc/manual.txt 2007-02-21 17:34:54 UTC (rev 1547)
@@ -25,7 +25,7 @@
.. _html: http://epydoc.sourceforge.net/api/
.. _pdf: http://epydoc.sourceforge.net/epydoc.pdf
-.. _epytext: http://epydoc.sourceforge.net/epytextintro.html
+.. _epytext: `The Epytext Markup Language`_
.. _reStructuredText:
http://docutils.sourceforge.net/rst.html
.. _JavaDoc: http://java.sun.com/j2se/javadoc/
Added: trunk/epydoc/src/tools/mkdispatch.py
===================================================================
--- trunk/epydoc/src/tools/mkdispatch.py (rev 0)
+++ trunk/epydoc/src/tools/mkdispatch.py 2007-02-21 17:34:54 UTC (rev 1547)
@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+# -*- coding: iso-8859-1 -*-
+"""A tool to allow creation of both single page and multi-page manual.
+
+For each file name in argv, detect title names and print a directive
+referring to it as anchor in an html file.
+"""
+
+# $Id$
+__version__ = "$Revision$"[11:-2]
+__author__ = "Daniele Varrazzo"
+__copyright__ = "Copyright (C) 2007 by Daniele Varrazzo"
+
+import sys, os
+
+def parse_pairs(fn):
+ """Parse a file and return a list of directives to create links."""
+ outfile = os.path.splitext(os.path.split(fn)[1])[0] + '.html'
+ rv = []
+ prev = None
+ for curr in open(fn):
+ curr = curr.rstrip()
+ if prev is not None:
+ if curr and curr[0] in "'^-=~":
+ if curr == curr[0] * len(curr):
+ rv.append(".. _%s: %s#%s" %
+ (prev, outfile, get_anchor(prev)))
+ prev = curr
+
+ return rv
+
+import string
+charmap = {}
+charmap.update(zip(string.ascii_lowercase, string.ascii_lowercase))
+charmap.update(zip(string.ascii_uppercase, string.ascii_lowercase))
+charmap[' '] = '-'
+for k in '()':
+ charmap[k] = ''
+
+def get_anchor(s):
+ # IndexErrors are expected to test for what else include in the map
+ return "".join(map(charmap.__getitem__, s))
+
+if __name__ == '__main__':
+ for fn in sys.argv[1:]:
+ for dir in parse_pairs(fn):
+ print dir
+
Property changes on: trunk/epydoc/src/tools/mkdispatch.py
___________________________________________________________________
Name: svn:executable
+ *
Name: svn:keywords
+ Id Revision
Name: svn:eol-style
+ native
Modified: trunk/epydoc/src/tools/rst2html.py
===================================================================
--- trunk/epydoc/src/tools/rst2html.py 2007-02-20 23:51:34 UTC (rev 1546)
+++ trunk/epydoc/src/tools/rst2html.py 2007-02-21 17:34:54 UTC (rev 1547)
@@ -32,9 +32,9 @@
class CustomizedHTMLWriter(HTMLWriter):
settings_defaults = (HTMLWriter.settings_defaults or {}).copy()
settings_defaults.update({
- 'stylesheet_path': os.path.normpath(os.path.join(
- os.path.split(__file__)[0], '../../doc/custom.css')),
- 'output_encoding': 'ascii',
+ 'stylesheet': 'custom.css',
+ 'stylesheet_path': None,
+ 'output_encoding': 'ascii',
'output_encoding_error_handler': 'xmlcharrefreplace',
'embed_stylesheet': False,
})
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-20 23:51:38
|
Revision: 1546
http://svn.sourceforge.net/epydoc/?rev=1546&view=rev
Author: dvarrazzo
Date: 2007-02-20 15:51:34 -0800 (Tue, 20 Feb 2007)
Log Message:
-----------
- Added reST and javadoc markups to documentation
- Confug file example updated
Modified Paths:
--------------
trunk/epydoc/doc/manual-epytext.txt
trunk/epydoc/doc/manual-reference.txt
trunk/epydoc/doc/manual-usage.txt
trunk/epydoc/doc/manual.txt
Added Paths:
-----------
trunk/epydoc/doc/manual-othermarkup.txt
Modified: trunk/epydoc/doc/manual-epytext.txt
===================================================================
--- trunk/epydoc/doc/manual-epytext.txt 2007-02-20 19:34:01 UTC (rev 1545)
+++ trunk/epydoc/doc/manual-epytext.txt 2007-02-20 23:51:34 UTC (rev 1546)
@@ -51,10 +51,10 @@
.. list-table::
:header-rows: 1
- * - Docstring Input
- - Rendered Output
+ * - Docstring Input
+ - Rendered Output
- * - .. python::
+ * - .. python::
def example():
"""
@@ -67,11 +67,11 @@
"""
*[...]*
- - This is a paragraph. Paragraphs can span multiple lines,
+ - This is a paragraph. Paragraphs can span multiple lines,
and contain *inline markup*.
This is another paragraph. Paragraphs are separated from each
- other by blank lines.
+ other by blank lines.
Lists
'''''
Added: trunk/epydoc/doc/manual-othermarkup.txt
===================================================================
--- trunk/epydoc/doc/manual-othermarkup.txt (rev 0)
+++ trunk/epydoc/doc/manual-othermarkup.txt 2007-02-20 23:51:34 UTC (rev 1546)
@@ -0,0 +1,419 @@
+Alternate Markup Languages
+==========================
+
+.. $Id$
+
+Epydoc's default markup language is epytext_, a lightweight markup language
+that's easy to write and to understand. But if epytext is not powerful enough
+for you, or doesn't suit your needs, epydoc also supports three alternate
+markup languages:
+
+reStructuredText__
+ is an "easy-to-read, what-you-see-is-what-you-get plaintext markup syntax".
+ It is more powerful than epytext (e.g., it includes markup for tables and
+ footnotes); but it is also more complex, and sometimes harder to read.
+
+ .. __: http://docutils.sourceforge.net/rst.html
+
+Javadoc__
+ is a documentation markup language that was developed for Java. It consists
+ of HTML, augmented by a set of special tagged fields.
+
+ .. __: http://java.sun.com/j2se/javadoc/
+
+Plaintext docstrings
+ are rendered verbatim (preserving whitespace).
+
+To specify the markup language for a module, you should define a module-level
+string variable ``__docformat__``, containing the name of the module's markup
+language. The name of the markup language may optionally be followed by a
+language code (such as ``en`` for English). Conventionally, the definition of
+the ``__docformat__`` variable immediately follows the module's docstring:
+
+.. python::
+
+ # widget.py
+ """
+ Graphical support for `gizmos` and `widgets`.
+ """
+ __docformat__ = "restructuredtext en"
+ #[...]
+
+To change the default markup language from the command line, use the
+``--docformat`` option. For example, the following command generates API
+documentation for the existing regular expression package ``re``, which uses
+plaintext markup::
+
+ [epydoc]$ epydoc --docformat plaintext re
+
+
+reStructuredText
+----------------
+
+reStructuredText is a markup language that was developed in conjunction with
+Docutils_. In order to parse reStructuredText docstrings, Docutils 0.3 or
+higher must be installed. If Docutils is not installed, then reStructuredText
+docstrings will be rendered as plaintext. Docutils can be downloaded from the
+`Docutils SourceForge page`_.
+
+.. _Docutils: http://docutils.sourceforge.net/
+.. _Docutils SourceForge page:
+ http://sourceforge.net/project/showfiles.php?group_id=38414
+
+
+Default role
+''''''''''''
+
+Epydoc replaces the Docutils' default `interpreted text role`_ with
+the creation of `documentation crossreference links`_. If you want to create
+a crossreference link to the ``somemod.Example`` class, you can put backquotes
+around your test, typing::
+
+ `somemod.Example`
+
+.. _interpreted text role: http://docutils.sourceforge.net/
+ docs/ref/rst/roles.html
+
+
+Consolidated Fields
+'''''''''''''''''''
+
+In addition to the `standard set of fields`_, the reStructruedText parser also
+supports *consolidated fields*, which combine the documentation for several
+objects into a single field. For example, a single ``:Parameters:`` field is
+often used to describe all of the parameters for a function or method:
+
+.. python::
+
+ def fox_speed(size, weight, age):
+ """
+ Return the maximum speed for a fox.
+
+ :Parameters:
+ - `size`: The size of the fox (in meters)
+ - `weight`: The weight of the fox (in stones)
+ - `age`: The age of the fox (in years)
+ """
+ #[...]
+
+.. _standard set of fields: `Epydoc fields`_
+
+Epydoc will automatically extract information about each parameter from this
+list. These *consolidated fields* may be written using either a `bulleted
+list`_ or a `definition list`_.
+
+* If a consolidated field is written as a *bulleted list*, then each list item
+ must begin with the field's argument, marked as `interpreted text`_, and
+ followed by a colon or dash.
+* If a consolidated field is written as a *definition list*, then each
+ definition item's term should contain the field's argument, (it is not
+ mandatory for it being marked as interpreted text).
+
+.. _bulleted list: http://docutils.sourceforge.net/
+ docs/user/rst/quickref.html#bullet-lists
+.. _definition list: http://docutils.sourceforge.net/
+ docs/user/rst/quickref.html#definition-lists
+.. _interpreted text: http://docutils.sourceforge.net/
+ docs/user/rst/quickref.html#inline-markup
+
+The term classifier, if present, is used to specify the associated type. The
+following example shows the use of a definition list to define a consolidated
+field (note that docutils requires a space before and after the '``:``' used
+to mark classifiers).
+
+.. python::
+
+ def fox_speed(size, weight, age):
+ """
+ Return the maximum speed for a fox.
+
+ :Parameters:
+ size
+ The size of the fox (in meters)
+ weight : float
+ The weight of the fox (in stones)
+ age : int
+ The age of the fox (in years)
+ """
+ #[...]
+
+The following consolidated fields are currently supported by epydoc:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Consolidated Field Tag
+ - Corresponding Base Field Tag
+ * - ``:Parameters:``
+ - ``:param:``
+ * - ``:Exception:``
+ - ``:except:``
+ * - ``:Groups:``
+ - ``:group:``
+ * - ``:Keywords:``
+ - ``:keyword:``
+ * - ``:Variables:``
+ - ``:var:``
+ * - ``:IVariables:``
+ - ``:ivar:``
+ * - ``:CVariables:``
+ - ``:cvar:``
+ * - ``:Types:``
+ - ``:type:``
+
+
+Graph directives
+''''''''''''''''
+
+The epydoc reStructuredText reader defines several custom `directives`, which
+can be used to automatically generate a variety of graphs. The following custom
+directives are currently defined:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Directive
+ - Description
+
+ * - .. parsed-literal::
+
+ .. classtree:: [*classes...*]
+ :dir: *up|down|left|right*
+
+ - Display a class hierarchy for the given class or classes (including all
+ superclasses & subclasses). If no class is specified, and the directive
+ is used in a class's docstring, then that class's class hierarchy will
+ be displayed. The ``dir`` option specifies the orientation for the graph
+ (default=\ ``down``).
+
+ * - .. parsed-literal::
+
+ .. packagetree:: [*modules...*]
+ :dir: *up|down|left|right*
+ :style: *uml|tree*
+
+ - Display a package hierarchy for the given module or modules (including
+ all subpackages and submodules). If no module is specified, and the
+ directive is used in a module's docstring, then that module's package
+ hierarchy will be displayed. The ``dir`` option specifies the
+ orientation for the graph (default=\ ``down``). The ``style`` option
+ specifies whether packages should be displayed in a tree, or using
+ nested UML symbols.
+
+ * - .. parsed-literal::
+
+ .. importgraph:: [*modules...*]
+ :dir: *up|down|left|right*
+
+ - Display an import graph for the given module or modules. If no module
+ is specified, and the directive is used in a module's docstring, then
+ that module's import graph will be displayed. The ``dir`` option
+ specifies the orientation for the graph (default=\ ``left``).
+
+ * - .. parsed-literal::
+
+ .. callgraph:: [*functions...*]
+ :dir: *up|down|left|right*
+
+ - Display a call graph for the given function or functions. If no
+ function is specified, and the directive is used in a function's
+ docstring, then that function's call graph will be displayed. The
+ ``dir`` option specifies the orientation for the graph (default=\
+ ``right``).
+
+ * - .. parsed-literal::
+
+ .. dotgraph:: [*title...*]
+ :caption: *text...*
+ *graph...*
+
+ - Display a custom Graphviz dot graph. The body of the directive
+ (``graph...``) should contain the body of a dot graph. The optional
+ ``title`` argument, if specified, is used as the title of the graph.
+ The optional ``caption`` option can be used to provide a caption for
+ the graph.
+
+
+Colorized snippets directive
+''''''''''''''''''''''''''''
+
+Using reStructuredText markup it is possible to specify Python snippets in a
+`doctest block`__. SUch block will be colorized as in epytext `Doctest Blocks`_.
+
+.. __: http://docutils.sourceforge.net/
+ docs/user/rst/quickref.html#bullet-lists
+
+>>> def double(x):
+... return x * 2
+...
+>>> print double(8)
+16
+
+Doctest block are mostly useful to be run as a part of automatized test suite
+using the doctest_ module. If the Python prompt gets in your way when you try
+to copy and paste and you are not interested in self-testing docstrings, the
+``python`` directive will let you obtain a simple block of colorized text:
+
+.. _doctest: http://docs.python.org/lib/module-doctest.html
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - ::
+
+ .. python::
+
+ def fib(n):
+ """Print a Fibonacci series."""
+ a, b = 0, 1
+ while b < n:
+ print b,
+ a, b = b, a+b
+
+ - .. python::
+
+ def fib(n):
+ """Print a Fibonacci series."""
+ a, b = 0, 1
+ while b < n:
+ print b,
+ a, b = b, a+b
+
+
+External API links
+''''''''''''''''''
+
+Epydoc can be used to create hyperlinks from your package documentation towards
+objects defined in the API of other packages. Such links are similar to
+ordinary `documentation crossreference links`_, but it is required to configure
+Epydoc setting up a new `interpreted text role`_, binding it to an external API.
+
+To create a new role, the command line option ``--external-api=``\ *NAME* must
+be used. This option introduces a new interpreted text role called ``NAME``,
+which can be used to refer to objects defined in an external API.
+
+You can alternatively use a configuration file for this and all the other
+options: see the `sample configuration file`_ for a comprehensive example.
+
+For example, if your program needs to programmatically use the Epydoc package
+itself, your docstrings may refer to functions described by Epydoc API::
+
+ If you want to print a value, you can use
+ the :epydoc:`apidoc.pp_apidoc()` function.
+
+When you will generate the API documentation for such program, you will
+need the option ``--external-api=epydoc`` or you will get parsing errors due
+to the unknown role.
+
+Of course this doesn't help to really create cross references: the
+``--external-api`` option suffices to stop Epydoc complaining about unknown
+roles, but the text is simply rendered in a monotype font and no link is
+created.
+
+What Epydoc requires to create external API links is a mapping from the names
+of the objects exposed by the API and the URL where such objects are actually
+described. Such mapping must be provided as a text file, with an object name
+and its URL on each line, separated by a ``tab`` character. For example the
+Epydoc API documentation may be represented by a file names ``api-objects.txt``
+containing::
+
+ epydoc -> epydoc-module.html
+ epydoc.apidoc -> epydoc.apidoc-module.html
+ epydoc.apidoc.UNKNOWN -> epydoc.apidoc-module.html#UNKNOWN
+ epydoc.apidoc._pp_val -> epydoc.apidoc-module.html#_pp_val
+ epydoc.apidoc.py_src_filename -> epydoc.util-module.html#py_src_filename
+ epydoc.apidoc.pp_apidoc -> epydoc.apidoc-module.html#pp_apidoc
+ epydoc.apidoc._pp_list -> epydoc.apidoc-module.html#_pp_list
+ ... ...
+ ... ...
+
+Epydoc's HTML writer indeed includes such file in its output: see `HTML
+Files`_ for details.
+
+You can bind the definition file to the interpreted text role name using
+the command line option ``--external-api-file=``\ *NAME:FILENAME*.In the
+previous example you can use::
+
+ --external-api-file=epydoc:api-objects.txt
+
+This helps Epydoc to create relative urls: in the previous example the
+``apidoc.pp_apidoc()`` label will be linked with the
+``epydoc.apidoc-module.html#_pp_val`` URL.
+
+You can specify a new root for the generated links using the last command line
+option: ``--external-api-root=``\ *NAME:STRING*. *STRING* will be attached
+in front of any URL returned by the *NAME* text role. For example, to let your
+program refer to Epydoc API whose documentation is published at
+http://epydoc.sourceforge.net/api/ you can use the options::
+
+ --external-api-root=epydoc:http://epydoc.sourceforge.net/api/
+
+this will let your reference :epydoc:`apidoc.pp_apidoc()` point at the
+right documentation.
+
+The three options can be used any number of time, effectively allowing to link
+towards all the required external packages.
+
+
+Names resolution
+~~~~~~~~~~~~~~~~
+
+When an external API link is to be created, the required name is split along
+any separator ('``.``', '``::``', '``->``'). Everything after the first noise
+character (for example after an '``(``') is discarded.
+
+The name fragment is looked for in the names defined in the description file:
+first an exact match is attempted; if no name exactly matches the required
+name, a partial match is attempted: the required name is compared with the
+*trailing parts* of the names in the file.
+
+If a single name is found in this lookup, then its URL is returned. If the
+name is not found, or if it matches with the trailing part of many defined
+names, a warning is raised and the name is rendered as literal text.
+
+
+Linking from standalone documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Epydoc provides the script ``apirst2html.py`` which allows to use the
+previously described interpreted text roles from any reST document. The script
+exposes the same interface of the standard Docutils script ``rst2html.py`` but
+provides the extra command line options described in `External API links`_.
+
+With such tool you will be able to create hypertextual documentation of your
+package with direct links to its API.
+
+
+Javadoc
+-------
+
+Javadoc_ is a markup language developed by Sun Microsystems for documenting
+Java APIs. The epydoc implementation of Javadoc is based on the `Javadoc 1.4.2
+reference documentation`__. However, there are likely to be some minor incompatibilities between Sun's implementation and epydoc's. Known incompatibilities include:
+
+* Epydoc does not support the Javadoc block tag ``@serial``.
+* Epydoc does not support the following Javadoc inline tags: ``{@docroot}``,
+ ``{@inheritdoc}``, ``{@value}``.
+* Epydoc adds many field tags that Sun does not include, such as ``@var``,
+ ``@type``, and ``@group``.
+
+.. __: http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html
+
+
+Javadoc Fields
+''''''''''''''
+
+For compatibility with Javadoc, every ``@see`` field is assumed to contain a
+single crossreference link, unless its body is quoted, or it starts with an
+HTML tag. See the `Javadoc reference manual`__ for more information about how the
+``@see`` field is encoded in Javadoc.
+
+.. __: http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html#@see
+
+Because Javadoc does not mark end of the optional argument, field arguments
+must contain exactly one word. Thus, multi-word arguments are not available
+in Javadoc. In particular, all group names must be single words.
Property changes on: trunk/epydoc/doc/manual-othermarkup.txt
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Modified: trunk/epydoc/doc/manual-reference.txt
===================================================================
--- trunk/epydoc/doc/manual-reference.txt 2007-02-20 19:34:01 UTC (rev 1545)
+++ trunk/epydoc/doc/manual-reference.txt 2007-02-20 23:51:34 UTC (rev 1546)
@@ -156,17 +156,73 @@
*# The path to the output directory. May be relative or absolute.*
**target: html/**
+ *# An integer indicating how verbose epydoc should be. The default*
+ *# value is 0; negative values will supress warnings and errors;*
+ *# positive values will give more verbose output.*
+ **verbosity: 0**
+
+ *# A boolean value indicating that Epydoc should show a tracaback*
+ *# in case of unexpected error. By default don't show tracebacks*
+ **debug: 0**
+
+ *# If True, don't try to use colors or cursor control when doing*
+ *# textual output. The default False assumes a rich text prompt*
+ **simple-term: 0**
+
+
+ **### Generation options**
+
*# The default markup language for docstrings, for modules that do*
*# not define __docformat__. Defaults to epytext.*
**docformat: epytext**
+ *# Whether or not parsing should be used to examine objects.*
+ **parse: yes**
+
+ *# Whether or not introspection should be used to examine objects.*
+ **introspect: yes**
+
+ *# Don't examine in any way the modules whose dotted name match this*
+ *# regular expression pattern.*
+ **#exclude**
+
+ *# Don't perform introspection on the modules whose dotted name match this*
+ *# regular expression pattern.*
+ **#exclude-introspect**
+
+ *# Don't perform parsing on the modules whose dotted name match this*
+ *# regular expression pattern.*
+ **#exclude-parse**
+
+ *# The format for showing inheritance objects.*
+ *# It should be one of: 'grouped', 'listed', 'included'.*
+ **inheritance: listed**
+
+ *# Whether or not to inclue private variables. (Even if included,*
+ *# private variables will be hidden by default.)*
+ **private: yes**
+
+ *# Whether or not to list each module's imports.*
+ **imports: no**
+
+ *# Whether or not to include syntax highlighted source code in*
+ *# the output (HTML only).*
+ **sourcecode: yes**
+
+ *# Whether or not to includea a page with Epydoc log, containing*
+ *# effective option at the time of generation and the reported logs.*
+ **include-log: no**
+
+
+ **### Output options**
+
+ *# The documented project's name.*
+ **name: Example**
+
*# The CSS stylesheet for HTML output. Can be the name of a builtin*
*# stylesheet, or the name of a file.*
**css: white**
- *# The documented project's name.*
- **name: Example**
-
*# The documented project's URL.*
**url: http://some.project/**
@@ -187,24 +243,26 @@
*# Whether or not to include a frames-based table of contents.*
**frames: yes**
- *# Whether or not to inclue private variables. (Even if included,*
- *# private variables will be hidden by default.)*
- **private: yes**
+ *# Whether each class should be listed in its own section when*
+ *# generating LaTeX or PDF output.*
+ **separate-classes: no**
- *# Whether or not to list each module's imports.*
- **imports: no**
- *# An integer indicating how verbose epydoc should be. The default*
- *# value is 0; negative values will supress warnings and errors;*
- *# positive values will give more verbose output.*
- **verbosity: 0**
+ **### API linking options**
- *# Whether or not parsing should be used to examine objects.*
- **parse: yes**
+ *# Define a new API document. A new interpreted text role*
+ *# will be created*
+ **#external-api: epydoc**
- *# Whether or not introspection should be used to examine objects.*
- **introspect: yes**
+ *# Use the records in this file to resolve objects in the API named NAME.*
+ **#external-api-file: epydoc:api-objects.txt**
+ *# Use this URL prefix to configure the string returned for external API.*
+ **#external-api-root: epydoc:http://epydoc.sourceforge.net/api**
+
+
+ **### Graph options**
+
*# The list of graph types that should be automatically included*
*# in the output. Graphs are generated using the Graphviz "dot"*
*# executable. Graph types include: "classtree", "callgraph",*
@@ -215,19 +273,35 @@
*# graphs.*
**dotpath: /usr/local/bin/dot**
- *# Whether or not to include syntax highlighted source code in*
- *# the output (HTML only).*
- **sourcecode: yes**
-
*# The name of one or more pstat files (generated by the profile*
*# or hotshot module). These are used to generate call graphs.*
**pstat: profile.out**
- *# Whether each class should be listed in its own section when*
- *# generating LaTeX or PDF output.*
- **separate-classes: no**
+ *# Specify the font used to generate Graphviz graphs.*
+ *# (e.g., helvetica or times).*
+ **graph-font: Helvetica**
+ *# Specify the font size used to generate Graphviz*
+ **graph-font-size: 10**
+
+ **### Return value options**
+
+ *# If true, return a non-zero exit status, indicating failure,*
+ *# if any errors are encountered.*
+ **fail-on-error: false**
+
+ *# If true, return a non-zero exit status, indicating failure,*
+ *# if any errors or warnings are encountered (not including*
+ *# docstring warnings).*
+ **fail-on-warning: false**
+
+ *# Return a non-zero exit status, indicating failure, if any*
+ *# errors or warnings are encountered (including docstring*
+ *# warnings).*
+ **fail-on-docstring-warning: false**
+
+
Warnings and Errors
-------------------
Modified: trunk/epydoc/doc/manual-usage.txt
===================================================================
--- trunk/epydoc/doc/manual-usage.txt 2007-02-20 19:34:01 UTC (rev 1545)
+++ trunk/epydoc/doc/manual-usage.txt 2007-02-20 23:51:34 UTC (rev 1546)
@@ -270,8 +270,8 @@
``array.ArrayType``.
*module*\ ``-pysrc.html``
- A page with the module colourized source code, with links back to the
- objects main documentation pages. The creation of the colourized source
+ A page with the module colorized source code, with links back to the
+ objects main documentation pages. The creation of the colorized source
pages can be controlled using the options_ ``--show-sourcecode`` and
``--no-sourcecode``.
@@ -311,8 +311,7 @@
``api-objects.txt``
A text file containing each available item and the URL where it is
documented. Each item takes a file line and it is separated by the URL by
- a ``tab`` charecter. Such file can be used to create documents linkig to
- the API: see the ``--external-api`` documentation for details.
+ a ``tab`` charecter. Such file can be used to create `external API links`_.
``redirect.html``
A page containing Javascript code that redirect the browser to the
Modified: trunk/epydoc/doc/manual.txt
===================================================================
--- trunk/epydoc/doc/manual.txt 2007-02-20 19:34:01 UTC (rev 1545)
+++ trunk/epydoc/doc/manual.txt 2007-02-20 23:51:34 UTC (rev 1546)
@@ -42,5 +42,6 @@
.. include:: manual-usage.txt
.. include:: manual-epytext.txt
.. include:: manual-fields.txt
+.. include:: manual-othermarkup.txt
.. include:: manual-docstring.txt
.. include:: manual-reference.txt
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-02-20 19:34:06
|
Revision: 1545
http://svn.sourceforge.net/epydoc/?rev=1545&view=rev
Author: edloper
Date: 2007-02-20 11:34:01 -0800 (Tue, 20 Feb 2007)
Log Message:
-----------
- Check that duplicate item names are not given to build_doc_index;
if they are, then issue a warning and discard dups.
- Check that we don't generate 2 doc items with the same canonical name
from different items. This can happen, e.g., if you run
"epydoc a/x.py b/x.py" where neither a nor b are package directories,
so both modules will have canonical name "x". In this case, issue an
error message, and discard the docs from the second item.
(Otherwise, there would be 2 problems: first, we'd try to merge the
docs of these two modules; and second, we wouldn't have unique names
for them, so we'd end up overwriting the doc files of one with the
doc files of the other.)
Modified Paths:
--------------
trunk/epydoc/src/epydoc/docbuilder.py
Modified: trunk/epydoc/src/epydoc/docbuilder.py
===================================================================
--- trunk/epydoc/src/epydoc/docbuilder.py 2007-02-20 09:54:15 UTC (rev 1544)
+++ trunk/epydoc/src/epydoc/docbuilder.py 2007-02-20 19:34:01 UTC (rev 1545)
@@ -311,6 +311,20 @@
log.start_progress('Building documentation')
progress_estimator = _ProgressEstimator(items)
+ # Check for duplicate item names.
+ item_set = set()
+ for item in items[:]:
+ if item in item_set:
+ log.warning("Name %r given multiple times" % item)
+ items.remove(item)
+ item_set.add(item)
+
+ # Keep track of what top-level canonical names we've assigned, to
+ # make sure there are no naming conflicts. This dict maps
+ # canonical names to the item names they came from (so we can print
+ # useful error messages).
+ canonical_names = {}
+
# Collect (introspectdoc, parsedoc) pairs for each item.
doc_pairs = []
for item in items:
@@ -346,6 +360,20 @@
doc_pairs.append(_get_docs_from_pyobject(
item, options, progress_estimator))
+ # Make sure there are no naming conflicts.
+ name = (getattr(doc_pairs[-1][0], 'canonical_name', None) or
+ getattr(doc_pairs[-1][1], 'canonical_name', None))
+ if name in canonical_names:
+ log.error(
+ 'Two of the specified items, %r and %r, have the same '
+ 'canonical name ("%s"). This may mean that you specified '
+ 'two different files that both use the same module name. '
+ 'Ignoring the second item (%r)' %
+ (canonical_names[name], item, name, canonical_names[name]))
+ doc_pairs.pop()
+ else:
+ canonical_names[name] = item
+
# This will only have an effect if doc_pairs[-1] contains a
# package's docs. The 'not is_module_file(item)' prevents
# us from adding subdirectories if they explicitly specify
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-20 09:54:17
|
Revision: 1544
http://svn.sourceforge.net/epydoc/?rev=1544&view=rev
Author: dvarrazzo
Date: 2007-02-20 01:54:15 -0800 (Tue, 20 Feb 2007)
Log Message:
-----------
- Dropped old stylesheets.
Removed Paths:
-------------
trunk/epydoc/doc/doctest/doctest.css
trunk/epydoc/doc/doctest/docutils.css
Deleted: trunk/epydoc/doc/doctest/doctest.css
===================================================================
--- trunk/epydoc/doc/doctest/doctest.css 2007-02-20 09:52:09 UTC (rev 1543)
+++ trunk/epydoc/doc/doctest/doctest.css 2007-02-20 09:54:15 UTC (rev 1544)
@@ -1,45 +0,0 @@
-/*
-:Author: Edward Loper
-:Copyright: This stylesheet has been placed in the public domain.
-
-Stylesheet for use with Docutils.
-*/
-
-@import url(docutils).css);
-
-/*======================================================================*/
-/* Source code colorization */
-pre.py-doctest { padding: .5em; margin: 1em;
- background: #e8f0f8; color: #000000;
- border: 1px solid #708890; }
-table pre.py-doctest { background: #dce4ec;
- color: #000000; }
-.py-prompt { color: #005050; font-weight: bold;}
-.py-string { color: #006030; }
-.py-comment { color: #003060; }
-.py-keyword { color: #600000; }
-.py-output { color: #404040; }
-.py-name { color: #000050; }
-.py-name:link { color: #000050; }
-.py-name:visited { color: #000050; }
-.py-number { color: #005000; }
-.py-def-name { color: #000060; font-weight: bold; }
-.py-base-class { color: #000060; }
-.py-param { color: #000060; }
-.py-docstring { color: #006030; }
-.py-decorator { color: #804020; }
-
-/*======================================================================*/
-/* Document formatting */
-
-@media screen {
- body { background: #204060; color: #000000; }
- div.document {
- background: white; color: black;
- padding: 0 1em 0 1em;
- border: 2px solid black;
- }
-}
-
-h1.title { font-size: 180%; font-weight: bold; text-align: center;
- padding: .1em; margin: 0; border-bottom: 2px solid black;}
Deleted: trunk/epydoc/doc/doctest/docutils.css
===================================================================
--- trunk/epydoc/doc/doctest/docutils.css 2007-02-20 09:52:09 UTC (rev 1543)
+++ trunk/epydoc/doc/doctest/docutils.css 2007-02-20 09:54:15 UTC (rev 1544)
@@ -1,257 +0,0 @@
-/*
-:Author: David Goodger
-:Contact: go...@us...
-:Date: $Date: 2004/12/22 19:03:27 $
-:Version: $Revision: 1.45 $
-:Copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-*/
-
-/* "! important" is used here to override other ``margin-top`` and
- ``margin-bottom`` styles that are later in the stylesheet or
- more specific. See <http://www.w3.org/TR/CSS1#the-cascade>. */
-.first {
- margin-top: 0 ! important }
-
-.last {
- margin-bottom: 0 ! important }
-
-.hidden {
- display: none }
-
-a.toc-backref {
- text-decoration: none ;
- color: black }
-
-blockquote.epigraph {
- margin: 2em 5em ; }
-
-dl.docutils dd {
- margin-bottom: 0.5em }
-
-/* Uncomment (and remove this text!) to get bold-faced definition list terms
-dl.docutils dt {
- font-weight: bold }
-*/
-
-div.abstract {
- margin: 2em 5em }
-
-div.abstract p.topic-title {
- font-weight: bold ;
- text-align: center }
-
-div.admonition, div.attention, div.caution, div.danger, div.error,
-div.hint, div.important, div.note, div.tip, div.warning {
- margin: 2em ;
- border: medium outset ;
- padding: 1em }
-
-div.admonition p.admonition-title, div.hint p.admonition-title,
-div.important p.admonition-title, div.note p.admonition-title,
-div.tip p.admonition-title {
- font-weight: bold ;
- font-family: sans-serif }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
- color: red ;
- font-weight: bold ;
- font-family: sans-serif }
-
-/* Uncomment (and remove this text!) to get reduced vertical space in
- compound paragraphs.
-div.compound .compound-first, div.compound .compound-middle {
- margin-bottom: 0.5em }
-
-div.compound .compound-last, div.compound .compound-middle {
- margin-top: 0.5em }
-*/
-
-div.dedication {
- margin: 2em 5em ;
- text-align: center ;
- font-style: italic }
-
-div.dedication p.topic-title {
- font-weight: bold ;
- font-style: normal }
-
-div.figure {
- margin-left: 2em }
-
-div.footer, div.header {
- font-size: smaller }
-
-div.line-block {
- display: block ;
- margin-top: 1em ;
- margin-bottom: 1em }
-
-div.line-block div.line-block {
- margin-top: 0 ;
- margin-bottom: 0 ;
- margin-left: 1.5em }
-
-div.sidebar {
- margin-left: 1em ;
- border: medium outset ;
- padding: 1em ;
- background-color: #ffffee ;
- width: 40% ;
- float: right ;
- clear: right }
-
-div.sidebar p.rubric {
- font-family: sans-serif ;
- font-size: medium }
-
-div.system-messages {
- margin: 5em }
-
-div.system-messages h1 {
- color: red }
-
-div.system-message {
- border: medium outset ;
- padding: 1em }
-
-div.system-message p.system-message-title {
- color: red ;
- font-weight: bold }
-
-div.topic {
- margin: 2em }
-
-h1.title {
- text-align: center }
-
-h2.subtitle {
- text-align: center }
-
-hr.docutils {
- width: 75% }
-
-ol.simple, ul.simple {
- margin-bottom: 1em }
-
-ol.arabic {
- list-style: decimal }
-
-ol.loweralpha {
- list-style: lower-alpha }
-
-ol.upperalpha {
- list-style: upper-alpha }
-
-ol.lowerroman {
- list-style: lower-roman }
-
-ol.upperroman {
- list-style: upper-roman }
-
-p.attribution {
- text-align: right ;
- margin-left: 50% }
-
-p.caption {
- font-style: italic }
-
-p.credits {
- font-style: italic ;
- font-size: smaller }
-
-p.label {
- white-space: nowrap }
-
-p.rubric {
- font-weight: bold ;
- font-size: larger ;
- color: maroon ;
- text-align: center }
-
-p.sidebar-title {
- font-family: sans-serif ;
- font-weight: bold ;
- font-size: larger }
-
-p.sidebar-subtitle {
- font-family: sans-serif ;
- font-weight: bold }
-
-p.topic-title {
- font-weight: bold }
-
-pre.address {
- margin-bottom: 0 ;
- margin-top: 0 ;
- font-family: serif ;
- font-size: 100% }
-
-pre.line-block {
- font-family: serif ;
- font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
- margin-left: 2em ;
- margin-right: 2em ;
- background-color: #eeeeee }
-
-span.classifier {
- font-family: sans-serif ;
- font-style: oblique }
-
-span.classifier-delimiter {
- font-family: sans-serif ;
- font-weight: bold }
-
-span.interpreted {
- font-family: sans-serif }
-
-span.option {
- white-space: nowrap }
-
-span.option-argument {
- font-style: italic }
-
-span.pre {
- white-space: pre }
-
-span.problematic {
- color: red }
-
-table.citation {
- border-left: solid thin gray }
-
-table.docinfo {
- margin: 2em 4em }
-
-table.docutils {
- margin-top: 0.5em ;
- margin-bottom: 0.5em }
-
-table.footnote {
- border-left: solid thin black }
-
-table.docutils td, table.docutils th,
-table.docinfo td, table.docinfo th {
- padding-left: 0.5em ;
- padding-right: 0.5em ;
- vertical-align: top }
-
-th.docinfo-name, th.field-name {
- font-weight: bold ;
- text-align: left ;
- white-space: nowrap }
-
-h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
-h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
- font-size: 100% }
-
-tt.docutils {
- background-color: #eeeeee }
-
-ul.auto-toc {
- list-style-type: none }
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-20 09:52:10
|
Revision: 1543
http://svn.sourceforge.net/epydoc/?rev=1543&view=rev
Author: dvarrazzo
Date: 2007-02-20 01:52:09 -0800 (Tue, 20 Feb 2007)
Log Message:
-----------
- Typo fixed
Modified Paths:
--------------
trunk/epydoc/src/epydoc/test/apidoc.doctest
trunk/epydoc/src/epydoc/test/docbuilder.doctest
Modified: trunk/epydoc/src/epydoc/test/apidoc.doctest
===================================================================
--- trunk/epydoc/src/epydoc/test/apidoc.doctest 2007-02-20 09:50:38 UTC (rev 1542)
+++ trunk/epydoc/src/epydoc/test/apidoc.doctest 2007-02-20 09:52:09 UTC (rev 1543)
@@ -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 :epydoc:`APIDoc` class hierarchy, which is used to encode API
+define the `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-20 09:50:38 UTC (rev 1542)
+++ trunk/epydoc/src/epydoc/test/docbuilder.doctest 2007-02-20 09:52:09 UTC (rev 1543)
@@ -7,8 +7,8 @@
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 build_doc to build documentation, and pretty prints the resulting
-ModuleDoc object. The `attribs` argument specifies which attributes
-of the `APIDoc`s should be displayed. The `build` argument gives the
+ModuleDoc object. The ``attribs`` argument specifies which attributes
+of the `APIDoc` s should be displayed. The `build` argument gives the
name of a variable in the module whose documentation should be built,
instead of bilding docs for the whole module.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-20 09:50:39
|
Revision: 1542
http://svn.sourceforge.net/epydoc/?rev=1542&view=rev
Author: dvarrazzo
Date: 2007-02-20 01:50:38 -0800 (Tue, 20 Feb 2007)
Log Message:
-----------
- Added HTML manual generation
Modified Paths:
--------------
trunk/epydoc/Makefile
Modified: trunk/epydoc/Makefile
===================================================================
--- trunk/epydoc/Makefile 2007-02-20 09:49:56 UTC (rev 1541)
+++ trunk/epydoc/Makefile 2007-02-20 09:50:38 UTC (rev 1542)
@@ -14,6 +14,7 @@
EXAMPLES_SRC = $(wildcard doc/*.py)
DOCS = $(wildcard doc/*)
DOCTESTS = $(wildcard src/epydoc/test/*.doctest)
+MANUAL_SRC = $(wildcard doc/manual*.txt)
# What version of python to use?
PYTHON = python
@@ -47,6 +48,9 @@
DOCTEST_HTML_FILES := \
$(DOCTESTS:src/epydoc/test/%.doctest=$(HTML_DOCTEST)/%.html)
+manual-html: $(MANUAL_SRC)
+ $(RST2HTML) doc/manual.txt $(HTML)/epydoc.html
+
##//////////////////////////////////////////////////////////////////////
## Usage
##//////////////////////////////////////////////////////////////////////
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-20 09:49:57
|
Revision: 1541
http://svn.sourceforge.net/epydoc/?rev=1541&view=rev
Author: dvarrazzo
Date: 2007-02-20 01:49:56 -0800 (Tue, 20 Feb 2007)
Log Message:
-----------
- Adding user manual.
A chapter on reST and Javadoc is required. To be done soon.
Added Paths:
-----------
trunk/epydoc/doc/manual-docstring.txt
trunk/epydoc/doc/manual-epytext.txt
trunk/epydoc/doc/manual-fields.txt
trunk/epydoc/doc/manual-install.txt
trunk/epydoc/doc/manual-reference.txt
trunk/epydoc/doc/manual-usage.txt
trunk/epydoc/doc/manual.txt
Added: trunk/epydoc/doc/manual-docstring.txt
===================================================================
--- trunk/epydoc/doc/manual-docstring.txt (rev 0)
+++ trunk/epydoc/doc/manual-docstring.txt 2007-02-20 09:49:56 UTC (rev 1541)
@@ -0,0 +1,125 @@
+Docstrings and coding issues
+============================
+
+.. $Id$
+
+..
+ This paragraph is introdictory: this chapter should explain advanced details.
+
+
+ Python docstrings
+ -----------------
+
+ Docstrings are a standard method that can be used by Python developers to
+ attach documentation pieces to most Python objects.
+
+ Here is an example module showing different docstrings:
+
+ .. python::
+
+ #!/usr/bin/python
+ # -*- coding: latin-1 -*-
+ """A Sample Module.
+
+ The first string in the module, starting after the *hashbang* and the
+ encoding definition comment, is the module docstring.
+ """
+
+ class Foo:
+ """
+ This is a testing class.
+
+ It doesn't do much stuff, but it's pretty documented. This, for
+ example, is the class docstring.
+ """
+
+ def getMagic(self):
+ """
+ A function returning a magic number.
+
+ This is the function documentation.
+ """
+ return 42
+
+ the_number = property(
+ fget=getMagic,
+ doc="""This is the property docstring.""")
+
+ Some guidelines for docstring standardization have been published, see for
+ example :PEP:`257` for some higl-level convention. No docstring structure
+ is enforced anyway by official documentation.
+
+
+Variable docstrings
+-------------------
+
+Python variables don't support docstrings. The variable can be described in the
+module or class where it is defined using the tags ``@var``, ``@ivar``,
+``@cvar``; but this only allows for a textual description: no further metadata
+can be added to the variable (except for the type, using the ``@type`` tag).
+
+Epydoc supports *variable docstrings*: 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 (``__init__``) are considered instance variables:
+
+.. python::
+
+ class A:
+ x = 22
+ """Docstring for class variable A.x"""
+
+ def __init__(self, a):
+ self.y = a
+ """Docstring for instance variable A.y
+
+Variables may also be documented using *comment docstrings*. If a variable
+assignment is immediately preceeded by a comment whose lines begin with the
+special marker '``#:``', or is followed on the same line by such a comment,
+then it is treated as a docstring for that variable:
+
+.. python::
+
+ #: docstring for x
+ x = 22
+ x = 22 #: docstring for x
+
+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 ``@ivar`` in the context of a variable
+docstring:
+
+.. python::
+
+ class B:
+ y = 42
+ """@ivar: This is an instance variable."""
+
+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.
+
+
+Items visibility
+----------------
+
+Any Python object (modules, classes, functions, variables...) can be *public*
+or *private*. Usually the object name decides the object visibility: objects
+whose name starts with an underscore and doesn't end with an underscore are
+considered private. All the other objects (including the "magic functions" such
+as ``__add__``) are public.
+
+For each module and class, Epydoc generates pages with both public and private
+methods. A Javascript snippet allows to toggle the visibility of private
+objects.
+
+If a module wants to hide some of the objects it contains (either defined in
+the module itself or imported from other modules), it can explicitly list the
+names if its `public names`_ in the ``__all__`` variable.
+
+.. _public names: http://www.python.org/doc/2.4.3/ref/import.html
+
+If a module defines the ``__all__`` variable, Epydoc uses its content to decide
+if the module objects are public or private.
+
Property changes on: trunk/epydoc/doc/manual-docstring.txt
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Added: trunk/epydoc/doc/manual-epytext.txt
===================================================================
--- trunk/epydoc/doc/manual-epytext.txt (rev 0)
+++ trunk/epydoc/doc/manual-epytext.txt 2007-02-20 09:49:56 UTC (rev 1541)
@@ -0,0 +1,873 @@
+The Epytext Markup Language
+===========================
+
+.. $Id$
+
+Overview
+--------
+
+Epytext is a lightweight markup language for Python docstrings. The epytext
+markup language is used by epydoc to parse docstrings and create structured API
+documentation. Epytext markup is broken up into the following categories:
+
+* **Block Structure** divides the docstring into nested blocks of text, such
+ as *paragraphs* and *lists*.
+
+ o **Basic Blocks** are the basic unit of block structure.
+
+ o **Hierarchical blocks** represent the nesting structure of the docstring.
+
+* **Inline Markup** marks regions of text within a basic block with properties,
+ such as italics and hyperlinks.
+
+
+Block Structure
+---------------
+
+Block structure is encoded using indentation, blank lines, and a handful of
+special character sequences.
+
+* Indentation is used to encode the nesting structure of hierarchical blocks.
+ The indentation of a line is defined as the number of leading spaces on that
+ line; and the indentation of a block is typically the indentation of its
+ first line.
+* Blank lines are used to separate blocks. A blank line is a line that only
+ contains whitespace.
+* Special character sequences are used to mark the beginnings of some blocks.
+ For example, '``-``' is used as a bullet for unordered list items, and
+ '``>>>``' is used to mark `doctest blocks`_.
+
+The following sections describe how to use each type of block structure.
+
+
+Paragraphs
+''''''''''
+
+A paragraph is the simplest type of basic block. It consists of one or more
+lines of text. Paragraphs must be left justified (i.e., every line must have
+the same indentation). The following example illustrates how paragraphs can be
+used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This is a paragraph. Paragraphs can
+ span multiple lines, and can contain
+ I{inline markup}.
+
+ This is another paragraph. Paragraphs
+ are separated by blank lines.
+ """
+ *[...]*
+
+ - This is a paragraph. Paragraphs can span multiple lines,
+ and contain *inline markup*.
+
+ This is another paragraph. Paragraphs are separated from each
+ other by blank lines.
+
+Lists
+'''''
+
+Epytext supports both ordered and unordered lists. A list consists of one or
+more consecutive *list items* of the same type (ordered or unordered), with the
+same indentation. Each list item is marked by a *bullet*. The bullet for
+unordered list items is a single dash character (``-``). Bullets for ordered
+list items consist of a series of numbers followed by periods, such as
+``12.`` or ``1.2.8.``.
+
+List items typically consist of a bullet followed by a space and a single
+paragraph. The paragraph may be indented more than the list item's bullet;
+often, the paragraph is intended two or three characters, so that its left
+margin lines up with the right side of the bullet. The following example
+illustrates a simple ordered list.
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ 1. This is an ordered list item.
+
+ 2. This is a another ordered list
+ item.
+
+ 3. This is a third list item. Note that
+ the paragraph may be indented more
+ than the bullet.
+ """
+ *[...]*
+
+ - 1. This is an ordered list item.
+ 2. This is another ordered list item.
+ 3. This is a third list item. Note that the paragraph may be
+ indented more than the bullet.
+
+List items can contain more than one paragraph; and they can also contain
+sublists, `literal blocks`, and `doctest blocks`. All of the blocks contained
+by a list item must all have equal indentation, and that indentation must be
+greater than or equal to the indentation of the list item's bullet. If the
+first contained block is a paragraph, it may appear on the same line as the
+bullet, separated from the bullet by one or more spaces, as shown in the
+previous example. All other block types must follow on separate lines.
+
+Every list must be separated from surrounding blocks by indentation:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This is a paragraph.
+ 1. This is a list item.
+ 2. This a second list
+ item.
+ - This is a sublist
+ """
+ [...]
+
+ - This is a paragraph.
+
+ 1. This is a list item.
+ 2. This is a second list item.
+
+ * This is a sublist.
+
+Note that sublists must be separated from the blocks in their parent list
+item by indentation. In particular, the following docstring generates an error,
+since the sublist is not separated from the paragraph in its parent list item
+by indentation:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ 1. This is a list item. Its
+ paragraph is indented 7 spaces.
+ - This is a sublist. It is
+ indented 7 spaces.
+ """
+ #[...]
+
+ - **L5: Error: Lists must be indented.**
+
+The following example illustrates how lists can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This is a paragraph.
+ 1. This is a list item.
+ - This is a sublist.
+ - The sublist contains two
+ items.
+ - The second item of the
+ sublist has its own sublist.
+
+ 2. This list item contains two
+ paragraphs and a doctest block.
+
+ >>> print 'This is a doctest block'
+ This is a doctest block
+
+ This is the second paragraph.
+ """
+ #[...]
+
+ - This is a paragraph.
+
+ 1. This is a list item.
+
+ * This is a sublist.
+ * The sublist contains two items.
+
+ - The second item of the sublist has its own own sublist.
+
+ 2. This list item contains two paragraphs and a doctest block.
+
+ >>> print 'This is a doctest block'
+ This is a doctest block
+
+ This is the second paragraph.
+
+Epytext will treat any line that begins with a bullet as a list item. If you
+want to include bullet-like text in a paragraph, then you must either ensure
+that it is not at the beginning of the line, or use escaping_ to prevent
+epytext from treating it as markup:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This sentence ends with the number
+ 1. Epytext can't tell if the "1."
+ is a bullet or part of the paragraph,
+ so it generates an error.
+ """
+ #[...]
+
+ - **L4: Error: Lists must be indented.**
+
+ * - .. python::
+
+ def example():
+ """
+ This sentence ends with the number 1.
+
+ This sentence ends with the number
+ E{1}.
+ """
+ #[...]
+
+ - This sentence ends with the number 1.
+
+ This sentence ends with the number 1.
+
+
+Sections
+''''''''
+
+A section consists of a heading followed by one or more child blocks.
+
+* The heading is a single underlined line of text. Top-level section headings
+ are underlined with the '``=``' character; subsection headings are
+ underlined with the '``-``' character; and subsubsection headings are
+ underlined with the '``~``' character. The length of the underline must
+ exactly match the length of the heading.
+* The child blocks can be paragraphs, lists, literal blocks, doctest blocks,
+ or sections. Each child must have equal indentation, and that indentation
+ must be greater than or equal to the heading's indentation.
+
+The following example illustrates how sections can be used:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This paragraph is not in any section.
+
+ Section 1
+ =========
+ This is a paragraph in section 1.
+
+ Section 1.1
+ -----------
+ This is a paragraph in section 1.1.
+
+ Section 2
+ =========
+ This is a paragraph in section 2.
+ """
+ #[...]
+
+ -
+ .. class:: h1
+
+ Section 1
+
+ This is a paragraph in section 1.
+
+ .. class:: h2
+
+ Section 1.1
+
+ This is a paragraph in section 1.1.
+
+ .. class:: h1
+
+ Section 2
+
+ This is a paragraph in section 2.
+
+
+Literal Blocks
+''''''''''''''
+
+Literal blocks are used to represent "preformatted" text. Everything within a
+literal block should be displayed exactly as it appears in plaintext. In
+particular:
+
+* Spaces and newlines are preserved.
+* Text is shown in a monospaced font.
+* Inline markup is not detected.
+
+Literal blocks are introduced by paragraphs ending in the special sequence
+"``::``". Literal blocks end at the first line whose indentation is equal to
+or less than that of the paragraph that introduces them. The following example
+shows how literal blocks can be used:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ The following is a literal block::
+
+ Literal /
+ / Block
+
+ This is a paragraph following the
+ literal block.
+ """
+ #[...]
+
+ - The following is a literal block::
+
+ Literal /
+ / Block
+
+ This is a paragraph following the literal block.
+
+Literal blocks are indented relative to the paragraphs that introduce them;
+for example, in the previous example, the word "Literal" is displayed with four
+leading spaces, not eight. Also, note that the double colon ("``::``") that
+introduces the literal block is rendered as a single colon.
+
+
+Doctest Blocks
+''''''''''''''
+
+Doctest blocks contain examples consisting of Python expressions and their
+output. Doctest blocks can be used by the doctest module to test the
+documented object. Doctest blocks begin with the special sequence
+"``>>>``". Doctest blocks are delimited from surrounding blocks by blank lines.
+Doctest blocks may not contain blank lines. The following example shows how
+doctest blocks can be used:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ The following is a doctest block:
+
+ >>> print (1+3,
+ ... 3+5)
+ (4, 8)
+ >>> 'a-b-c-d-e'.split('-')
+ ['a', 'b', 'c', 'd', 'e']
+
+ This is a paragraph following the
+ doctest block.
+ """
+ #[...]
+
+ - The following is a doctest block:
+
+ >>> print (1+3,
+ ... 3+5)
+ (4, 8)
+ >>> 'a-b-c-d-e'.split('-')
+ ['a', 'b', 'c', 'd', 'e']
+
+ This is a paragraph following the doctest block.
+
+
+Fields
+''''''
+
+Fields are used to describe specific properties of a documented object. For
+example, fields can be used to define the parameters and return value of a
+function; the instance variables of a class; and the author of a module. Each
+field is marked by a *field tag*, which consist of an at sign ('``@``')
+followed by a *field name*, optionally followed by a space and a *field
+argument*, followed by a colon ('``:``'). For example, '``@return:``' and
+'``@param x:``' are field tags.
+
+Fields can contain paragraphs, lists, literal blocks, and doctest blocks.
+All of the blocks contained by a field must all have equal indentation, and
+that indentation must be greater than or equal to the indentation of the
+field's tag. If the first contained block is a paragraph, it may appear on the
+same line as the field tag, separated from the field tag by one or more spaces.
+All other block types must follow on separate lines.
+
+Fields must be placed at the end of the docstring, after the description of
+the object. Fields may be included in any order.
+
+Fields do not need to be separated from other blocks by a blank line. Any line
+that begins with a field tag followed by a space or newline is considered a
+field.
+
+The following example illustrates how fields can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ @param x: This is a description of
+ the parameter x to a function.
+ Note that the description is
+ indented four spaces.
+ @type x: This is a description of
+ x's type.
+ @return: This is a description of
+ the function's return value.
+
+ It contains two paragraphs.
+ """
+ #[...]
+
+ - **Parameters:**
+ **x** - This is a description of the parameter x to a function.
+ Note that the description is indented four spaces.
+
+ *(type=This is a description of x's type.)*
+
+ **Returns:**
+ This is a description of the function's return value.
+
+ It contains two paragraphs.
+
+For a list of the fields that are supported by epydoc, see the `epydoc fields`
+chapter.
+
+
+Inline Markup
+-------------
+
+Inline markup has the form '``x{...}``', where ``x`` is a single capital letter
+that specifies how the text between the braces should be rendered. Inline
+markup is recognized within paragraphs and section headings. It is *not*
+recognized within literal and doctest blocks. Inline markup can contain
+multiple words, and can span multiple lines. Inline markup may be nested.
+
+A matching pair of curly braces is only interpreted as inline markup if the
+left brace is immediately preceeded by a capital letter. So in most cases, you
+can use curly braces in your text without any form of escaping. However, you do
+need to escape curly braces when:
+
+1. You want to include a single (un-matched) curly brace.
+2. You want to preceed a matched pair of curly braces with a capital letter.
+
+Note that there is no valid Python expression where a pair of matched curly
+braces is immediately preceeded by a capital letter (except within string
+literals). In particular, you never need to escape braces when writing Python
+dictionaries. See also escaping_.
+
+
+Basic Inline Markup
+'''''''''''''''''''
+
+ Epytext defines four types of inline markup that specify how text should be
+ displayed:
+
+* ``I{...}``: Italicized text.
+* ``B{...}``: Bold-faced text.
+* ``C{...}``: Source code or a Python identifier.
+* ``M{...}``: A mathematical expression.
+
+By default, source code is rendered in a fixed width font; and mathematical
+expressions are rendered in italics. But those defaults may be changed by
+modifying the CSS stylesheet. The following example illustrates how the four
+basic markup types can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ I{B{Inline markup} may be nested; and
+ it may span} multiple lines.
+
+ - I{Italicized text}
+ - B{Bold-faced text}
+ - C{Source code}
+ - M{Math}
+
+ Without the capital letter, matching
+ braces are not interpreted as markup:
+ C{my_dict={1:2, 3:4}}.
+ """
+ #[...]
+
+ - **Inline markup** *may be nested*; and it may span multiple lines.
+
+ - *Italicized text*
+ - **Bold-faced text**
+ - ``Source code``
+ - Math: *m*x+b*
+
+ Without the capital letter, matching braces are not interpreted as
+ markup: ``my_dict={1:2, 3:4}``.
+
+
+URLs
+''''
+
+The inline markup construct ``U{``\ *text<url>*\ ``}`` is used to create links
+to external URLs and URIs. '*text*' is the text that should be displayed for
+the link, and '*url*' is the target of the link. If you wish to use the URL as
+the text for the link, you can simply write "``U{``\ *url*\ ``}``". Whitespace
+within URL targets is ignored. In particular, URL targets may be split over
+multiple lines. The following example illustrates how URLs can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ - U{www.python.org}
+ - U{http://www.python.org}
+ - U{The epydoc homepage<http://
+ epydoc.sourceforge.net>}
+ - U{The B{Python} homepage
+ <www.python.org>}
+ - U{Edward Loper<mailto:edloper@
+ gradient.cis.upenn.edu>}
+ """
+ #[...]
+
+ - * `www.python.org`_
+ * http://www.python.org
+ * `The epydoc homepage`_
+ * |pyhome|__
+ * `Edward Loper <mailto:ed...@gr...>`__
+
+ .. __: http://www.python.org
+ .. _The epydoc homepage: http://epydoc.sourceforge.net
+ .. _www.python.org: http://www.python.org
+ .. |pyhome| replace:: The **Python** homepage
+
+
+Documentation Crossreference Links
+''''''''''''''''''''''''''''''''''
+
+The inline markup construct '``L{``\ *text<object>*\ ``}``' is used to create
+links to the documentation for other Python objects. '*text*' is the text that
+should be displayed for the link, and '*object*' is the name of the Python
+object that should be linked to. If you wish to use the name of the Python
+object as the text for the link, you can simply write ``L{``\ *object*\ }``.
+Whitespace within object names is ignored. In particular, object names may be
+split over multiple lines. The following example illustrates how documentation
+crossreference links can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ - L{x_transform}
+ - L{search<re.search>}
+ - L{The I{x-transform} function
+ <x_transform>}
+ """
+ #[...]
+
+ - * `x_transform`_
+ * `search`_
+ * `The x-transform function`_
+
+ .. _x_transform: http://www.example.com
+ .. _search: http://www.example.com
+ .. _The x-transform function: http://www.example.com
+
+In order to find the object that corresponds to a given name, epydoc checks the
+following locations, in order:
+
+1. If the link is made from a class or method docstring, then epydoc checks for
+ a method, instance variable, or class variable with the given name.
+2. Next, epydoc looks for an object with the given name in the current module.
+3. Epydoc then tries to import the given name as a module. If the current
+ module is contained in a package, then epydoc will also try importing the
+ given name from all packages containing the current module.
+4. Epydoc then tries to divide the given name into a module name and an
+ object name, and to import the object from the module. If the current module
+ is contained in a package, then epydoc will also try importing the module
+ name from all packages containing the current module.
+5. Finally, epydoc looks for a class name in any module with the given name.
+ This is only returned if there is a single class with such name.
+
+If no object is found that corresponds with the given name, then epydoc
+issues a warning.
+
+
+Indexed Terms
+'''''''''''''
+
+Epydoc automatically creates an index of term definitions for the API
+documentation. The inline markup construct '``X{...}``' is used to mark terms
+for inclusion in the index. The term itself will be italicized; and a link will
+be created from the index page to the location of the term in the text. The
+following example illustrates how index terms can be used:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ An X{index term} is a term that
+ should be included in the index.
+ """
+ #[...]
+
+ - An *index term* is a term that should be included in the index.
+
+ ============ ==============
+ Index
+ ===========================
+ index term *example*
+ x intercept *x_intercept*
+ y intercept *x_intercept*
+ ============ ==============
+
+
+Symbols
+'''''''
+
+Symbols are used to insert special characters in your documentation. A symbol
+has the form '``S{code}``', where code is a symbol code that specifies what
+character should be produced. The following example illustrates how symbols can
+be used to generate special characters:
+
+.. include:: <xhtml1-symbol.txt>
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ Symbols can be used in equations:
+
+ - S{sum}S{alpha}/x S{<=} S{beta}
+
+ S{<-} and S{larr} both give left
+ arrows. Some other arrows are
+ S{rarr}, S{uarr}, and S{darr}.
+ """
+ #[...]
+
+ - Symbols can be used in equations:
+
+ - |sum| |alpha|/\ *x* |le| |beta|
+
+ |larr| and |larr| both give left
+ arrows. Some other arrows are
+ |rarr|, |uarr|, and |darr|.
+
+Although symbols can be quite useful, you should keep in mind that they can
+make it harder to read your docstring in plaintext. In general, symbols should
+be used sparingly. For a complete list of the symbols that are currently
+supported, see the reference documentation for :epydoc:`epytext.SYMBOLS`.
+
+
+Escaping
+''''''''
+
+Escaping is used to write text that would otherwise be interpreted as epytext
+markup. Epytext was carefully constructed to minimize the need for this type
+of escaping; but sometimes, it is unavoidable. Escaped text has the form
+'``E{``\ *code*\ ``}``', where code is an escape code that specifies what
+character should be produced. If the escape code is a single character (other
+than '``{``' or '``}``'), then that character is produced. For example, to
+begin a paragraph with a dash (which would normally signal a list item), write
+'``E{-}``'. In addition, two special escape codes are defined: '``E{lb}``'
+produces a left curly brace ('``{``'); and '``E{rb}``' produces a right curly
+brace ('``}``'). The following example illustrates how escaping can be used:
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ This paragraph ends with two
+ colons, but does not introduce
+ a literal blockE{:}E{:}
+
+ E{-} This is not a list item.
+
+ Escapes can be used to write
+ unmatched curly braces:
+ E{rb}E{lb}
+ """
+ #[...]
+
+ - This paragraph ends with two colons, but does not introduce a literal
+ block:\ :
+
+ \- This is not a list item.
+
+ Escapes can be used to write unmatched curly braces: }{
+
+
+Graphs
+''''''
+
+The inline markup construct '``G{``\ *graphtype args...*\ ``}``' is used to
+insert automatically generated graphs. The following graphs generation
+constructions are currently defines:
+
+======================================= =======================================
+Markup Description
+======================================= =======================================
+``G{classtree`` *classes...*\ ``}`` Display a class hierarchy for the given
+ class or classes (including all
+ superclasses & subclasses). If no class
+ is specified, and the directive is used
+ in a class's docstring, then that
+ class's class hierarchy will be
+ displayed.
+``G{packagetree`` *modules...*\ ``}`` Display a package hierarchy for the
+ given module or modules (including all
+ subpackages and submodules). If no
+ module is specified, and the directive
+ is used in a module's docstring, then
+ that module's package hierarchy will be
+ displayed.
+``G{importgraph`` *modules...*\ ``}`` Display an import graph for the given
+ module or modules. If no module is
+ specified, and the directive is used in
+ a module's docstring, then that
+ module's import graph will be
+ displayed.
+``G{callgraph`` *functions...*\ ``}`` Display a call graph for the given
+ function or functions. If no function
+ is specified, and the directive is used
+ in a function's docstring, then that
+ function's call graph will be
+ displayed.
+======================================= =======================================
+
+
+Characters
+----------
+
+Valid Characters
+''''''''''''''''
+
+Valid characters for an epytext docstring are space (``\040``); newline
+(``\012``); and any letter, digit, or punctuation, as defined by the current
+locale. Control characters (``\000``-``\010` and ``\013``-``\037``) are not
+valid content characters. Tabs (``\011``) are expanded to spaces, using the
+same algorithm used by the Python parser. Carridge-return/newline pairs
+(``\015\012``) are converted to newlines.
+
+
+Content Characters
+''''''''''''''''''
+
+Characters in a docstring that are not involved in markup are called *content characters*. Content characters are always displayed as-is. In particular, HTML
+codes are not passed through. For example, consider the following example:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ def example():
+ """
+ <B>test</B>
+ """
+ #[...]
+
+ - <B>test</B>
+
+The docstring is rendered as ``<B>test</B>``, and not as the word "test" in
+bold face.
+
+
+Spaces and Newlines
+'''''''''''''''''''
+
+In general, spaces and newlines within docstrings are treated as soft spaces.
+In other words, sequences of spaces and newlines (that do not contain a blank
+line) are rendered as a single space, and words may wrapped at spaces. However,
+within literal blocks and doctest blocks, spaces and newlines are preserved,
+and no word-wrapping occurs; and within URL targets and documentation link
+targets, whitespace is ignored.
Property changes on: trunk/epydoc/doc/manual-epytext.txt
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Added: trunk/epydoc/doc/manual-fields.txt
===================================================================
--- trunk/epydoc/doc/manual-fields.txt (rev 0)
+++ trunk/epydoc/doc/manual-fields.txt 2007-02-20 09:49:56 UTC (rev 1541)
@@ -0,0 +1,522 @@
+Epydoc fields
+=============
+
+.. $Id$
+
+Fields are used to describe specific properties of a documented object. For
+example, fields can be used to define the parameters and return value of a
+function; the instance variables of a class; and the author of a module. Each
+field consists of a *tag*, an optional *argument*, and a *body*.
+
+* The *tag* is a case-insensitive word that indicates what kind of
+ documentation is given by the field.
+* The optional *argument* specifies what object, parameter, or group is
+ documented by the field.
+* The *body* contains the main contents of the field.
+
+
+Field Markup
+------------
+
+Each docstring markup langauge marks fields differently. The following table
+shows the basic fields syntax for each markup language. For more information,
+see the definition of field syntax for each markup language.
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Epytext
+ - reStructuredText
+ - Javadoc
+
+ * - .. parsed-literal::
+
+ @\ *tag*: *body*...
+ @\ *tag* *arg*: *body*...
+
+ - .. parsed-literal::
+
+ :\ *tag*: *body*...
+ :\ *tag* *arg*: *body*...
+
+ - .. parsed-literal::
+
+ @\ *tag* *body*...
+ @\ *tag* *arg* *body*...
+
+ * - `Definition of epytext fields`__
+ - `Definition of ReStructuredText fields`__
+ - `Definition of Javadoc fields`__
+
+.. __: Fields_
+.. __: http://docutils.sourceforge.net/spec/rst/reStructuredText.html
+ #field-lists
+.. __: http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html
+ #javadoctags
+
+
+Supported Fields
+----------------
+
+The following table lists the fields that epydoc currently recognizes. Field
+tags are written using epytext markup; if you are using a different markup
+language, then you should adjust the markup accordingly.
+
+
+Functions and Methods parameters
+''''''''''''''''''''''''''''''''
+
+``@param`` *p*: ...
+ A description of the parameter *p* for a function or method.
+
+``@type`` *p*: ...
+ The expected type for the parameter *p*.
+
+``@return``: ...
+ The return value for a function or method.
+
+``@rtype``: ...
+ The type of the return value for a function or method.
+
+``@keyword`` *p*: ...
+ A description of the keyword parameter *p*.
+
+``@raise`` *e*: ...
+ A description of the circumstances under which a function or method
+ raises exception *e*.
+
+These tags can be used to specify attributes of parameters and return value
+of function and methods. These tags are usually put in the the docstring of the
+function to be documented.
+
+.. note:: constructor parameters
+
+ In C extension modules, extension classes cannot have a docstring attached
+ to the ``__init__`` function; consequently it is not possible to document
+ parameters and exceptions raised by the class constructor. To overcome this
+ shortcoming, the tags ``@param``, ``@keyword``, ``@type``, ``@exception``
+ are also allowed to appear in the class docstring. In this case they refer
+ to constructor parameters.
+
+``@param`` fields should be used to document any explicit parameter
+(including the keyword parameter). ``@keyword`` fields should only be used
+for non-explicit keyword parameters:
+
+.. python::
+
+ def plant(seed, *tools, **options):
+ """
+ @param seed: The seed that should be planted.
+ @param tools: Tools that should be used to plant the seed.
+ @param options: Any extra options for the planting.
+
+ @keyword dig_deep: Plant the seed deep under ground.
+ @keyword soak: Soak the seed before planting it.
+ """
+ #[...]
+
+Since the ``@type`` field allows for arbitrary text, it does not
+automatically create a crossreference link to the specified type, and is
+not written in fixed-width font by default. If you want to create a
+crossreference link to the type, or to write the type in a fixed-width
+font, then you must use inline markup:
+
+.. python::
+
+ def ponder(person, time):
+ """
+ @param person: Who should think.
+ @type person: L{Person} or L{Animal}
+ @param time: How long they should think.
+ @type time: C{int} or C{float}
+ """
+ #[...]
+
+
+Variables parameters
+''''''''''''''''''''
+
+``@ivar`` *v*: ...
+ A description of the class instance variable *v*.
+
+``@cvar`` *v*: ...
+ A description of the static class variable *v*.
+
+``@var`` *v*: ...
+ A description of the module variable *v*.
+
+``@type`` *v*: ...
+ The type of the variable *v*.
+
+These tags are usually put in a module or class docstring. If fthe sources can
+be parsed by Epydoc it is also possible to document the variable in their own
+docstrings: see `variable docstrings`_
+
+
+Properties parameters
+'''''''''''''''''''''
+
+``@type``: ...
+ The type of the property.
+
+The ``@type`` tag can be attached toa property docstring to specify its type.
+
+
+Grouping and Sorting
+'''''''''''''''''''''
+
+``@group`` *g*: *c1,...,cn*
+ Organizes a set of related children of a module or class into a group.
+ *g* is the name of the group; and *c1,...,cn* are the names of the
+ children in the group. To define multiple groups, use multiple group
+ fields.
+
+``@sort``: *c1,...,cn*
+ Specifies the sort order for the children of a module or class.
+ *c1,...,cn* are the names of the children, in the order in which they
+ should appear. Any children that are not included in this list will
+ appear after the children from this list, in alphabetical order.
+
+These tags can be used to present groups of related items in a logical way.
+They apply to modules and classes docstrings.
+
+For the ``@group`` and ``@sort`` tags, asterisks (``*``) can be used to
+specify multiple children at once. An asterisk in a child name will match
+any substring:
+
+.. python::
+
+ class widget(size, weight, age):
+ """
+ @group Tools: zip, zap, *_tool
+ @group Accessors: get_*
+ @sort: get_*, set_*, unpack_*, cut
+ """
+ #[...]
+
+.. note:: group markers
+
+ It is also possible to group set of related items enclosing them
+ into special comment starting with the *group markers* '``#{``' and '``#}``'
+ The group title can be specified after the opening group marker. Example:
+
+ .. python::
+
+ #{ Database access functions
+
+ def read(id):
+ #[...]
+
+ def store(item):
+ #[...]
+
+ def delete(id):
+ #[...]
+
+ # groups can't be nested, so a closing marker is not required here.
+
+ #{ Web publish functions
+
+ def get(request):
+ #[...]
+
+ def post(request):
+ #[...]
+
+ #}
+
+
+Notes and Warnings
+''''''''''''''''''
+
+``@note``: ...
+ A note about an object. Multiple note fields may be used to list
+ separate notes.
+
+``@attention``: ...
+ An important note about an object. Multiple attention fields may be
+ used to list separate notes.
+
+``@bug``: ...
+ A description of a bug in an object. Multiple bug fields may be used to
+ report separate bugs.
+
+ .. note::
+
+ If any ``@bug`` field is used, the HTML writer will generate a the page
+ ``bug-index.html``, containing links to all the items tagged with
+ the field.
+
+``@warning``: ...
+ A warning about an object. Multiple warning fields may be used to
+ report separate warnings.
+
+
+Status
+''''''
+
+``@version``: ...
+ The current version of an object.
+
+``@todo`` [*ver*]: ...
+ A planned change to an object. If the optional argument ver is given,
+ then it specifies the version for which the change will be made.
+ Multiple todo fields may be used if multiple changes are planned.
+
+ .. note::
+
+ If any ``@todo`` field is used, the HTML writer will generate a the
+ page ``todo-index.html``, containing links to all the items tagged
+ with the field.
+
+
+``@deprecated``: ...
+ Indicates that an object is deprecated. The body of the field describe
+ the reason why the object is deprecated.
+
+``@since``: ...
+ The date or version when an object was first introduced.
+
+``@status``: ...
+ The current status of an object.
+
+``@change``: ...
+ A change log entry for this object.
+
+``@permission``: ...
+ The object access permission, for systems such Zope/Plone supporting
+ this concept. It may be used more than once to specify multiple
+ permissions.
+
+
+Formal Conditions
+'''''''''''''''''
+
+``@requires``: ...
+ A requirement for using an object. Multiple requires fields may be
+ used if an object has multiple requirements.
+
+``@precondition``: ...
+ A condition that must be true before an object is used. Multiple
+ precondition fields may be used if an object has multiple preconditions.
+
+``@postcondition``: ...
+ A condition that is guaranteed to be true after an object is used.
+ Multiple postcondition fields may be used if an object has multiple
+ postconditions.
+
+``@invariant``: ...
+ A condition which should always be true for an object. Multiple
+ invariant fields may be used if an object has multiple invariants.
+
+
+Bibliographic Information
+'''''''''''''''''''''''''
+
+``@author``: ...
+ The author(s) of an object. Multiple author fields may be used if an
+ object has multiple authors.
+
+``@organization``: ...
+ The organization that created or maintains an object.
+
+``@copyright``: ...
+ The copyright information for an object.
+
+``@license``: ...
+ The licensing information for an object.
+
+``@contact``: ...
+ Contact information for the author or maintainer of a module, class,
+ function, or method. Multiple contact fields may be used if an object
+ has multiple contacts.
+
+
+Other fields
+''''''''''''
+
+``@summary``: ...
+ A summary description for an object. This description overrides the
+ default summary (which is constructed from the first sentence of the
+ object's description).
+
+``@see``: ...
+ A description of a related topic. see fields typically use
+ documentation crossreference links or external hyperlinks that link to
+ the related topic.
+
+
+Fields synonyms
+---------------
+
+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 adjust the markup
+accordingly.
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Name
+ - Synonims
+
+ * - ``@param`` *p*: ...
+ - | ``@parameter`` *p*: ...
+ | ``@arg`` *p*: ...
+ | ``@argument`` *p*: ...
+
+ * - ``@return``: ...
+ - ``@returns``: ...
+
+ * - ``@rtype``: ...
+ - ``@returntype``: ...
+
+ * - ``@raise`` *e*: ...
+ - | ``@raises`` *e*: ...
+ | ``@except`` *e*: ...
+ | ``@exception`` *e*: ...
+
+ * - ``@keyword`` *p*: ...
+ - | ``@kwarg`` *p*: ...
+ | ``@kwparam`` *p*: ...
+
+ * - ``@ivar`` *v*: ...
+ - ``@ivariable`` *v*: ...
+
+ * - ``@cvar`` *v*: ...
+ - ``@cvariable`` *v*: ...
+
+ * - ``@var`` *v*: ...
+ - ``@variable`` *v*: ...
+
+ * - ``@see``: ...
+ - ``@seealso``: ...
+
+ * - ``@warning``: ...
+ - ``@warn``: ...
+
+ * - ``@requires``: ...
+ - | ``@require``: ...
+ | ``@requirement``: ...
+
+ * - ``@precondition``: ...
+ - ``@precond``: ...
+
+ * - ``@postcondition``: ...
+ - ``@postcond``: ...
+
+ * - ``@organization``: ...
+ - ``@org``: ...
+
+ * - ``@copyright``: ...
+ - ``@(c)``: ...
+
+ * - ``@change``: ...
+ - ``@changed``: ...
+
+
+Module metadata variables
+-------------------------
+
+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. Customized
+metadata variables can be added using the method described in `Adding New
+Fields`_.
+
+.. list-table::
+ :header-rows: 1
+
+ * - Tag
+ - Variable
+
+ * - ``@author``
+ - ``__author__``
+
+ * - ``@authors``
+ - ``__authors__``
+
+ * - ``@contact``
+ - ``__contact__``
+
+ * - ``@copyright``
+ - ``__copyright__``
+
+ * - ``@license``
+ - ``__license__``
+
+ * - ``@deprecated``
+ - ``__deprecated__``
+
+ * - ``@date``
+ - ``__date__``
+
+ * - ``@version``
+ - ``__version__``
+
+
+Adding New Fields
+-----------------
+
+New fields can be defined for the docstrings in a module using the special
+``@newfield`` tag (or its synonym, ``@deffield``). This tag has the following
+syntax:
+
+ .. parsed-literal::
+
+ @newfield *tag*: *label* [, *plural* ]
+
+Where *tag* is the new tag that's being defined; *label* is a string that will
+be used to mark this field in the generated output; and plural is the plural form
+of label, if different.
+
+New fields can be defined in any Python module. If they are defined in a
+package, it will be possible to use the newly defined tag from every package
+submodule.
+
+Each new field will also define a `metadata variable`_ which can be used
+to set the field value instead of the tag. For example, if a *revision*
+tag has been defined with::
+
+ @newfield revision: Revision
+
+then it will be possible to set a value for the field using a module variable:
+
+.. python::
+
+ __revision__ = "1234"
+
+.. _metadata variable: `Module metadata variables`_
+
+The following example illustrates how the @newfield can be used:
+Docstring Input Rendered Output
+
+
+.. list-table::
+ :header-rows: 1
+
+ * - Docstring Input
+ - Rendered Output
+
+ * - .. python::
+
+ """
+ @newfield corpus: Corpus, Corpora
+ """
+
+ def example():
+ """
+ @corpus: Bob's wordlist.
+ @corpus: The British National Corpus.
+ """
+ [...]
+
+ - **Corpora:**
+
+ * Bob's wordlist.
+ * The British National Corpus.
+
+.. Note:: The module-level variable ``__extra_epydoc_fields__`` is deprecated;
+ use ``@newfield`` instead.
Property changes on: trunk/epydoc/doc/manual-fields.txt
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Added: trunk/epydoc/doc/manual-install.txt
===================================================================
--- trunk/epydoc/doc/manual-install.txt (rev 0)
+++ trunk/epydoc/doc/manual-install.txt 2007-02-20 09:49:56 UTC (rev 1541)
@@ -0,0 +1,163 @@
+Installing Epydoc
+=================
+
+.. $Id$
+
+Downloading Epydoc
+------------------
+
+Epydoc can be downloaded from the `SourceForge download page`_. Epydoc is
+available in five formats:
+
+* RPM (``.noarch.rpm``)
+* Windows installer (``.win32.exe``)
+* Source install (``.tar.gz``)
+* Source install (``.zip``)
+* Source RPM (``.src.rpm``)
+
+.. _SourceForge download page:
+ http://sourceforge.net/project/showfiles.php?group_id=32455
+
+If you are installing on RedHat, I recommend that you use the RPM file. If you
+are installing on Windows, I recommended that you use the windows installer.
+Otherwise, you should use one of the source install files.
+
+
+Getting Epydoc from Subversion
+------------------------------
+
+If you wish to keep up on the latest developments, you can get the latest
+version of epydoc from the `subversion repository`_::
+
+ [/home/edloper]$ svn co https://svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc
+ [/home/edloper]$ ls epydoc
+ Makefile doc man sandbox src
+
+This will create a directory named ``epydoc`` containing the latest version of
+epydoc. The ``epydoc`` package itself is in ``epydoc/src/epydoc`` (so adding
+``epydoc/src`` to your ``PYTHONPATH`` will let you use it). You should
+periodically update your copy of the subversion repository, to make sure you
+have all the latest changes::
+
+ [/home/edloper/epydoc]$ svn up
+
+You can browse the subversion repository here__.
+
+.. _subversion repository: http://sourceforge.net/svn/?group_id=32455
+.. __: http://svn.sourceforge.net/viewcvs.cgi/epydoc/trunk/epydoc/
+
+
+Installing from the RPM File
+----------------------------
+
+1. Download the RPM file to a directory of your choice.
+2. Use rpm to install the new package. ::
+
+ [/tmp]$ su
+ Password:
+ [/tmp]# rpm -i epydoc-3.0beta1.noarch.rpm
+
+3. Once epydoc is installed, you can delete the RPM file. ::
+
+ [/tmp]# rm epydoc-3.0beta1.rpm
+
+
+Installing from the Windows Installer
+-------------------------------------
+
+1. Download and run ``epydoc-3.0beta1.win32.exe``.
+2. Follow the on-screen instructions. Epydoc will be installed in the epydoc
+ subdirectory of your Python installation directory (typically
+ ``C:\Python24\``).
+3. The Windows installer creates two scripts in the ``Scripts`` subdirectory of
+ your Python installation directory: ``epydoc.pyw`` opens the graphical user
+ interface, and ``epydoc.py`` calls the command line interface. If you'd
+ like, you can create shortcuts from these scripts to more convenient
+ locations (such as your desktop or start menu).
+4. Once epydoc is installed, you can delete ``epydoc-3.0beta1.win32.exe``.
+
+
+Installing from the Source Distribution (using make)
+----------------------------------------------------
+
+1. Download an epydoc source distribution to a directory of your choice, and
+ uncompress it. ::
+
+ [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0beta1.tar.gz
+ [/tmp]$ gunzip epydoc-3.0beta1.tar.gz
+ [/tmp]$ tar -xvf epydoc-3.0beta1.tar
+
+2. Use ``make install`` in the ``eydoc-3.0beta1/`` directory to install
+ epydoc. ::
+
+ [/tmp]$ cd epydoc-3.0beta1/
+ [/tmp/epydoc-3.0beta1]$ su
+ Password:
+ [/tmp/epydoc-3.0beta1]# make install
+ running install
+ running build
+ [...]
+ copying build/scripts/epydoc -> /usr/bin
+ changing mode of /usr/bin/epydoc to 100775
+
+3. If you'd like to keep a local copy of the documentation, then use ``make
+ installdocs``. By default, this will install the documentation to
+ ``/usr/share/doc/`` and the man pages to ``/usr/share/man/``. If you would
+ prefer to install documentation to different directories (such as
+ ``/usr/lib/doc``), then edit the ``MAN`` and ``DOC`` variables at the top of
+ ``Makefile`` before running ``make installdocs``. ::
+
+ [/tmp/epydoc-3.0beta1]# make installdocs
+
+4. Once epydoc is installed, you can delete the installation directory and the
+ source distribution file. ::
+
+ [/tmp/epydoc-3.0beta1]# cd ..
+ [/tmp]# rm -r epydoc-3.0beta1
+ [/tmp]# rm epydoc-3.0beta1.tar
+
+
+Installing from the Source Distribution (without make)
+------------------------------------------------------
+
+1. Download an epydoc source distribution to a directory of your choice, and
+ uncompress it. ::
+
+ [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0beta1.tar.gz
+ [/tmp]$ gunzip epydoc-3.0beta1.tar.gz
+ [/tmp]$ tar -xvf epydoc-3.0beta1.tar
+
+2. Use the ``setup.py`` script in the ``eydoc-3.0beta1/`` directory to install
+ epydoc. ::
+
+ [/tmp]$ cd epydoc-3.0beta1/
+ [/tmp/epydoc-3.0beta1]$ su
+ Password:
+ [/tmp/epydoc-3.0beta1]# python setup.py install
+ running install
+ running build
+ [...]
+ copying build/scripts/epydoc -> /usr/bin
+ changing mode of /usr/bin/epydoc to 100775
+ [/tmp/epydoc-3.0beta1]# cd ..
+ [/tmp]#
+
+3. If you'd like to keep a local copy of the documentation, then copy it to a
+ permanant location, such as ``/usr/share/doc/``. You may also want to copy
+ the man pages to a permanant location, such as ``/usr/share/man/``. ::
+
+ [/tmp]# cp -r epydoc-3.0beta1/doc/ /usr/share/doc/epydoc/
+ [/tmp]# cp epydoc-3.0beta1/man/* /usr/share/man/
+
+4. Once epydoc is installed, you can delete the installation directory and the
+ source distribution file. ::
+
+ [/tmp]# rm -r epydoc-3.0beta1
+ [/tmp]# rm epydoc-3.0beta1.tar
+
+
+Installing on Debian
+--------------------
+
+Epydoc 2.1 is available as a testing debian package (``python-epydoc``). The
+epydoc documentation is also available as a package (``epydoc-doc``).
Property changes on: trunk/epydoc/doc/manual-install.txt
___________________________________________________________________
Name: svn:keywords
+ Id
Name: svn:eol-style
+ native
Added: trunk/epydoc/doc/manual-reference.txt
===================================================================
--- trunk/epydoc/doc/manual-reference.txt (rev 0)
+++ trunk/epydoc/doc/manual-reference.txt 2007-02-20 09:49:56 UTC (rev 1541)
@@ -0,0 +1,367 @@
+References
+==========
+
+.. $Id$
+
+Command Line Usage
+------------------
+
+Usage: ``epydoc.py`` [*ACTION*] [*options*] *NAMES...*
+
+NAMES...
+ A list of the Python objects that should be documented. Objects can be
+ specified using dotted names (such as ``os.path``), module filenames (such
+ as ``epydoc/epytext.py``), or package directory names (such as
+ ``epydoc/``). Packages are expanded to include all sub-modules and
+ sub-packages.
+
+options
+ .. parsed-literal::
+
+ --config=FILE A configuration file, specifying additional OPTIONS
+ and/or NAMES. This option may be repeated.
+ -o PATH, --output=PATH
+ The output directory. If PATH does not exist, then it
+ will be created.
+ -q, --quiet Decrease the verbosity.
+ -v, --verbose Increase the verbosity.
+ --debug Show full tracebacks for internal errors.
+ --simple-term Do not try to use color or cursor control when
+ displaying the progress bar, warnings, or errors.
+
+ Actions:
+ --html Write HTML output.
+ --text Write plaintext output. (not implemented yet)
+ --latex Write LaTeX output.
+ --dvi Write DVI output.
+ --ps Write Postscript output.
+ --pdf Write PDF output.
+ --check Check completeness of docs.
+ --pickle Write the documentation to a pickle file.
+ --version Show epydoc's version number and exit.
+ -h, --help Show this message and exit. For help on specific
+ topics, use "--help TOPIC". Use "--help topics" for a
+ list of available help topics
+
+ Generation Options:
+ --docformat=NAME The default markup language for docstrings. Defaults
+ to "epytext".
+ --parse-only Get all information from parsing (don't introspect)
+ --introspect-only Get all information from introspecting (don't parse)
+ --exclude=PATTERN Exclude modules whose dotted name matches the regular
+ expression PATTERN
+ --exclude-introspect=PATTERN
+ Exclude introspection of modules whose dotted name
+ matches the regular expression PATTERN
+ --exclude-parse=PATTERN
+ Exclude parsing of modules whose dotted name matches
+ the regular expression PATTERN
+ --inheritance=STYLE
+ The format for showing inheritance objects. STYLE
+ should be one of: grouped, listed, included.
+ --show-private Include private variables in the output. (default)
+ --no-private Do not include private variables in the output.
+ --show-imports List each module's imports.
+ --no-imports Do not list each module's imports. (default)
+ --show-sourcecode Include source code with syntax highlighting in the
+ HTML output. (default)
+ --no-sourcecode Do not include source code with syntax highlighting in
+ the HTML output.
+ --include-log Include a page with the process log (epydoc-log.html)
+
+ Output Options:
+ --name=NAME The documented project's name (for the navigation
+ bar).
+ --css=STYLESHEET The CSS stylesheet. STYLESHEET can be either a
+ builtin stylesheet or the name of a CSS file.
+ --url=URL The documented project's URL (for the navigation bar).
+ --navlink=HTML HTML code for a navigation link to place in the
+ navigation bar.
+ --top=PAGE 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"
+ --help-file=FILE An alternate help file. FILE should contain the body
+ of an HTML file -- navigation bars will be added to
+ it.
+ --show-frames Include frames in the HTML output. (default)
+ --no-frames Do not include frames in the HTML output.
+ --separate-classes When generating LaTeX or PDF output, list each class
+ in its own section, instead of listing them under
+ their containing module.
+
+ 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.
+
+ Graph Options:
+ --graph=...
[truncated message content] |
|
From: <dva...@us...> - 2007-02-20 09:44:42
|
Revision: 1540
http://svn.sourceforge.net/epydoc/?rev=1540&view=rev
Author: dvarrazzo
Date: 2007-02-20 01:44:38 -0800 (Tue, 20 Feb 2007)
Log Message:
-----------
- rst2html to be used to produce other web pages other than the doctest.
- added support for '.. python::' directive
- added support for epydoc api directive
- the stylesheet is linked with the path properly mangled.
Modified Paths:
--------------
trunk/epydoc/src/tools/rst2html.py
Modified: trunk/epydoc/src/tools/rst2html.py
===================================================================
--- trunk/epydoc/src/tools/rst2html.py 2007-02-20 09:41:31 UTC (rev 1539)
+++ trunk/epydoc/src/tools/rst2html.py 2007-02-20 09:44:38 UTC (rev 1540)
@@ -12,16 +12,29 @@
import docutils.nodes
# Epydoc imports. Make sure path contains the 'right' epydoc.
-import sys
+import sys, os
sys.path.insert(0, '../')
-from epydoc.markup.doctest import doctest_to_html
+import epydoc.markup.restructuredtext # register the 'python' directive
+from epydoc.markup.doctest import doctest_to_html, doctest_to_latex, \
+ HTMLDoctestColorizer
+from epydoc.docwriter.xlink import ApiLinkReader
+
+class CustomizedReader(ApiLinkReader):
+ settings_defaults = (ApiLinkReader.settings_defaults or {}).copy()
+ settings_defaults.update({
+ 'external_api': [ 'epydoc' ],
+ 'external_api_root': [ 'epydoc:http://epydoc.sourceforge.net/api/' ],
+ 'external_api_file': [ 'epydoc:' + os.path.join(
+ os.path.split(__file__)[0], '../../html/api/api-objects.txt') ],
+ })
+
class CustomizedHTMLWriter(HTMLWriter):
settings_defaults = (HTMLWriter.settings_defaults or {}).copy()
settings_defaults.update({
- 'stylesheet': 'doctest.css',
- 'stylesheet_path': None,
- 'output_encoding': 'ascii',
+ 'stylesheet_path': os.path.normpath(os.path.join(
+ os.path.split(__file__)[0], '../../doc/custom.css')),
+ 'output_encoding': 'ascii',
'output_encoding_error_handler': 'xmlcharrefreplace',
'embed_stylesheet': False,
})
@@ -32,10 +45,20 @@
class CustomizedHTMLTranslator(HTMLTranslator):
def visit_doctest_block(self, node):
- self.body.append(doctest_to_html(str(node[0])))
+ pysrc = node[0].astext()
+ if node.get('codeblock'):
+ self.body.append(HTMLDoctestColorizer().colorize_codeblock(pysrc))
+ else:
+ self.body.append(doctest_to_html(pysrc))
raise docutils.nodes.SkipNode
description = ('Generates HTML documents from reStructuredText '
'documents. ' + default_description)
writer = CustomizedHTMLWriter()
-docutils.core.publish_cmdline(writer=writer, description=description)
+reader = CustomizedReader()
+
+#this doesn't work. Put ``.. default-role:: epydoc`` in the doctests instead.
+#docutils.parsers.rst.roles.DEFAULT_INTERPRETED_ROLE = 'epydoc'
+
+docutils.core.publish_cmdline(reader=reader, writer=writer,
+ description=description)
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-20 09:41:33
|
Revision: 1539
http://svn.sourceforge.net/epydoc/?rev=1539&view=rev
Author: dvarrazzo
Date: 2007-02-20 01:41:31 -0800 (Tue, 20 Feb 2007)
Log Message:
-----------
- Added customized css (a more generic version of the one used by doctests)
- Docutils base CSS updated.
Added Paths:
-----------
trunk/epydoc/doc/custom.css
trunk/epydoc/doc/docutils.css
Added: trunk/epydoc/doc/custom.css
===================================================================
--- trunk/epydoc/doc/custom.css (rev 0)
+++ trunk/epydoc/doc/custom.css 2007-02-20 09:41:31 UTC (rev 1539)
@@ -0,0 +1,56 @@
+/*
+:Author: Edward Loper
+:Copyright: This stylesheet has been placed in the public domain.
+
+Stylesheet for use with Docutils.
+*/
+
+@import url("docutils.css");
+
+/*======================================================================*/
+/* Source code colorization */
+pre.py-doctest { padding: .5em; margin: 1em;
+ background: #e8f0f8; color: #000000;
+ border: 1px solid #708890; }
+table pre.py-doctest { background: #dce4ec;
+ color: #000000; }
+.py-prompt { color: #005050; font-weight: bold;}
+.py-string { color: #006030; }
+.py-comment { color: #003060; }
+.py-keyword { color: #600000; }
+.py-output { color: #404040; }
+.py-name { color: #000050; }
+.py-name:link { color: #000050; }
+.py-name:visited { color: #000050; }
+.py-number { color: #005000; }
+.py-def-name { color: #000060; font-weight: bold; }
+.py-base-class { color: #000060; }
+.py-param { color: #000060; }
+.py-docstring { color: #006030; }
+.py-decorator { color: #804020; }
+
+/*======================================================================*/
+/* Document formatting */
+
+@media screen {
+ body { background: #204060; color: #000000; }
+ div.document {
+ background: white; color: black;
+ padding: 0 1em 0 1em;
+ border: 2px solid black;
+ }
+}
+
+h1.title { font-size: 180%; font-weight: bold; text-align: center;
+ padding: .1em; margin: 0; border-bottom: 2px solid black;}
+
+pre.literal-block { padding: .5em; margin: 1em;
+ background: #e8f0f8; color: #000000;
+ border: 1px solid #708890; }
+
+table.docutils { background: #e8f0f8; border: 1px solid black; }
+table.docutils th { background: #70b0ff; }
+
+/* For the "Sections" example in the manual */
+p.h1 { font-size: 150%; font-weight: bold; }
+p.h2 { font-size: 125%; font-weight: bold; }
Added: trunk/epydoc/doc/docutils.css
===================================================================
--- trunk/epydoc/doc/docutils.css (rev 0)
+++ trunk/epydoc/doc/docutils.css 2007-02-20 09:41:31 UTC (rev 1539)
@@ -0,0 +1,273 @@
+/*
+:Author: David Goodger
+:Contact: go...@py...
+:Date: $Date: 2006-05-21 22:44:42 +0200 (Sun, 21 May 2006) $
+:Revision: $Revision: 4564 $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+ border: 0 }
+
+table.borderless td, table.borderless th {
+ /* Override padding for "table.docutils td" with "! important".
+ The right padding separates the table cells. */
+ padding: 0 0.5em 0 0 ! important }
+
+.first {
+ /* Override more specific margin styles with "! important". */
+ margin-top: 0 ! important }
+
+.last, .with-subtitle {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dl.docutils dd {
+ margin-bottom: 0.5em }
+
+dl.docutils dt {
+ font-weight: bold }
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+ compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+ margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+ margin-top: 0.5em }
+*/
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+div.footer, div.header {
+ clear: both;
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+ margin-top: 0.4em }
+
+h1.title {
+ text-align: center }
+
+h2.subtitle {
+ text-align: center }
+
+hr.docutils {
+ width: 75% }
+
+img.align-left {
+ clear: left }
+
+img.align-right {
+ clear: right }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+span.section-subtitle {
+ /* font-size relative to parent (h1..h6 element) */
+ font-size: 80% }
+
+table.citation {
+ border-left: solid 1px gray;
+ margin-left: 1px }
+
+table.docinfo {
+ margin: 2em 4em }
+
+table.docutils {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.footnote {
+ border-left: solid 1px black;
+ margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap ;
+ padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+ font-size: 100% }
+
+ul.auto-toc {
+ list-style-type: none }
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <dva...@us...> - 2007-02-20 09:40:05
|
Revision: 1538
http://svn.sourceforge.net/epydoc/?rev=1538&view=rev
Author: dvarrazzo
Date: 2007-02-20 01:39:50 -0800 (Tue, 20 Feb 2007)
Log Message:
-----------
- A pair of typo fixed.
Modified Paths:
--------------
trunk/epydoc/doc/using.html
Modified: trunk/epydoc/doc/using.html
===================================================================
--- trunk/epydoc/doc/using.html 2007-02-20 01:38:37 UTC (rev 1537)
+++ trunk/epydoc/doc/using.html 2007-02-20 09:39:50 UTC (rev 1538)
@@ -388,18 +388,18 @@
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>
+ A text file containing each available item and the URL where it is
+ documented. Each item dotted name 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
+ documentation 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>
+ <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
@@ -433,7 +433,7 @@
<p> Epydoc creates a CSS stylesheet (<code>epydoc.css</code>) when it
builds the API documentation for a project. You can specify which
-stylesheet should be used using the <code>-c</code> command-line
+stylesheet should be used using the <code>--css</code> command-line
option. If you do not specify a stylesheet, and one is already
present, epydoc will use that stylesheet; otherwise, it will use the
default stylesheet. For a list of the CSS classes used by epydoc, see
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
