[Epydoc-commits] SF.net SVN: epydoc: [1551] trunk/epydoc

[<dva...@us...>]

Revision: 1551
          http://svn.sourceforge.net/epydoc/?rev=1551&view=rev
Author:   dvarrazzo
Date:     2007-02-25 08:13:17 -0800 (Sun, 25 Feb 2007)

Log Message:
-----------
- Added :term: reST iterpreted text role to create indexed terms as X{...}
  epytext markup.

Modified Paths:
--------------
    trunk/epydoc/doc/manual-othermarkup.txt
    trunk/epydoc/src/epydoc/markup/restructuredtext.py

Modified: trunk/epydoc/doc/manual-othermarkup.txt
===================================================================
--- trunk/epydoc/doc/manual-othermarkup.txt	2007-02-25 14:35:15 UTC (rev 1550)
+++ trunk/epydoc/doc/manual-othermarkup.txt	2007-02-25 16:13:17 UTC (rev 1551)
@@ -390,6 +390,41 @@
 package with direct links to its API.
 
 
+Indexed Terms in reStructuredText
+'''''''''''''''''''''''''''''''''
+
+Epydoc uses `indexed terms`_ to create a table of terms definitions. Indexed
+terms are created using the epytext markup ``X{...}``.
+
+If you want to create indexed terms in reStructuredText modules,
+you can use the ``term`` `interpreted text role`_. For example:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Docstring Input
+     - Rendered Output
+
+   * - .. python::
+
+        def example():
+            """
+            An :term:`index term` is a term that
+            should be included in the index.
+            """
+            #[...]
+
+     -  An *index term* is a term that should be included in the index.
+   
+            ============ ==============
+                      Index
+            ===========================
+            index term   *example*
+            x intercept  *x_intercept*
+            y intercept  *x_intercept*
+            ============ ==============
+
+
 Javadoc
 -------
 

Modified: trunk/epydoc/src/epydoc/markup/restructuredtext.py
===================================================================
--- trunk/epydoc/src/epydoc/markup/restructuredtext.py	2007-02-25 14:35:15 UTC (rev 1550)
+++ trunk/epydoc/src/epydoc/markup/restructuredtext.py	2007-02-25 16:13:17 UTC (rev 1551)
@@ -78,7 +78,7 @@
 from docutils.nodes import NodeVisitor, Text, SkipChildren
 from docutils.nodes import SkipNode, TreeCopyVisitor
 from docutils.frontend import OptionParser
-from docutils.parsers.rst import directives
+from docutils.parsers.rst import directives, roles
 import docutils.nodes
 import docutils.transforms.frontmatter
 import docutils.transforms
@@ -208,6 +208,11 @@
 
     def __repr__(self): return '<ParsedRstDocstring: ...>'
 
+    def index_terms(self):
+        visitor = _TermsExtractor(self._document)
+        self._document.walkabout(visitor)
+        return visitor.terms
+
 class _EpydocReader(ApiLinkReader):
     """
     A reader that captures all errors that are generated by parsing,
@@ -318,6 +323,45 @@
     def unknown_visit(self, node):
         'Ignore all unknown nodes'
 
+class _TermsExtractor(NodeVisitor):
+    """
+    A docutils node visitor that extracts the terms from documentation.
+
+    Terms are created using the C{:term:} interpreted text role.
+    """
+    def __init__(self, document):
+        NodeVisitor.__init__(self, document)
+        
+        self.terms = None
+        """
+        The terms currently found.
+        @type: C{list}
+        """
+        
+    def visit_document(self, node):
+        self.terms = []
+        self._in_term = False
+
+    def visit_emphasis(self, node):
+        if 'term' in node.get('classes'):
+            self._in_term = True
+
+    def depart_emphasis(self, node):
+        if 'term' in node.get('classes'):
+            self._in_term = False
+
+    def visit_Text(self, node):
+        if self._in_term:
+            doc = self.document.copy()
+            doc[:] = [node.copy()]
+            self.terms.append(ParsedRstDocstring(doc))
+
+    def unknown_visit(self, node):
+        'Ignore all unknown nodes'
+
+    def unknown_departure(self, node):
+        'Ignore all unknown nodes'
+
 class _SplitFieldsTranslator(NodeVisitor):
     """
     A docutils translator that removes all fields from a document, and
@@ -653,6 +697,17 @@
 
 directives.register_directive('python', python_code_directive)
 
+def term_role(name, rawtext, text, lineno, inliner,
+            options={}, content=[]):
+
+    text = docutils.utils.unescape(text)
+    node = docutils.nodes.emphasis(rawtext, text, **options)
+    node.attributes['classes'].append('term')
+
+    return [node], []
+
+roles.register_local_role('term', term_role)
+
 ######################################################################
 #{ Graph Generation Directives
 ######################################################################


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.