sandbox/tibs/pysource2/transform.py

   1 """transform.py - create a docutils Document tree from a Package or Module tree
   2
   3 :Author:    Tibs
   4 :Contact:   tibs@tibsnjoan.co.uk
   5 :Revision:  $Revision$
   6 :Date:      $Date$
   7 :Copyright: This module has been placed in the public domain.
   8 """
   9
  10 __docformat__ = 'reStructuredText'
  11
  12 import os
  13 from docutils.utils import new_document
  14 import docutils.nodes as nodes
  15 from package import Package, NotPython
  16 from docutils.readers.python.moduleparser import Module, Class, Docstring
  17
  18 def make_document(tree,settings=None):
  19     """Return a docutils Document tree constructed from this Python tree.
  20
  21     The tree given must be either a Package or Module tree.
  22     """
  23
  24     # @@@ Can it ever be anything other than a package or module?
  25     # I'd assert not - the module is the basic "smallest unit".
  26     # Should we test that?
  27     if isinstance(tree,Package):
  28         document = new_document("Package %s"%tree.filename,settings)
  29         section = make_package_section(tree)
  30     else:
  31         document = new_document("Module %s"%os.path.splitext(tree.filename)[0],
  32                                 settings)
  33         section = make_module_section(tree)
  34     document.append(section)
  35     return document
  36
  37 def make_package_section(tree,parent_name=None):
  38     """Return a docutils tree constructed from this Package tree
  39     """
  40     if parent_name:
  41         tree_name = "%s.%s"%(parent_name,tree.filename)
  42     else:
  43         tree_name = tree.filename
  44     title = "Package %s"%(tree_name)
  45
  46     # @@@ Do I really want to normalise (case fold, in particular)
  47     # the id/name for this section? Python names can legitimately
  48     # distinguish case, and whilst that's not terribly useful at
  49     # the file level (since not all OS/filesystems keep such a
  50     # distinction), it certainly is a valid possibility *within*
  51     # a file...
  52     #
  53     # make_id() produces a name that starts with [a-z] and continues
  54     # with a-z, 0-9 and hyphen (or something like that).
  55     #
  56     # fully_normalize_name() reduces spaces to single spaces (OK),
  57     # but also lowercases.
  58     #
  59     # @@@ Think more on usage here, I guess
  60     section = nodes.section(CLASS="package",id=nodes.make_id(title),
  61                             name=nodes.fully_normalize_name(title))
  62     title = nodes.title(text=title)
  63     section.append(title)
  64
  65     # @@@ I'm enforcing an order of modules before non-python files before
  66     # subpackages here
  67     #     - do I really care?
  68     #     - do I want some other way order?
  69     #     - is this the best way to do it (e.g., I could sort the children
  70     #       into order first instead)
  71     for child in tree.children:
  72         if isinstance(child,Module):
  73             subsection = make_module_section(child,tree_name)
  74             section.append(subsection)
  75     for child in tree.children:
  76         if isinstance(child,NotPython):
  77             subsection = make_not_python_section(child,tree_name)
  78             section.append(subsection)
  79     for child in tree.children:
  80         if isinstance(child,Package):
  81             subsection = make_package_section(child,tree_name)
  82             section.append(subsection)
  83     return section
  84
  85 def make_module_section(tree,parent_name=None):
  86     """Return a docutils tree constructed from this Module sub-tree
  87     """
  88     module_name = os.path.splitext(tree.filename)[0]
  89     if parent_name:
  90         tree_name = "%s.%s"%(parent_name,module_name)
  91     else:
  92         tree_name = module_name
  93     title = "Module %s"%(tree_name)
  94
  95     # @@@ Same considerations on id/name as above
  96     section = nodes.section(CLASS="module",id=nodes.make_id(title),
  97                             name=nodes.fully_normalize_name(title))
  98     title = nodes.title(text=title)
  99     section.append(title)
 100
 101     # Assume that the docstring must be the first child
 102     if len(tree.children) > 0 and \
 103        isinstance(tree.children[0],Docstring):
 104         section.append(make_docstring(tree.children[0]))
 105
 106     # @@@ Again, I'm looking for classes before anything else
 107     for child in tree.children:
 108         if isinstance(child,Class):
 109             subsection = make_class_section(child,tree_name)
 110             section.append(subsection)
 111
 112     return section
 113
 114 def make_not_python_section(tree,parent_name=None):
 115     """Return a docutils tree constructed from this NotPython (file) sub-tree
 116     """
 117     if parent_name:
 118         tree_name = "%s.%s"%(parent_name,tree.filename)
 119     else:
 120         tree_name = tree.filename
 121     title = "File %s"%(tree_name)
 122
 123     # @@@ Same considerations on id/name as above
 124     section = nodes.section(CLASS="file",id=nodes.make_id(title),
 125                             name=nodes.fully_normalize_name(title))
 126     title = nodes.title(text=title)
 127     section.append(title)
 128     paragraph = nodes.paragraph(text="File ")
 129     paragraph.append(nodes.literal(text=tree.filename))
 130     paragraph.append(nodes.Text(" is not a Python module."))
 131     section.append(paragraph)
 132     return section
 133
 134 def make_class_section(tree,parent_name):
 135     """Return a docutils tree constructed from this Class sub-tree
 136     """
 137     tree_name = "%s.%s"%(parent_name,tree.name)
 138     title = "Class %s"%(tree_name)
 139
 140     # @@@ Same considerations on id/name as above
 141     section = nodes.section(CLASS="class",id=nodes.make_id(title),
 142                             name=nodes.fully_normalize_name(title))
 143     title = nodes.title(text=title)
 144     section.append(title)
 145
 146     # Assume that the docstring must be the first child
 147     if len(tree.children) > 0 and \
 148        isinstance(tree.children[0],Docstring):
 149         section.append(make_docstring(tree.children[0]))
 150
 151     # @@@ Don't forget that we want base classes to be named at
 152     # some point
 153
 154     return section
 155
 156 def make_docstring(docstring):
 157     return nodes.literal_block(text=docstring.text,CLASS="docstring")