def __init__(self, name, section_names=None, target='man'):
"""Provides a Hierarichial structure to a ReSTDocument
You can write to it similiar to as you can to a ReSTDocument but
has an innate structure for more orginaztion and abstraction.
:param name: The name of the document
:param section_names: A list of sections to be included
in the document.
:parma target: The target documentation of the Document structure
"""
super(DocumentStructure, self).__init__(target=target)
self._name = name
self._structure = OrderedDict()
self._path = [self._name]
if section_names is not None:
self._generate_structure(section_names)
class DocumentStructure(ReSTDocument):
def __init__(self, name, section_names=None, target='man'):
"""Provides a Hierarichial structure to a ReSTDocument
You can write to it similiar to as you can to a ReSTDocument but
has an innate structure for more orginaztion and abstraction.
:param name: The name of the document
:param section_names: A list of sections to be included
in the document.
:parma target: The target documentation of the Document structure
"""
super(DocumentStructure, self).__init__(target=target)
self._name = name
self._structure = OrderedDict()
self._path = [self._name]
if section_names is not None:
self._generate_structure(section_names)
@property
def name(self):
"""The name of the document structure"""
return self._name
@property
def path(self):
"""
A list of where to find a particular document structure in the
overlying document structure.
"""
return self._path
@path.setter
def path(self, value):
self._path = value
@property
def available_sections(self):
return list(self._structure)
def _generate_structure(self, section_names):
for section_name in section_names:
self.add_new_section(section_name)
def add_new_section(self, name):
"""Adds a new section to the current document structure
This document structure will be considered a section to the
current document structure but will in itself be an entirely
new document structure that can be written to and have sections
as well
:param name: The name of the section.
:rtype: DocumentStructure
:returns: A new document structure to add to but lives as a section
to the document structure it was instantiated from.
"""
# Add a new section
section = self.__class__(name=name, target=self.target)
section.path = self.path + [name]
# Indent the section apporpriately as well
section.style.indentation = self.style.indentation
section.translation_map = self.translation_map
section.hrefs = self.hrefs
self._structure[name] = section
return section
def get_section(self, name):
"""Retrieve a section"""
return self._structure[name]
def delete_section(self, name):
"""Delete a section"""
del self._structure[name]
def flush_structure(self):
"""Flushes a doc structure to a ReSTructed string
The document is flushed out in a DFS style where sections and their
subsections' values are added to the string as they are visited.
"""
# We are at the root flush the links at the beginning of the
# document
if len(self.path) == 1:
if self.hrefs:
self.style.new_paragraph()
for refname, link in self.hrefs.items():
self.style.link_target_definition(refname, link)
value = self.getvalue()
for name, section in self._structure.items():
value += section.flush_structure()
return value
def getvalue(self):
return ''.join(self._writes).encode('utf-8')
