diff options
Diffstat (limited to 'sandbox/tibs/pysource2/transform.py')
| -rw-r--r-- | sandbox/tibs/pysource2/transform.py | 157 |
1 files changed, 0 insertions, 157 deletions
diff --git a/sandbox/tibs/pysource2/transform.py b/sandbox/tibs/pysource2/transform.py deleted file mode 100644 index 1be37bd02..000000000 --- a/sandbox/tibs/pysource2/transform.py +++ /dev/null @@ -1,157 +0,0 @@ -"""transform.py - create a docutils Document tree from a Package or Module tree - -:Author: Tibs -:Contact: tibs@tibsnjoan.co.uk -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. -""" - -__docformat__ = 'reStructuredText' - -import os -from docutils.utils import new_document -import docutils.nodes as nodes -from package import Package, NotPython -from docutils.readers.python.moduleparser import Module, Class, Docstring - -def make_document(tree,settings=None): - """Return a docutils Document tree constructed from this Python tree. - - The tree given must be either a Package or Module tree. - """ - - # @@@ Can it ever be anything other than a package or module? - # I'd assert not - the module is the basic "smallest unit". - # Should we test that? - if isinstance(tree,Package): - document = new_document("Package %s"%tree.filename,settings) - section = make_package_section(tree) - else: - document = new_document("Module %s"%os.path.splitext(tree.filename)[0], - settings) - section = make_module_section(tree) - document.append(section) - return document - -def make_package_section(tree,parent_name=None): - """Return a docutils tree constructed from this Package tree - """ - if parent_name: - tree_name = "%s.%s"%(parent_name,tree.filename) - else: - tree_name = tree.filename - title = "Package %s"%(tree_name) - - # @@@ Do I really want to normalise (case fold, in particular) - # the id/name for this section? Python names can legitimately - # distinguish case, and whilst that's not terribly useful at - # the file level (since not all OS/filesystems keep such a - # distinction), it certainly is a valid possibility *within* - # a file... - # - # make_id() produces a name that starts with [a-z] and continues - # with a-z, 0-9 and hyphen (or something like that). - # - # fully_normalize_name() reduces spaces to single spaces (OK), - # but also lowercases. - # - # @@@ Think more on usage here, I guess - section = nodes.section(CLASS="package",id=nodes.make_id(title), - name=nodes.fully_normalize_name(title)) - title = nodes.title(text=title) - section.append(title) - - # @@@ I'm enforcing an order of modules before non-python files before - # subpackages here - # - do I really care? - # - do I want some other way order? - # - is this the best way to do it (e.g., I could sort the children - # into order first instead) - for child in tree.children: - if isinstance(child,Module): - subsection = make_module_section(child,tree_name) - section.append(subsection) - for child in tree.children: - if isinstance(child,NotPython): - subsection = make_not_python_section(child,tree_name) - section.append(subsection) - for child in tree.children: - if isinstance(child,Package): - subsection = make_package_section(child,tree_name) - section.append(subsection) - return section - -def make_module_section(tree,parent_name=None): - """Return a docutils tree constructed from this Module sub-tree - """ - module_name = os.path.splitext(tree.filename)[0] - if parent_name: - tree_name = "%s.%s"%(parent_name,module_name) - else: - tree_name = module_name - title = "Module %s"%(tree_name) - - # @@@ Same considerations on id/name as above - section = nodes.section(CLASS="module",id=nodes.make_id(title), - name=nodes.fully_normalize_name(title)) - title = nodes.title(text=title) - section.append(title) - - # Assume that the docstring must be the first child - if len(tree.children) > 0 and \ - isinstance(tree.children[0],Docstring): - section.append(make_docstring(tree.children[0])) - - # @@@ Again, I'm looking for classes before anything else - for child in tree.children: - if isinstance(child,Class): - subsection = make_class_section(child,tree_name) - section.append(subsection) - - return section - -def make_not_python_section(tree,parent_name=None): - """Return a docutils tree constructed from this NotPython (file) sub-tree - """ - if parent_name: - tree_name = "%s.%s"%(parent_name,tree.filename) - else: - tree_name = tree.filename - title = "File %s"%(tree_name) - - # @@@ Same considerations on id/name as above - section = nodes.section(CLASS="file",id=nodes.make_id(title), - name=nodes.fully_normalize_name(title)) - title = nodes.title(text=title) - section.append(title) - paragraph = nodes.paragraph(text="File ") - paragraph.append(nodes.literal(text=tree.filename)) - paragraph.append(nodes.Text(" is not a Python module.")) - section.append(paragraph) - return section - -def make_class_section(tree,parent_name): - """Return a docutils tree constructed from this Class sub-tree - """ - tree_name = "%s.%s"%(parent_name,tree.name) - title = "Class %s"%(tree_name) - - # @@@ Same considerations on id/name as above - section = nodes.section(CLASS="class",id=nodes.make_id(title), - name=nodes.fully_normalize_name(title)) - title = nodes.title(text=title) - section.append(title) - - # Assume that the docstring must be the first child - if len(tree.children) > 0 and \ - isinstance(tree.children[0],Docstring): - section.append(make_docstring(tree.children[0])) - - # @@@ Don't forget that we want base classes to be named at - # some point - - return section - -def make_docstring(docstring): - return nodes.literal_block(text=docstring.text,CLASS="docstring") |