Thread: [Epydoc-commits] SF.net SVN: epydoc: [1230] trunk/epydoc/doc/faq.html
Brought to you by:
edloper
Menu
▾
▴
epydoc-commits
|
From: <ed...@us...> - 2006-04-13 07:24:24
|
Revision: 1230 Author: edloper Date: 2006-04-13 00:24:22 -0700 (Thu, 13 Apr 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1230&view=rev Log Message: ----------- - Fixed bad links Modified Paths: -------------- trunk/epydoc/doc/faq.html Modified: trunk/epydoc/doc/faq.html =================================================================== --- trunk/epydoc/doc/faq.html 2006-04-13 07:17:41 UTC (rev 1229) +++ trunk/epydoc/doc/faq.html 2006-04-13 07:24:22 UTC (rev 1230) @@ -91,7 +91,7 @@ add support for my favorite markup language <i>xyz</i>?</p> <dd> <p>No, but you can! See the documentation for the function <a - href="http://syse.local/epydoc/api/epydoc.markup-module.html#register_markup_language" + href="epydoc.markup-module.html#register_markup_language" ><code>register_markup_language()</code></a>, which can be used to register new markup languages. If you add support for a new markup language, and believe that others might like to use it, please @@ -102,7 +102,7 @@ <dd><p>You can add new fields that describe simple metadata using the <code>@newfield</code> field. See the documentation for <a - href="http://syse.local/~edloper/epydoc/fields.html#newfield">fields</a> + href="fields.html#newfield">fields</a> for more information. </p></dd> </p></dd> </dl> @@ -250,7 +250,7 @@ generated documentation? </p></dt> <dd><p>Use the <code>@undocumented</code> field. See the documentation for <a - href="http://syse.local/~edloper/epydoc/fields.html">fields</a> for + href="fields.html">fields</a> for more information. </p></dd> </dl> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2006-08-22 15:11:20
|
Revision: 1292 Author: edloper Date: 2006-08-22 08:11:17 -0700 (Tue, 22 Aug 2006) ViewCVS: http://svn.sourceforge.net/epydoc/?rev=1292&view=rev Log Message: ----------- - Added FAQ entry for testing if epydoc is currently running Modified Paths: -------------- trunk/epydoc/doc/faq.html Modified: trunk/epydoc/doc/faq.html =================================================================== --- trunk/epydoc/doc/faq.html 2006-08-22 07:31:56 UTC (rev 1291) +++ trunk/epydoc/doc/faq.html 2006-08-22 15:11:17 UTC (rev 1292) @@ -28,6 +28,8 @@ introspection and parsing?</a></li> <li><a href="#parse_only">When should I use <code>--parse-only</code>? </a></li> + <li><a href="#is_epydoc_running">How can I test whether + epydoc is currently running?</a></li> </ul></p> <p><b>Generated Output</b> <ul class="nomargin"> @@ -175,9 +177,26 @@ non-windows machine). </li> <li>You wish to document a module where importing the module would have undesired side effects.</li> - </ul> + </ul></dd> - + <!-- QUESTION --><a name="is_epydoc_running" /> + <dt> <p><b>Q:</b> How can I test whether my program is + being documented by epydoc? + </p></dt> + + <dd> <p>Some programs or libraries need to take special actions when + being documented by epydoc. E.g., you might want your code to skip + certain set-up actions if it's just being imported to be documented. + You can test whether epydoc is currently running by testing whether + <code>'epydoc'</code> is in <code>sys.modules</code>:</p> + +<div class="screen"><pre> + >>> import sys.modules + >>> if 'epydoc' in sys.modules: + ... print 'Epydoc is running' +</pre></div> + </dd> + </dl> <!-- ==================== GENERATED OUTPUT ========================= --> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |
|
From: <ed...@us...> - 2007-02-16 07:24:06
|
Revision: 1519
http://svn.sourceforge.net/epydoc/?rev=1519&view=rev
Author: edloper
Date: 2007-02-15 23:24:02 -0800 (Thu, 15 Feb 2007)
Log Message:
-----------
- added 2 new faq entries (#url and #redirect)
Modified Paths:
--------------
trunk/epydoc/doc/faq.html
Modified: trunk/epydoc/doc/faq.html
===================================================================
--- trunk/epydoc/doc/faq.html 2007-02-16 07:23:36 UTC (rev 1518)
+++ trunk/epydoc/doc/faq.html 2007-02-16 07:24:02 UTC (rev 1519)
@@ -30,6 +30,8 @@
</a></li>
<li><a href="#is_epydoc_running">How can I test whether
epydoc is currently running?</a></li>
+ <li><a href="#speed">I'm documenting a large project. How can I make
+ epydoc go faster?</a></li>
</ul></p>
<p><b>Generated Output</b>
<ul class="nomargin">
@@ -41,13 +43,17 @@
generated documentation?</a></li>
<li><a href="#graphs">How can I include graphs in the generated output?
</a></li>
+ <li><a href="#urls">Why does epydoc add "<tt>-module</tt>" and
+ "<tt>-class</tt>" to the names of the HTML pages it generates?
+ </a></li>
+ <li><a href="#redirect">Is there a way to link to the API documentation
+ for objects using a simple URL based on the object's dotted name?
+ </a></li>
</ul></p>
<p><b>Development of Epydoc</b>
<ul class="nomargin">
<li><a href="#bug">I've found a bug in epydoc! Where should I report it?</a></li>
<li><a href="#help">I'd like to help! What can I do?</a></li>
- <li><a href="#speed">I'm documenting a large project. How can I make
- epydoc go faster?</a></li>
<!-- <li><a href="#"></a></li>-->
</ul></p>
<p><b><a href="mailto:ed...@gr...">Ask a new question...</a></b></p>
@@ -82,7 +88,7 @@
<dd><p>For many modules, <a href="epytextintro.html">epytext</a>
works well: it is very lightweight, so it won't get in the way; but
it lets you mark important information about objects. If you would
- like to use a more expressive markup language, then I recommend
+ like to use a more expressive markup language, then we recommend
using <a href="othermarkup.html">reStructuredText</a>, which is
easy to write, easy to read, and has support for a very wide array
of constructs.</p></dd>
@@ -197,6 +203,39 @@
</pre></div>
</dd>
+ <!-- QUESTION --><a name="speed" />
+ <dt><p><b>Q:</b> I'm documenting a large project. How can I make
+ epydoc go faster? </p></dt>
+ <dd><p>Try the following options: </p>
+ <table border="1" cellspacing="0" cellpadding="3">
+
+ <tr>
+ <th align="left"><code>−−no-sourcecode</code></th>
+ <td>Don't generate pages containing source code with syntax
+ highlighting.</td></tr>
+
+ <tr>
+ <th align="left"><code>−−no−private</code></th>
+ <td> Don't generate documentation for private objects.</td></tr>
+
+ <tr>
+ <th align="left"><code>−−introspect−only</code> or
+ <code>−−parse−only</code></th>
+ <td> Extract information about objects using introspection
+ <i>or</i> parsing (but not both). This may decrease the amount
+ of information that epydoc can extract from your
+ project.</td></tr>
+
+ <tr>
+ <th align="left"><code>−−docformat=plaintext</code></th>
+ <td> Format docstrings as plaintext, instead of epytext.
+ (Docstrings will be rendered verbatim).</td></tr>
+
+ </table>
+
+ <p>Also, note that including graphs in the output can
+ slow epydoc down significantly. </p></dd></dl>
+
</dl>
<!-- ==================== GENERATED OUTPUT ========================= -->
@@ -272,6 +311,38 @@
href="fields.html">fields</a> for
more information. </p></dd>
+ <!-- QUESTION --><a name="urls" />
+ <dt><p><b>Q:</b> Why does epydoc add "<tt>-module</tt>" and
+ "<tt>-class</tt>" to the names of the HTML pages it generates?
+ </p></dt>
+ <dd><p>There are two reasons. First, this ensures that the names of
+ module and class pages do not conflict with the names of existing
+ special pages. For example, if a module were named
+ "<tt>index</tt>", then naming its documentation page
+ "<tt>index.html</tt>" would interfere with the use of that name for
+ the documentation's main page. Second, it is possible to define a
+ package where a module and a class share the same name. In those
+ cases, this naming scheme ensures that the two object's pages do not
+ conflict.</p></dd>
+
+ <!-- QUESTION --><a name="redirect" />
+ <dt><p><b>Q:</b> Is there a way to link to the API documentation
+ for objects using a simple URL based on the object's dotted name?
+ </p></dt>
+
+ <dd><p>Epydoc creates a page named "<tt>redirect.html</tt>" that
+ uses javascript to automatically convert dotted names to the
+ corresponding URLs. In particular, loading the page
+ "<tt>redirect.html#<i>dotted.name</i></tt>" will automatically
+ redirect the user's browser to the URL for the object whose dotted
+ name is <tt><i>dotted.name</i></tt>. For example, a link to
+ <tt><<a href="api/redirect.html#epydoc.cli.HELP_TOPICS"
+ >redirect.html#epydoc.cli.HELP_TOPICS</a>></tt> automatically
+ redirects the browser to <tt><<a
+ href="api/epydoc.cli-module.html#HELP_TOPICS"
+ >epydoc.cli-module.html#HELP_TOPICS</a>></tt>. The redirect page can
+ be used for any object documented by epydoc, including modules,
+ classes, functions, varaibles, properties, etc. </p></dd>
</dl>
<!-- ==================== DEVELOPMENT ========================= -->
@@ -282,7 +353,7 @@
</p></dt>
<dd><p> Use the <a
href="http://sourceforge.net/tracker/?func=add&group_id=32455&atid=405618">Sourceforge
- bug tracker</a> to report bugs. If you want to hear back when I fix
+ bug tracker</a> to report bugs. If you want to hear back when we fix
it, be sure to either log in to Sourceforge, or include your email
address in the bug report.
</p></dd>
@@ -290,14 +361,14 @@
<dt><p><b>Q:</b> I'd like to help! What can I do?
</p></dt>
<dd><p> If there are any features that you want to add to Epydoc,
- I'd be happy to accept patches. Patches should be submitted with
+ we'd be happy to accept patches. Patches should be submitted with
the <a
href="http://sourceforge.net/tracker/?func=add&group_id=32455&atid=405620">Sourceforge
patch tracker</a> (be sure to describe what your patch does!). If
- you plan to make several changes, I could also add you as a
+ you plan to make several changes, we could also add you as a
developer on Sourceforge. Email me if you're interested. </p>
- <p> For a list of additions that I'd like to make to Epydoc, see
+ <p> For a list of additions that we'd like to make to Epydoc, see
the todo list in the <a href="api/">Epydoc reference
documentation</a>; or the SourceForge <a
href="http://sourceforge.net/tracker/?group_id=32455&atid=405621">feature
@@ -305,39 +376,6 @@
href="http://sourceforge.net/tracker/?group_id=32455&atid=405618">bug
tracker</a> </p></dd>
- <!-- QUESTION --><a name="speed" />
- <dt><p><b>Q:</b> I'm documenting a large project. How can I make
- epydoc go faster? </p></dt>
- <dd><p>Try the following options: </p>
- <table border="1" cellspacing="0" cellpadding="3">
-
- <tr>
- <th align="left"><code>−−no-sourcecode</code></th>
- <td>Don't generate pages containing source code with syntax
- highlighting.</td></tr>
-
- <tr>
- <th align="left"><code>−−no−private</code></th>
- <td> Don't generate documentation for private objects.</td></tr>
-
- <tr>
- <th align="left"><code>−−introspect−only</code> or
- <code>−−parse−only</code></th>
- <td> Extract information about objects using introspection
- <i>or</i> parsing (but not both). This may decrease the amount
- of information that epydoc can extract from your
- project.</td></tr>
-
- <tr>
- <th align="left"><code>−−docformat=plaintext</code></th>
- <td> Format docstrings as plaintext, instead of epytext.
- (Docstrings will be rendered verbatim).</td></tr>
-
- </table>
-
- <p>Also, note that including graphs in the output can
- slow epydoc down significantly. </p></dd></dl>
-
<!-- QUESTION TEMPLATE
<dt><p><b>Q: </b> ...</p></dt>
<dd><p> ... </p></dd> -->
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-09-22 19:32:29
|
Revision: 1604
http://epydoc.svn.sourceforge.net/epydoc/?rev=1604&view=rev
Author: edloper
Date: 2007-09-22 12:32:26 -0700 (Sat, 22 Sep 2007)
Log Message:
-----------
Added question about epytext docstrings rendered as plaintext
Modified Paths:
--------------
trunk/epydoc/doc/faq.html
Modified: trunk/epydoc/doc/faq.html
===================================================================
--- trunk/epydoc/doc/faq.html 2007-09-21 23:17:34 UTC (rev 1603)
+++ trunk/epydoc/doc/faq.html 2007-09-22 19:32:26 UTC (rev 1604)
@@ -21,6 +21,8 @@
<li><a href="#new_markup">Will you
add support for my favorite markup language <i>xyz</i>?</a></li>
<li><a href="#new_field">Is there a way to define a new field?</a></li>
+ <li><a href="#epytext_fail">Why does epydoc render one of my epytext-formatted
+ docstrings as plaintext?</a></li>
</ul></p>
<p><b>Extracting Documentation</b>
<ul class="nomargin">
@@ -111,10 +113,31 @@
<dd><p>You can add new fields that describe simple metadata using
the <code>@newfield</code> field. See the documentation for <a
href="fields.html#newfield">fields</a>
- for more information. </p></dd> </p></dd>
+ for more information. </p></dd>
</dl>
+ <!-- QUESTION --><a name="epytext_fail" />
+ <dt><p><b>Q:</b> Why does epydoc render one of my
+ epytext-formatted docstrings as plaintext? </p></dt>
+
+ <dd><p>Since epytext is used as the default markup language for
+ epydoc, it needs to be very conservative -- it will be used to
+ display many docstrings that are not explicitly written using
+ epytext, and it needs to display those docstrings in a readable way.
+ Therefore, whenever epytext encounters a docstring that doesn't
+ strictly conform to the epytext markup language, it renders it as
+ plaintext. </p>
+
+ <p>If you expect one of your docstrings to be processed using
+ epytext, but it gets rendered as plaintext, then the docstring most
+ likely contains one or more markup errors. Run epydoc with the
+ <code>-v</code> option to see markup errors, and check for an error
+ in the docstring in question. Once you fix the markup errors, the
+ docstring will be processed as expected.</p></dd>
+
+</dl>
+
<!-- ================ EXTRACTING DOCUMENTATION ===================== -->
<h2>Extracting Documentation</h2>
<dl class="faq">
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-09-23 15:17:45
|
Revision: 1619
http://epydoc.svn.sourceforge.net/epydoc/?rev=1619&view=rev
Author: edloper
Date: 2007-09-23 08:17:43 -0700 (Sun, 23 Sep 2007)
Log Message:
-----------
- Added FAQ: Why are some values listed in the details section, but not others?
Modified Paths:
--------------
trunk/epydoc/doc/faq.html
Modified: trunk/epydoc/doc/faq.html
===================================================================
--- trunk/epydoc/doc/faq.html 2007-09-23 15:07:34 UTC (rev 1618)
+++ trunk/epydoc/doc/faq.html 2007-09-23 15:17:43 UTC (rev 1619)
@@ -51,6 +51,8 @@
<li><a href="#redirect">Is there a way to link to the API documentation
for objects using a simple URL based on the object's dotted name?
</a></li>
+ <li><a href="#redundant-details">Why are some values listed in the details
+ section, but not others?</a></li>
</ul></p>
<p><b>Development of Epydoc</b>
<ul class="nomargin">
@@ -368,6 +370,28 @@
classes, functions, varaibles, properties, etc. </p></dd>
</dl>
+ <!-- QUESTION --><a name="redundant-details" />
+ <dt><p><b>Q:</b> Why are some values listed in the details
+ section, but not others?
+ </p></dt>
+
+ <dd><p>By default, epydoc will only list a value in the details
+ section if there's additional information beyond what's listed in
+ the summary section. For example, if you define a function but
+ don't give it a docstring, then all API information about that
+ function can be shown in the summary table, so no details entry will
+ be created for it. This helps keep the generated documentation
+ consise, and the information density high. However if you prefer,
+ the command-line option "<code>--redundant-details</code>" can be
+ used to tell epydoc to display all values in the details lists, even
+ if all info about them is already provided by the summary table.
+ The corresponding config file option is
+ <code>redundant-details</code>. <i>This option was added in svn
+ revision 1613, and is not yet available in the most recent
+ release.</i>
+ </p></dd>
+</dl>
+
<!-- ==================== DEVELOPMENT ========================= -->
<h2>Development of Epydoc</h2>
<dl class="faq">
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-09-26 19:23:30
|
Revision: 1657
http://epydoc.svn.sourceforge.net/epydoc/?rev=1657&view=rev
Author: edloper
Date: 2007-09-26 12:23:23 -0700 (Wed, 26 Sep 2007)
Log Message:
-----------
- Fixed html typo
Modified Paths:
--------------
trunk/epydoc/doc/faq.html
Modified: trunk/epydoc/doc/faq.html
===================================================================
--- trunk/epydoc/doc/faq.html 2007-09-26 19:03:00 UTC (rev 1656)
+++ trunk/epydoc/doc/faq.html 2007-09-26 19:23:23 UTC (rev 1657)
@@ -117,8 +117,6 @@
href="fields.html#newfield">fields</a>
for more information. </p></dd>
-</dl>
-
<!-- QUESTION --><a name="epytext_fail" />
<dt><p><b>Q:</b> Why does epydoc render one of my
epytext-formatted docstrings as plaintext? </p></dt>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
|
From: <ed...@us...> - 2007-09-26 19:25:37
|
Revision: 1658
http://epydoc.svn.sourceforge.net/epydoc/?rev=1658&view=rev
Author: edloper
Date: 2007-09-26 12:25:35 -0700 (Wed, 26 Sep 2007)
Log Message:
-----------
- Fixed html typo
Modified Paths:
--------------
trunk/epydoc/doc/faq.html
Modified: trunk/epydoc/doc/faq.html
===================================================================
--- trunk/epydoc/doc/faq.html 2007-09-26 19:23:23 UTC (rev 1657)
+++ trunk/epydoc/doc/faq.html 2007-09-26 19:25:35 UTC (rev 1658)
@@ -366,7 +366,6 @@
>epydoc.cli-module.html#HELP_TOPICS</a>></tt>. The redirect page can
be used for any object documented by epydoc, including modules,
classes, functions, varaibles, properties, etc. </p></dd>
-</dl>
<!-- QUESTION --><a name="redundant-details" />
<dt><p><b>Q:</b> Why are some values listed in the details
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
×
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.
Thanks for helping keep SourceForge clean.
X