Thread: [Epydoc-commits] SF.net SVN: epydoc: [1212] trunk/epydoc/doc
Brought to you by:
edloper
From: <ed...@us...> - 2006-04-10 19:46:27
|
Revision: 1212 Author: edloper Date: 2006-04-10 12:45:10 -0700 (Mon, 10 Apr 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1212&view=rev Log Message: ----------- - Major update to the webpage Modified Paths: -------------- trunk/epydoc/doc/epydoc_gui.png trunk/epydoc/doc/epydoc_guiconfig.png trunk/epydoc/doc/sflogo.png Property Changed: ---------------- trunk/epydoc/doc/epydoc_gui.png trunk/epydoc/doc/epydoc_guiconfig.png trunk/epydoc/doc/sflogo.png Modified: trunk/epydoc/doc/epydoc_gui.png =================================================================== (Binary files differ) Property changes on: trunk/epydoc/doc/epydoc_gui.png ___________________________________________________________________ Name: svn:eol-style - native Name: svn:mime-type + image/png Modified: trunk/epydoc/doc/epydoc_guiconfig.png =================================================================== (Binary files differ) Property changes on: trunk/epydoc/doc/epydoc_guiconfig.png ___________________________________________________________________ Name: svn:eol-style - native Name: svn:mime-type + image/png Modified: trunk/epydoc/doc/sflogo.png =================================================================== (Binary files differ) Property changes on: trunk/epydoc/doc/sflogo.png ___________________________________________________________________ Name: svn:eol-style - native Name: svn:mime-type + image/png This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ed...@us...> - 2006-08-22 16:45:55
|
Revision: 1295 Author: edloper Date: 2006-08-22 09:45:49 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1295&view=rev Log Message: ----------- - Added regression tests to the web page Modified Paths: -------------- trunk/epydoc/doc/index.html Added Paths: ----------- trunk/epydoc/doc/doctests.html Added: trunk/epydoc/doc/doctests.html =================================================================== --- trunk/epydoc/doc/doctests.html (rev 0) +++ trunk/epydoc/doc/doctests.html 2006-08-22 16:45:49 UTC (rev 1295) @@ -0,0 +1,62 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> <head> +<title>Epydoc: Regression Tests</title> +<link rel="stylesheet" href="epydoc.css" type="text/css"/> +</head> +<!-- $Id: future.html 1211 2006-04-10 19:38:37Z edloper $ --> + +<body> +<div class="body"> +<h1> Epydoc: Regression Tests </h1> + +<p> The following files contain the current regression test suite for +epydoc. Each file contains a prose description of some aspect of +epydoc, interspersed with +<a href="http://docs.python.org/lib/module-doctest.html">doctest</a> +examples. Each of these doctest examples is a single test case. </p> + +<ul> + <li> <a href="doctest/apidoc.html">APIDoc</a> -- The classes used + to encode API documentation about Python programs.</li> + <li> <a href="doctest/docintrospecter.html">Introspection</a> -- + Extracting API information about Python objects by directly + introspecting their values.</li> + <li> <a href="doctest/docparser.html">Source Code Parsing</a> -- + Extracting API information about Python objects by parsing + their source code.</li> + <li> <a href="doctest/encoding.html">Unicode & Encodings</a> -- + Tests for the processing of Python files that use non-ascii + encodings. </li> + <li> <a href="doctest/epytext.html">Epytext</a> -- The default + markup language used by epydoc.</li> +</ul> + +</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> Modified: trunk/epydoc/doc/index.html =================================================================== --- trunk/epydoc/doc/index.html 2006-08-22 16:44:27 UTC (rev 1294) +++ trunk/epydoc/doc/index.html 2006-08-22 16:45:49 UTC (rev 1295) @@ -78,6 +78,7 @@ <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="doctests.html">Regression Tests</a> </li> </ul></p> </div> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ed...@us...> - 2006-08-23 20:10:13
|
Revision: 1314 Author: edloper Date: 2006-08-23 13:10:10 -0700 (Wed, 23 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1314&view=rev Log Message: ----------- - Bumped version number to alpha3 Modified Paths: -------------- trunk/epydoc/doc/index.html trunk/epydoc/doc/whatsnew.html Modified: trunk/epydoc/doc/index.html =================================================================== --- trunk/epydoc/doc/index.html 2006-08-23 20:08:52 UTC (rev 1313) +++ trunk/epydoc/doc/index.html 2006-08-23 20:10:10 UTC (rev 1314) @@ -32,7 +32,7 @@ <div class="box"> <h2 class="box-title">News</h2> -<p><b>Epydoc 3.0 alpha 2 released [April 2006]</b><br /> The second +<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 download page</a>. See the <a href="whatsnew.html">What's New</a> Modified: trunk/epydoc/doc/whatsnew.html =================================================================== --- trunk/epydoc/doc/whatsnew.html 2006-08-23 20:08:52 UTC (rev 1313) +++ trunk/epydoc/doc/whatsnew.html 2006-08-23 20:10:10 UTC (rev 1314) @@ -12,7 +12,7 @@ <div class="box"> <h2 class="box-title">Epydoc 3.0 (alpha)</h2></td> -<center><i>Released March 8, 2006</i></center> +<center><i>Alpha 3 released August 24, 2006</i></center> <h3>Support for Parsing & Introspection</h3> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ed...@us...> - 2006-08-24 18:10:02
|
Revision: 1320 Author: edloper Date: 2006-08-24 11:09:56 -0700 (Thu, 24 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1320&view=rev Log Message: ----------- moved to doctest dir as index.html Added Paths: ----------- trunk/epydoc/doc/doctest/index.html Removed Paths: ------------- trunk/epydoc/doc/doctests.html Copied: trunk/epydoc/doc/doctest/index.html (from rev 1314, trunk/epydoc/doc/doctests.html) =================================================================== --- trunk/epydoc/doc/doctest/index.html (rev 0) +++ trunk/epydoc/doc/doctest/index.html 2006-08-24 18:09:56 UTC (rev 1320) @@ -0,0 +1,66 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> <head> +<title>Epydoc: Regression Tests</title> +<link rel="stylesheet" href="epydoc.css" type="text/css"/> +</head> +<!-- $Id: future.html 1211 2006-04-10 19:38:37Z edloper $ --> + +<body> +<div class="body"> +<h1> Epydoc: Regression Tests </h1> + +<p> The following files contain the current regression test suite for +epydoc. Each file contains a prose description of some aspect of +epydoc, interspersed with +<a href="http://docs.python.org/lib/module-doctest.html">doctest</a> +examples. Each of these doctest examples is a single test case. </p> + +<div class="box"> +<h2 class="box-title">Regression Tests</h2> + +<ul> + <li> <a href="doctest/apidoc.html">APIDoc</a> -- The classes used + to encode API documentation about Python programs.</li> + <li> <a href="doctest/docintrospecter.html">Introspection</a> -- + Extracting API information about Python objects by directly + introspecting their values.</li> + <li> <a href="doctest/docparser.html">Source Code Parsing</a> -- + Extracting API information about Python objects by parsing + their source code.</li> + <li> <a href="doctest/encoding.html">Unicode & Encodings</a> -- + Tests for the processing of Python files that use non-ascii + encodings. </li> + <li> <a href="doctest/epytext.html">Epytext</a> -- The default + markup language used by epydoc.</li> +</ul> +</div> + +</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> Deleted: trunk/epydoc/doc/doctests.html =================================================================== --- trunk/epydoc/doc/doctests.html 2006-08-24 18:07:54 UTC (rev 1319) +++ trunk/epydoc/doc/doctests.html 2006-08-24 18:09:56 UTC (rev 1320) @@ -1,62 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<html> <head> -<title>Epydoc: Regression Tests</title> -<link rel="stylesheet" href="epydoc.css" type="text/css"/> -</head> -<!-- $Id: future.html 1211 2006-04-10 19:38:37Z edloper $ --> - -<body> -<div class="body"> -<h1> Epydoc: Regression Tests </h1> - -<p> The following files contain the current regression test suite for -epydoc. Each file contains a prose description of some aspect of -epydoc, interspersed with -<a href="http://docs.python.org/lib/module-doctest.html">doctest</a> -examples. Each of these doctest examples is a single test case. </p> - -<ul> - <li> <a href="doctest/apidoc.html">APIDoc</a> -- The classes used - to encode API documentation about Python programs.</li> - <li> <a href="doctest/docintrospecter.html">Introspection</a> -- - Extracting API information about Python objects by directly - introspecting their values.</li> - <li> <a href="doctest/docparser.html">Source Code Parsing</a> -- - Extracting API information about Python objects by parsing - their source code.</li> - <li> <a href="doctest/encoding.html">Unicode & Encodings</a> -- - Tests for the processing of Python files that use non-ascii - encodings. </li> - <li> <a href="doctest/epytext.html">Epytext</a> -- The default - markup language used by epydoc.</li> -</ul> - -</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...> - 2006-09-03 05:31:38
|
Revision: 1349 http://svn.sourceforge.net/epydoc/?rev=1349&view=rev Author: edloper Date: 2006-09-02 22:31:31 -0700 (Sat, 02 Sep 2006) Log Message: ----------- made screenshot thumbnails local Modified Paths: -------------- trunk/epydoc/doc/index.html Added Paths: ----------- trunk/epydoc/doc/home.thumbnail.png trunk/epydoc/doc/index.thumbnail.png trunk/epydoc/doc/pysrc.thumbnail.png trunk/epydoc/doc/uml.thumbnail.png Added: trunk/epydoc/doc/home.thumbnail.png =================================================================== (Binary files differ) Property changes on: trunk/epydoc/doc/home.thumbnail.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: trunk/epydoc/doc/index.html =================================================================== --- trunk/epydoc/doc/index.html 2006-09-03 03:41:12 UTC (rev 1348) +++ trunk/epydoc/doc/index.html 2006-09-03 05:31:31 UTC (rev 1349) @@ -110,13 +110,13 @@ <center> <table class="transparent" cellspacing="10"> <tr> - <td class="transparent" valign="top"><a href="api/"><img src="http://sourceforge.net/dbimage.php?id=85862" alt="Generated HTML documentation for epydoc" border="0" /></a><br /> + <td class="transparent" valign="top"><a href="api/"><img src="home.thumbnail.png" alt="Generated HTML documentation for epydoc" border="0" height="75"/></a><br /> <!-- Generated HTML documentation for epydoc --> </td> - <td class="transparent" valign="top"><a href="api/epydoc.apidoc.VariableDoc-class.html"><img src="http://sourceforge.net/dbimage.php?id=85864" alt="Example of a UML graph generated by epydoc" border="0" /></a><br /> + <td class="transparent" valign="top"><a href="api/epydoc.apidoc.VariableDoc-class.html"><img src="uml.thumbnail.png" alt="Example of a UML graph generated by epydoc" border="0" height="75"/></a><br /> <!-- Example of a UML graph generated by epydoc --> </td> - <td class="transparent" valign="top"><a href="api/epydoc.apidoc-pysrc.html"><img src="http://sourceforge.net/dbimage.php?id=85866" alt="Example of syntax highlighted source, w/ links to API docs" border="0" /></a><br /> + <td class="transparent" valign="top"><a href="api/epydoc.apidoc-pysrc.html"><img src="pysrc.thumbnail.png" alt="Example of syntax highlighted source, w/ links to API docs" border="0" height="75"/></a><br /> <!-- Example of syntax highlighted source, w/ links to API docs --> </td> - <td class="transparent" valign="top"><a href="http://epydoc.sourceforge.net/stdlib/identifier-index.html"><img src="http://sourceforge.net/dbimage.php?id=85868" alt="Identifier index page for generated Python 2.4 docs" border="0" /></a><br /> + <td class="transparent" valign="top"><a href="http://epydoc.sourceforge.net/stdlib/identifier-index.html"><img src="index.thumbnail.png" alt="Identifier index page for generated Python 2.4 docs" border="0" height="75"/></a><br /> <!-- Identifier index page for generated Python 2.4 docs --> </td> </tr> </table> Added: trunk/epydoc/doc/index.thumbnail.png =================================================================== (Binary files differ) Property changes on: trunk/epydoc/doc/index.thumbnail.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/epydoc/doc/pysrc.thumbnail.png =================================================================== (Binary files differ) Property changes on: trunk/epydoc/doc/pysrc.thumbnail.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/epydoc/doc/uml.thumbnail.png =================================================================== (Binary files differ) Property changes on: trunk/epydoc/doc/uml.thumbnail.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <dva...@us...> - 2007-02-17 04:30:51
|
Revision: 1526 http://svn.sourceforge.net/epydoc/?rev=1526&view=rev Author: dvarrazzo Date: 2007-02-16 20:30:49 -0800 (Fri, 16 Feb 2007) Log Message: ----------- - Added variable docstring description (from the whatsnew). - Added table for metadata variables. - Added note about constructor parameters in class docstrings. Modified Paths: -------------- trunk/epydoc/doc/fields.html trunk/epydoc/doc/othermarkup.html Modified: trunk/epydoc/doc/fields.html =================================================================== --- trunk/epydoc/doc/fields.html 2007-02-17 02:06:45 UTC (rev 1525) +++ trunk/epydoc/doc/fields.html 2007-02-17 04:30:49 UTC (rev 1526) @@ -33,34 +33,35 @@ <table border="1" cellspacing="0" cellpadding="3"> <tr> <th width="33%">Epytext</th> - <th width="33%">ReStructuredText</th> + <th width="33%">reStructuredText</th> <th width="33%">Javadoc</th> </tr> <tr> <td> - <code>@<i>tag</i>: <i>body</i></code>...</br> - <code>@<i>tag</i> <i>arg</i>: <i>body</i></code>...</br> + <code>@<i>tag</i>: <i>body</i></code>...<br/> + <code>@<i>tag</i> <i>arg</i>: <i>body</i></code>...<br/> </td> <td> - <code>:<i>tag</i>: <i>body</i></code>...</br> - <code>:<i>tag</i> <i>arg</i>: <i>body</i></code>...</br> + <code>:<i>tag</i>: <i>body</i></code>...<br/> + <code>:<i>tag</i> <i>arg</i>: <i>body</i></code>...<br/> </td> <td> - <code>@<i>tag</i> <i>body</i></code>...</br> - <code>@<i>tag</i> <i>arg</i> <i>body</i></code>...</br> + <code>@<i>tag</i> <i>body</i></code>...<br/> + <code>@<i>tag</i> <i>arg</i> <i>body</i></code>...<br/> </td> </tr> <tr> <td align="center"><a href="epytext.html#fieldlist">Definition of<br/>epytext fields</a></td> <td align="center"><a -href="http://docutils.sourceforge.net/spec/rst/reStructuredText.html#field-lists">Definition of<br/>ReStructuredText fields</a></td> +href="http://docutils.sourceforge.net/spec/rst/reStructuredText.html#field-lists">Definition of<br/>reStructuredText fields</a></td> <td align="center"><a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html#javadoctags">Definition of<br/>Javadoc fields</a></td> </tr> </table> </center> + <a name="fields"></a> <h2> 2. Supported Fields</h2> @@ -77,11 +78,12 @@ <tr><td width="10%" align="left" valign="top"> <code>@<b>param</b> <i>p</i>:</code> ... </td><td> A description of the parameter <code><i>p</i></code> for a - function or method. </td></tr> + function or method. It may appear in the class docstring to describe + a costructor parameter: mostly useful for C extensions.</td></tr> <tr><td width="10%" align="left" valign="top"> <code>@<b>type</b> <i>p</i>:</code> ... </td><td> - The expected type for the parameter + The expected type for the parameter. <code><i>p</i></code>. </td></tr> <tr><td width="10%" align="left" valign="top"> @@ -95,16 +97,19 @@ <tr><td width="10%" align="left" valign="top"> <code>@<b>keyword</b> <i>p</i>:</code> ... </td><td> A description of the keyword parameter <code><i>p</i></code>. - </td></tr> + It may appear in the class docstring to describe + a costructor keyword parameter.</td></tr> <tr><td width="10%" align="left" valign="top"> <code>@<b>raise</b> <i>e</i>:</code> ... </td><td> A description of the circumstances under which a function or - method raises exception <code><i>e</i></code>. </td></tr> + method raises exception <code><i>e</i></code>. + It may appear in the class docstring to describe + an exception that can be raised by the costructor.</td></tr> <!-- ========== Variables ========== --> <tr><th colspan="2" align="left">Variables - <i>(module or class docstrings)</i></th></tr> + <i>(module, class or <a href="#variable-docstring">variable</a> docstrings)</i></th></tr> <tr><td width="10%" align="left" valign="top"> <code>@<b>ivar</b> <i>v</i>:</code> ... </td><td> A description of the class instance variable @@ -308,7 +313,7 @@ <code class="field">@keyword dig_deep:</code> Plant the seed deep under ground. <code class="field">@keyword soak:</code> Soak the seed before planting it. - """</code> + <code class="string">"""</code> <i>[...]</i> </pre></div> </li> @@ -323,7 +328,7 @@ <code class="field">@group Tools:</code> zip, zap, *_tool <code class="field">@group Accessors:</code> get_* <code class="field">@sort:</code> get_*, set_*, unpack_*, cut - """</code> + <code class="string">"""</code> <i>[...]</i> </pre></div> </li> @@ -341,15 +346,90 @@ <code class="field">@type person:</code> L{Person} or L{Animal} <code class="field">@param time:</code> How long they should think. <code class="field">@type time:</code> C{int} or C{float} - """</code> + <code class="string">"""</code> <i>[...]</i> </pre></div> </li> </ul> -<h2>3. Field Synonyms</h2> +<a name="locations"></a> +<h2> 3. Where to Write Fields</h2> + +<p> Normally the fields are written in the docstring of the documented +objects: this allows to add fields to modules, classes, function, properties. +Where a docstring is not allowed, usually alternative options do exist. +</p> + +<a name="variable-docstring"></a> +<h3> 3.1. Variable docstrings </h3> + +<p> Python variables don't support docstrings. The variable can be described +in the module or class where it is defined using the tags <code>@var</code>, +<code>@ivar</code>, <code>@cvar</code>; but this only allows for a textual +description: no further metadata can be added to the variable (except for the +type, using the <code>@type</code> tag. </p> + +<p> Epydoc supports <i>variable docstrings</i>: if a variable +assignment statement is immediately followed by a bare string literal, +then that assignment is treated as a docstring for that variable. In +classes, variable assignments at the class definition level are +considered class variables; and assignments to instance variables in +the constructor (<code>__init__</code>) are considered instance variables:<p> + +<div class="screen2"><pre> +<code class="prompt">>>></code> <code class="keyword">class</code> A: +<code class="prompt">...</code> x = 22 +<code class="prompt">...</code> <code class="string">"""Docstring for class variable A.x"""</code> +<code class="prompt">...</code> +<code class="prompt">...</code> <code class="keyword">def</code> <code class="function">__init__</code>(self, a): +<code class="prompt">...</code> self.y = a +<code class="prompt">...</code> <code class="string">"""Docstring for instance variable A.y</code> +</pre></div> + +<p> Variables may also be documented using <i>comment docstrings</i>. +If a variable assignment is immediately preceeded by a comment whose +lines begin with the special marker "<code><b>#:</b></code>", or is +followed on the same line by such a comment, then it is treated as a +docstring for that variable: </p> + +<div class="screen2"><pre> +<code class="prompt">>>></code> <code class="comment">#: docstring for x</code> +<code class="prompt">...</code> x = 22 +<code class="prompt">>>></code> x = 22 <code class="comment">#: docstring for x</code> +</pre></div> + +<p> A common Python idiom is to create instance variables settings their +default value in the class instead of the constructor (hopefully if the default +is immutable...). To avoid Epydoc to interpret such variable as a class +variable, you can describe it using the tag <code>@ivar</code> in the +context of a variable docstring:</p> + +<div class="screen2"><pre> +<code class="prompt">>>></code> <code class="keyword">class</code> B: +<code class="prompt">...</code> y = 42 +<code class="prompt">...</code> <code class="string">"""@ivar: This is an instance variable."""</code> +</pre></div> + +<p> Notice that variable docstrings are only available for documentation +when the source code is available for parsing: it is not possible to retrieve +variable docstrings from introspection informations only. </p> + + +<h3> 3.2. C Extensions </h3> + +<p> In a C extension module, extension classes cannot have a docstring attached +to the <code>__init__</code> function; consequently it is not possible to +document parameters and exceptions raised by the class constructor. To overcome +this shortcoming, the tags <code>@param</code>, <code>@keyword</code>, +<code>@type</code>, <code>@exception</code> are allowed to appear in the class +docstring to refer to constructor parameters. +</p> + + +<h2>4. Field Synonyms</h2> + <p> Several fields have "synonyms," or alternate tags. The following table lists all field synonyms. Field tags are written using epytext markup; if you are using a different markup language, then you should @@ -362,8 +442,8 @@ <tr><th width="50%">Name</th><th width="50%">Synonyms</th></tr> <tr><td align="left" valign="top"> <b><code>@param <i>p</i>:</code> ...</b> </td> - <td><code>@parameter <i>p</i>:</code> ...</br> - <code>@arg <i>p</i>:</code> ...</br> + <td><code>@parameter <i>p</i>:</code> ...<br/> + <code>@arg <i>p</i>:</code> ...<br/> <code>@argument <i>p</i>:</code> ...</td></tr> <tr><td align="left" valign="top"> @@ -376,8 +456,8 @@ <tr><td align="left" valign="top"> <b><code>@raise <i>e</i>:</code> ...</b> </td> - <td><code>@raises <i>e</i>:</code> ...</br> - <code>@except <i>e</i>:</code> ...</br> + <td><code>@raises <i>e</i>:</code> ...<br/> + <code>@except <i>e</i>:</code> ...<br/> <code>@exception <i>e</i>:</code> ...</td></tr> <tr><td align="left" valign="top"> @@ -412,7 +492,7 @@ <tr><td align="left" valign="top"> <b><code>@requires:</code> ...</b> </td><td> - <code>@require:</code> ... </br> + <code>@require:</code> ... <br/> <code>@requirement:</code> ... </td></tr> <tr><td align="left" valign="top"> @@ -438,9 +518,55 @@ </td></tr></table> </center> -<a name="newfield"> -<h2> 4. Adding New Fields</h2></a> +<a name="metadata-variable"></a> +<h3> 4.1. Metadata variables </h3> + +<p> Some module variables are commonly used as module metadata. Epydoc can +use the value provided by these variables as alternate form for tags. The +following table lists the recognized variables and the tag they replace. </p> + +<center> + <table border="1" cellspacing="0" cellpadding="3"> + <tr><th width="50%">Variable</th><th width="50%">Tag</th></tr> + <tr><td align="left" valign="top"> + <b><code>@deprecated</code></b></td> + <td><code>__deprecated__</code></td></tr> + + <tr><td align="left" valign="top"> + <b><code>@version</code></b></td> + <td><code>__version__</code><br/> + <code>__revision__</code></td></tr> + + <tr><td align="left" valign="top"> + <b><code>@date</code></b></td> + <td><code>__date__</code></td></tr> + + <tr><td align="left" valign="top"> + <b><code>@author</code></b><br/> + <b><code>@authors</code></b></td> + <td><code>__author__</code><br/> + <code>__authors__</code></td></tr> + + <tr><td align="left" valign="top"> + <b><code>@contact</code></b></td> + <td><code>__contact__</code></td></tr> + + <tr><td align="left" valign="top"> + <b><code>@copyright</code></b></td> + <td><code>__copyright__</code></td></tr> + + <tr><td align="left" valign="top"> + <b><code>@license</code></b></td> + <td><code>__license__</code></td></tr> + + </table> +</center> + + +<a name="newfield"></a> +<h2> 5. Adding New Fields</h2> + <p> New fields can be defined for the docstrings in a module using the special <code>@newfield</code> tag (or its synonym, <code>@deffield</code>). This tag has the following syntax:</p> @@ -464,10 +590,10 @@ """ <code class="keyword">def</code> <code class="function">example</code>(): - <code class="string">""" + <code class="string">"""</code> <code class="field">@corpus:</code> Bob's wordlist. <code class="field">@corpus:</code> The British National Corpus. - """</code> + <code class="string">"""</code> <i>[...]</i> </pre> </td><td> @@ -484,7 +610,7 @@ <code>__extra_epydoc_fields__</code> is deprecated; use <code>@newfield</code> instead.</p> -<h2> 5. Markup-Specific Notes </h2> +<h2> 6. Markup-Specific Notes </h2> <p> For the most part, fields are treated identically, regardless of what markup language is used to encode them. However, there are a few @@ -492,7 +618,7 @@ for each markup language. In particular: </p> <ul> - <li> ReStructuredText supports an extra group of fields, called + <li> reStructuredText supports an extra group of fields, called <i>consolidated fields</i>, which combine the documentation for several objects into a single field. </li> <li> Javadoc uses a special syntax for the body of the @@ -504,9 +630,9 @@ below. </p> <a name="rst"></a> -<h3> 5.1. ReStructuredText Fields </h3> +<h3> 6.1. reStructuredText Fields </h3> -<p> In ReStructuredText, a single field can be used to encode the +<p> In reStructuredText, a single field can be used to encode the documentation for a group of related items. For example, a single <code>:Parameters:</code> field is often used to describe all of the parameters for a function or method: </p> @@ -592,7 +718,7 @@ </center> -<h3> 5.2. Javadoc Fields </h3> +<h3> 6.2. Javadoc Fields </h3> <p> For compatibility with Javadoc, every <code>@see</code> field is assumed to contain a single crossreference link, unless its body Modified: trunk/epydoc/doc/othermarkup.html =================================================================== --- trunk/epydoc/doc/othermarkup.html 2007-02-17 02:06:45 UTC (rev 1525) +++ trunk/epydoc/doc/othermarkup.html 2007-02-17 04:30:49 UTC (rev 1526) @@ -16,7 +16,7 @@ <ul> <li><b><a href="http://docutils.sourceforge.net/rst.html" - >ReStructuredText</a></b> is an "easy-to-read, + >reStructuredText</a></b> is an "easy-to-read, what-you-see-is-what-you-get plaintext markup syntax." It is more powerful than epytext (e.g., it includes markup for tables and footnotes); but it is also more complex, and sometimes harder to @@ -59,23 +59,23 @@ </pre></div> <a name="restructuredtext"> -<h2>ReStructuredText</h2></a> +<h2>reStructuredText</h2></a> -<p> ReStructuredText is a markup language that was developed in +<p> reStructuredText is a markup language that was developed in conjunction with <a href="http://docutils.sourceforge.net">Docutils</a>. In order to -parse ReStructuredText docstrings, Docutils 0.3 or higher must be -installed. If Docutils is not installed, then ReStructuredText +parse reStructuredText docstrings, Docutils 0.3 or higher must be +installed. If Docutils is not installed, then reStructuredText docstrings will be rendered as plaintext. Docutils can be downloaded from the <a href="http://sourceforge.net/project/showfiles.php?group_id=38414">Docutils SourceForge page</a>. </p> <p> In addition to the <a href="fields.html#fields">standard set of -fields</a>, the ReStructruedText parser also supports +fields</a>, the reStructruedText parser also supports <i>consolidated</i> fields, which combine the documentation for several objects into a single field. For more information, see the -markup-specific notes for <a href="fields.html#rst">ReStructuredText +markup-specific notes for <a href="fields.html#rst">reStructuredText fields</a>. </p> <p> The epydoc reStructuredText reader also defines several custom <a This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <dva...@us...> - 2007-02-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: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 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: <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: <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-03-01 04:03:10
|
Revision: 1564 http://svn.sourceforge.net/epydoc/?rev=1564&view=rev Author: edloper Date: 2007-02-28 20:03:01 -0800 (Wed, 28 Feb 2007) Log Message: ----------- - Fixed svn properties Property Changed: ---------------- trunk/epydoc/doc/epydoc-slides.ppt trunk/epydoc/doc/epydoc_gui.png trunk/epydoc/doc/epydoc_guiconfig.png trunk/epydoc/doc/pycon-epydoc.pdf trunk/epydoc/doc/pycon-epydoc.ps Property changes on: trunk/epydoc/doc/epydoc-slides.ppt ___________________________________________________________________ Name: svn:keywords - Author Date Id Revision Name: svn:eol-style - native Name: svn:mime-type + application/vnd.ms-powerpoint Property changes on: trunk/epydoc/doc/epydoc_gui.png ___________________________________________________________________ Name: svn:keywords - Author Date Id Revision Property changes on: trunk/epydoc/doc/epydoc_guiconfig.png ___________________________________________________________________ Name: svn:keywords - Author Date Id Revision Property changes on: trunk/epydoc/doc/pycon-epydoc.pdf ___________________________________________________________________ Name: svn:keywords - Author Date Id Revision Name: svn:eol-style - native Name: svn:mime-type + application/pdf Property changes on: trunk/epydoc/doc/pycon-epydoc.ps ___________________________________________________________________ Name: svn:mime-type + application/postscript This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ed...@us...> - 2007-03-08 21:28:09
|
Revision: 1575 http://svn.sourceforge.net/epydoc/?rev=1575&view=rev Author: edloper Date: 2007-03-08 13:28:07 -0800 (Thu, 08 Mar 2007) Log Message: ----------- fixed typos Modified Paths: -------------- trunk/epydoc/doc/fields.html trunk/epydoc/doc/manual-docstring.txt trunk/epydoc/doc/manual-othermarkup.txt Modified: trunk/epydoc/doc/fields.html =================================================================== --- trunk/epydoc/doc/fields.html 2007-03-07 02:55:14 UTC (rev 1574) +++ trunk/epydoc/doc/fields.html 2007-03-08 21:28:07 UTC (rev 1575) @@ -364,7 +364,7 @@ <h2> 3. Where to Write Fields</h2> <p> Normally the fields are written in the docstring of the documented -objects: this allows to add fields to modules, classes, function, properties. +objects: this allows you to add fields to modules, classes, function, properties. Where a docstring is not allowed, usually alternative options do exist. </p> Modified: trunk/epydoc/doc/manual-docstring.txt =================================================================== --- trunk/epydoc/doc/manual-docstring.txt 2007-03-07 02:55:14 UTC (rev 1574) +++ trunk/epydoc/doc/manual-docstring.txt 2007-03-08 21:28:07 UTC (rev 1575) @@ -104,7 +104,7 @@ 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 +methods. A Javascript snippet allows you to toggle the visibility of private objects. If a module wants to hide some of the objects it contains (either defined in Modified: trunk/epydoc/doc/manual-othermarkup.txt =================================================================== --- trunk/epydoc/doc/manual-othermarkup.txt 2007-03-07 02:55:14 UTC (rev 1574) +++ trunk/epydoc/doc/manual-othermarkup.txt 2007-03-08 21:28:07 UTC (rev 1575) @@ -381,7 +381,7 @@ Linking from standalone documents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Epydoc provides the script ``apirst2html.py`` which allows to use the +Epydoc provides the script ``apirst2html.py`` which allows you 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`_. This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ed...@us...> - 2007-09-21 22:49:33
|
Revision: 1600 http://epydoc.svn.sourceforge.net/epydoc/?rev=1600&view=rev Author: edloper Date: 2007-09-21 15:49:26 -0700 (Fri, 21 Sep 2007) Log Message: ----------- fixed svn url (sf bug #1796882) Modified Paths: -------------- trunk/epydoc/doc/installing.html trunk/epydoc/doc/manual-install.txt Modified: trunk/epydoc/doc/installing.html =================================================================== --- trunk/epydoc/doc/installing.html 2007-09-21 22:46:28 UTC (rev 1599) +++ trunk/epydoc/doc/installing.html 2007-09-21 22:49:26 UTC (rev 1600) @@ -50,7 +50,7 @@ repository</a>:</p> <div class="screen"><pre> -<code class="prompt">[/home/edloper]$</code> <code class="user">svn co https://svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc</code> +<code class="prompt">[/home/edloper]$</code> <code class="user">svn co https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc</code> <code class="prompt">[/home/edloper]$</code> <code class="user">ls epydoc</code> Makefile doc man sandbox src </pre> @@ -69,7 +69,7 @@ </div> <p>You can browse the subversion repository <a -href="http://svn.sourceforge.net/viewcvs.cgi/epydoc/trunk/epydoc/">here</a>.</p> +href="http://epydoc.svn.sourceforge.net/viewcvs.cgi/epydoc/trunk/epydoc/">here</a>.</p> <a name="rpm"></a> Modified: trunk/epydoc/doc/manual-install.txt =================================================================== --- trunk/epydoc/doc/manual-install.txt 2007-09-21 22:46:28 UTC (rev 1599) +++ trunk/epydoc/doc/manual-install.txt 2007-09-21 22:49:26 UTC (rev 1600) @@ -29,7 +29,7 @@ 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]$ svn co https://epydoc.svn.sourceforge.net/svnroot/epydoc/trunk/epydoc epydoc [/home/edloper]$ ls epydoc Makefile doc man sandbox src @@ -44,7 +44,7 @@ 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/ +.. __: http://epydoc.svn.sourceforge.net/viewcvs.cgi/epydoc/trunk/epydoc/ Installing from the RPM File This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ed...@us...> - 2008-01-30 01:56:09
|
Revision: 1685 http://epydoc.svn.sourceforge.net/epydoc/?rev=1685&view=rev Author: edloper Date: 2008-01-29 17:56:08 -0800 (Tue, 29 Jan 2008) Log Message: ----------- - Updated version string to 3.0 Modified Paths: -------------- trunk/epydoc/doc/installing.html trunk/epydoc/doc/manual-install.txt trunk/epydoc/doc/whatsnew.html Modified: trunk/epydoc/doc/installing.html =================================================================== --- trunk/epydoc/doc/installing.html 2008-01-30 01:55:13 UTC (rev 1684) +++ trunk/epydoc/doc/installing.html 2008-01-30 01:56:08 UTC (rev 1685) @@ -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.0beta1.noarch.rpm</code> +<code class="prompt">[/tmp]#</code> <code class="user">rpm -i epydoc-3.0.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.0beta1.rpm</code> +<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0.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.0beta1.win32.exe</code>. </li> + <li> Download and run <code>epydoc-3.0.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.0beta1.win32.exe</code>. </li> + <code>epydoc-3.0.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.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> +<code class="prompt">[/tmp]$</code> <code class="user">wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.tar.gz</code> +<code class="prompt">[/tmp]$</code> <code class="user">gunzip epydoc-3.0.tar.gz</code> +<code class="prompt">[/tmp]$</code> <code class="user">tar -xvf epydoc-3.0.tar</code> </pre></div></li> - <li> Use "<code>make install</code>" in the <code>eydoc-3.0beta1/</code> + <li> Use "<code>make install</code>" in the <code>eydoc-3.0/</code> directory to install epydoc. <div class="screen"><pre> -<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> +<code class="prompt">[/tmp]$</code> <code class="user">cd epydoc-3.0/</code> +<code class="prompt">[/tmp/epydoc-3.0]$</code> <code class="user">su</code> Password: -<code class="prompt">[/tmp/epydoc-3.0beta1]#</code> <code class="user">make install</code> +<code class="prompt">[/tmp/epydoc-3.0]#</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.0beta1]#</code> <code class="user">make installdocs</code> +<code class="prompt">[/tmp/epydoc-3.0]#</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.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> +<code class="prompt">[/tmp/epydoc-3.0]#</code> <code class="user">cd ..</code> +<code class="prompt">[/tmp]#</code> <code class="user">rm -r epydoc-3.0</code> +<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0.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.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> +<code class="prompt">[/tmp]$</code> <code class="user">wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.tar.gz</code> +<code class="prompt">[/tmp]$</code> <code class="user">gunzip epydoc-3.0.tar.gz</code> +<code class="prompt">[/tmp]$</code> <code class="user">tar -xvf epydoc-3.0.tar</code> </pre></div></li> <li> Use the <code>setup.py</code> script in the - <code>eydoc-3.0beta1/</code> directory to install epydoc. + <code>eydoc-3.0/</code> directory to install epydoc. <div class="screen"><pre> -<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> +<code class="prompt">[/tmp]$</code> <code class="user">cd epydoc-3.0/</code> +<code class="prompt">[/tmp/epydoc-3.0]$</code> <code class="user">su</code> Password: -<code class="prompt">[/tmp/epydoc-3.0beta1]#</code> <code class="user">python setup.py install</code> +<code class="prompt">[/tmp/epydoc-3.0]#</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.0beta1]#</code> <code class="user">cd ..</code> +<code class="prompt">[/tmp/epydoc-3.0]#</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.0beta1/doc/ /usr/share/doc/epydoc/</code> -<code class="prompt">[/tmp]#</code> <code class="user">cp epydoc-3.0beta1/man/* /usr/share/man/</code> +<code class="prompt">[/tmp]#</code> <code class="user">cp -r epydoc-3.0/doc/ /usr/share/doc/epydoc/</code> +<code class="prompt">[/tmp]#</code> <code class="user">cp epydoc-3.0/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.0beta1</code> -<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0beta1.tar</code> +<code class="prompt">[/tmp]#</code> <code class="user">rm -r epydoc-3.0</code> +<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0.tar</code> </pre></div> </li> </ol> Modified: trunk/epydoc/doc/manual-install.txt =================================================================== --- trunk/epydoc/doc/manual-install.txt 2008-01-30 01:55:13 UTC (rev 1684) +++ trunk/epydoc/doc/manual-install.txt 2008-01-30 01:56:08 UTC (rev 1685) @@ -55,17 +55,17 @@ [/tmp]$ su Password: - [/tmp]# rpm -i epydoc-3.0beta1.noarch.rpm + [/tmp]# rpm -i epydoc-3.0.noarch.rpm 3. Once epydoc is installed, you can delete the RPM file. :: - [/tmp]# rm epydoc-3.0beta1.rpm + [/tmp]# rm epydoc-3.0.rpm Installing from the Windows Installer ------------------------------------- -1. Download and run ``epydoc-3.0beta1.win32.exe``. +1. Download and run ``epydoc-3.0.win32.exe``. 2. Follow the on-screen instructions. Epydoc will be installed in the epydoc subdirectory of your Python installation directory (typically ``C:\Python24\``). @@ -74,7 +74,7 @@ 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``. +4. Once epydoc is installed, you can delete ``epydoc-3.0.win32.exe``. Installing from the Source Distribution (using make) @@ -83,17 +83,17 @@ 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 + [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.tar.gz + [/tmp]$ gunzip epydoc-3.0.tar.gz + [/tmp]$ tar -xvf epydoc-3.0.tar -2. Use ``make install`` in the ``eydoc-3.0beta1/`` directory to install +2. Use ``make install`` in the ``eydoc-3.0/`` directory to install epydoc. :: - [/tmp]$ cd epydoc-3.0beta1/ - [/tmp/epydoc-3.0beta1]$ su + [/tmp]$ cd epydoc-3.0/ + [/tmp/epydoc-3.0]$ su Password: - [/tmp/epydoc-3.0beta1]# make install + [/tmp/epydoc-3.0]# make install running install running build [...] @@ -107,14 +107,14 @@ ``/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 + [/tmp/epydoc-3.0]# 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 + [/tmp/epydoc-3.0]# cd .. + [/tmp]# rm -r epydoc-3.0 + [/tmp]# rm epydoc-3.0.tar Installing from the Source Distribution (without make) @@ -123,37 +123,37 @@ 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 + [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.tar.gz + [/tmp]$ gunzip epydoc-3.0.tar.gz + [/tmp]$ tar -xvf epydoc-3.0.tar -2. Use the ``setup.py`` script in the ``eydoc-3.0beta1/`` directory to install +2. Use the ``setup.py`` script in the ``eydoc-3.0/`` directory to install epydoc. :: - [/tmp]$ cd epydoc-3.0beta1/ - [/tmp/epydoc-3.0beta1]$ su + [/tmp]$ cd epydoc-3.0/ + [/tmp/epydoc-3.0]$ su Password: - [/tmp/epydoc-3.0beta1]# python setup.py install + [/tmp/epydoc-3.0]# 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/epydoc-3.0]# 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/ + [/tmp]# cp -r epydoc-3.0/doc/ /usr/share/doc/epydoc/ + [/tmp]# cp epydoc-3.0/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 + [/tmp]# rm -r epydoc-3.0 + [/tmp]# rm epydoc-3.0.tar Installing on Debian Modified: trunk/epydoc/doc/whatsnew.html =================================================================== --- trunk/epydoc/doc/whatsnew.html 2008-01-30 01:55:13 UTC (rev 1684) +++ trunk/epydoc/doc/whatsnew.html 2008-01-30 01:56:08 UTC (rev 1685) @@ -10,8 +10,8 @@ <h1> What's New in Epydoc </h1> <div class="box"> -<h2 class="box-title">Epydoc 3.0 (beta)</h2> -<center><i>Beta 1 released February, 2007</i></center> +<h2 class="box-title">Epydoc 3.0</h2> +<center><i>Released January, 2008</i></center> <h3>Support for Parsing & Introspection</h3> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
From: <ed...@us...> - 2008-01-30 17:11:31
|
Revision: 1692 http://epydoc.svn.sourceforge.net/epydoc/?rev=1692&view=rev Author: edloper Date: 2008-01-30 09:11:29 -0800 (Wed, 30 Jan 2008) Log Message: ----------- - Bumped version to 3.0.1, for the GUI fix. Modified Paths: -------------- trunk/epydoc/doc/installing.html trunk/epydoc/doc/manual-install.txt Modified: trunk/epydoc/doc/installing.html =================================================================== --- trunk/epydoc/doc/installing.html 2008-01-30 17:11:09 UTC (rev 1691) +++ trunk/epydoc/doc/installing.html 2008-01-30 17:11:29 UTC (rev 1692) @@ -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.0.noarch.rpm</code> +<code class="prompt">[/tmp]#</code> <code class="user">rpm -i epydoc-3.0.1.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.0.rpm</code> +<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0.1.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.0.win32.exe</code>. </li> + <li> Download and run <code>epydoc-3.0.1.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.0.win32.exe</code>. </li> + <code>epydoc-3.0.1.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.0.tar.gz</code> -<code class="prompt">[/tmp]$</code> <code class="user">gunzip epydoc-3.0.tar.gz</code> -<code class="prompt">[/tmp]$</code> <code class="user">tar -xvf epydoc-3.0.tar</code> +<code class="prompt">[/tmp]$</code> <code class="user">wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.1.tar.gz</code> +<code class="prompt">[/tmp]$</code> <code class="user">gunzip epydoc-3.0.1.tar.gz</code> +<code class="prompt">[/tmp]$</code> <code class="user">tar -xvf epydoc-3.0.1.tar</code> </pre></div></li> - <li> Use "<code>make install</code>" in the <code>eydoc-3.0/</code> + <li> Use "<code>make install</code>" in the <code>eydoc-3.0.1/</code> directory to install epydoc. <div class="screen"><pre> -<code class="prompt">[/tmp]$</code> <code class="user">cd epydoc-3.0/</code> -<code class="prompt">[/tmp/epydoc-3.0]$</code> <code class="user">su</code> +<code class="prompt">[/tmp]$</code> <code class="user">cd epydoc-3.0.1/</code> +<code class="prompt">[/tmp/epydoc-3.0.1]$</code> <code class="user">su</code> Password: -<code class="prompt">[/tmp/epydoc-3.0]#</code> <code class="user">make install</code> +<code class="prompt">[/tmp/epydoc-3.0.1]#</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.0]#</code> <code class="user">make installdocs</code> +<code class="prompt">[/tmp/epydoc-3.0.1]#</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.0]#</code> <code class="user">cd ..</code> -<code class="prompt">[/tmp]#</code> <code class="user">rm -r epydoc-3.0</code> -<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0.tar</code> +<code class="prompt">[/tmp/epydoc-3.0.1]#</code> <code class="user">cd ..</code> +<code class="prompt">[/tmp]#</code> <code class="user">rm -r epydoc-3.0.1</code> +<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0.1.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.0.tar.gz</code> -<code class="prompt">[/tmp]$</code> <code class="user">gunzip epydoc-3.0.tar.gz</code> -<code class="prompt">[/tmp]$</code> <code class="user">tar -xvf epydoc-3.0.tar</code> +<code class="prompt">[/tmp]$</code> <code class="user">wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.1.tar.gz</code> +<code class="prompt">[/tmp]$</code> <code class="user">gunzip epydoc-3.0.1.tar.gz</code> +<code class="prompt">[/tmp]$</code> <code class="user">tar -xvf epydoc-3.0.1.tar</code> </pre></div></li> <li> Use the <code>setup.py</code> script in the - <code>eydoc-3.0/</code> directory to install epydoc. + <code>eydoc-3.0.1/</code> directory to install epydoc. <div class="screen"><pre> -<code class="prompt">[/tmp]$</code> <code class="user">cd epydoc-3.0/</code> -<code class="prompt">[/tmp/epydoc-3.0]$</code> <code class="user">su</code> +<code class="prompt">[/tmp]$</code> <code class="user">cd epydoc-3.0.1/</code> +<code class="prompt">[/tmp/epydoc-3.0.1]$</code> <code class="user">su</code> Password: -<code class="prompt">[/tmp/epydoc-3.0]#</code> <code class="user">python setup.py install</code> +<code class="prompt">[/tmp/epydoc-3.0.1]#</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.0]#</code> <code class="user">cd ..</code> +<code class="prompt">[/tmp/epydoc-3.0.1]#</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.0/doc/ /usr/share/doc/epydoc/</code> -<code class="prompt">[/tmp]#</code> <code class="user">cp epydoc-3.0/man/* /usr/share/man/</code> +<code class="prompt">[/tmp]#</code> <code class="user">cp -r epydoc-3.0.1/doc/ /usr/share/doc/epydoc/</code> +<code class="prompt">[/tmp]#</code> <code class="user">cp epydoc-3.0.1/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.0</code> -<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0.tar</code> +<code class="prompt">[/tmp]#</code> <code class="user">rm -r epydoc-3.0.1</code> +<code class="prompt">[/tmp]#</code> <code class="user">rm epydoc-3.0.1.tar</code> </pre></div> </li> </ol> Modified: trunk/epydoc/doc/manual-install.txt =================================================================== --- trunk/epydoc/doc/manual-install.txt 2008-01-30 17:11:09 UTC (rev 1691) +++ trunk/epydoc/doc/manual-install.txt 2008-01-30 17:11:29 UTC (rev 1692) @@ -55,17 +55,17 @@ [/tmp]$ su Password: - [/tmp]# rpm -i epydoc-3.0.noarch.rpm + [/tmp]# rpm -i epydoc-3.0.1.noarch.rpm 3. Once epydoc is installed, you can delete the RPM file. :: - [/tmp]# rm epydoc-3.0.rpm + [/tmp]# rm epydoc-3.0.1.rpm Installing from the Windows Installer ------------------------------------- -1. Download and run ``epydoc-3.0.win32.exe``. +1. Download and run ``epydoc-3.0.1.win32.exe``. 2. Follow the on-screen instructions. Epydoc will be installed in the epydoc subdirectory of your Python installation directory (typically ``C:\Python24\``). @@ -74,7 +74,7 @@ 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.0.win32.exe``. +4. Once epydoc is installed, you can delete ``epydoc-3.0.1.win32.exe``. Installing from the Source Distribution (using make) @@ -83,17 +83,17 @@ 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.0.tar.gz - [/tmp]$ gunzip epydoc-3.0.tar.gz - [/tmp]$ tar -xvf epydoc-3.0.tar + [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.1.tar.gz + [/tmp]$ gunzip epydoc-3.0.1.tar.gz + [/tmp]$ tar -xvf epydoc-3.0.1.tar -2. Use ``make install`` in the ``eydoc-3.0/`` directory to install +2. Use ``make install`` in the ``eydoc-3.0.1/`` directory to install epydoc. :: - [/tmp]$ cd epydoc-3.0/ - [/tmp/epydoc-3.0]$ su + [/tmp]$ cd epydoc-3.0.1/ + [/tmp/epydoc-3.0.1]$ su Password: - [/tmp/epydoc-3.0]# make install + [/tmp/epydoc-3.0.1]# make install running install running build [...] @@ -107,14 +107,14 @@ ``/usr/lib/doc``), then edit the ``MAN`` and ``DOC`` variables at the top of ``Makefile`` before running ``make installdocs``. :: - [/tmp/epydoc-3.0]# make installdocs + [/tmp/epydoc-3.0.1]# make installdocs 4. Once epydoc is installed, you can delete the installation directory and the source distribution file. :: - [/tmp/epydoc-3.0]# cd .. - [/tmp]# rm -r epydoc-3.0 - [/tmp]# rm epydoc-3.0.tar + [/tmp/epydoc-3.0.1]# cd .. + [/tmp]# rm -r epydoc-3.0.1 + [/tmp]# rm epydoc-3.0.1.tar Installing from the Source Distribution (without make) @@ -123,37 +123,37 @@ 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.0.tar.gz - [/tmp]$ gunzip epydoc-3.0.tar.gz - [/tmp]$ tar -xvf epydoc-3.0.tar + [/tmp]$ wget -q http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.1.tar.gz + [/tmp]$ gunzip epydoc-3.0.1.tar.gz + [/tmp]$ tar -xvf epydoc-3.0.1.tar -2. Use the ``setup.py`` script in the ``eydoc-3.0/`` directory to install +2. Use the ``setup.py`` script in the ``eydoc-3.0.1/`` directory to install epydoc. :: - [/tmp]$ cd epydoc-3.0/ - [/tmp/epydoc-3.0]$ su + [/tmp]$ cd epydoc-3.0.1/ + [/tmp/epydoc-3.0.1]$ su Password: - [/tmp/epydoc-3.0]# python setup.py install + [/tmp/epydoc-3.0.1]# 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.0]# cd .. + [/tmp/epydoc-3.0.1]# 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.0/doc/ /usr/share/doc/epydoc/ - [/tmp]# cp epydoc-3.0/man/* /usr/share/man/ + [/tmp]# cp -r epydoc-3.0.1/doc/ /usr/share/doc/epydoc/ + [/tmp]# cp epydoc-3.0.1/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.0 - [/tmp]# rm epydoc-3.0.tar + [/tmp]# rm -r epydoc-3.0.1 + [/tmp]# rm epydoc-3.0.1.tar Installing on Debian This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |