[Epydoc-commits] SF.net SVN: epydoc: [1604] trunk/epydoc/doc/faq.html

[<ed...@us...>]

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.