def _get_api_index_rst(self, tools_packages):
from abjad.tools import documentationtools
document = documentationtools.ReSTDocument()
heading = documentationtools.ReSTHeading(
level=2,
text=self.api_title,
)
document.append(heading)
toc = documentationtools.ReSTTOCDirective(
options={
'maxdepth': 3,
'includehidden': True,
},
)
for tools_package in tools_packages:
if self.__class__.__name__.startswith('ScoreLibrary'):
tools_package_parts = tools_package.__name__.split('.')
else:
tools_package_parts = tools_package.__name__.split('.')[1:]
tools_package_path = '/'.join(tools_package_parts)
text = '{}/index'
text = text.format(tools_package_path)
toc_item = documentationtools.ReSTTOCItem(text=text)
toc.append(toc_item)
document.append(toc)
return document
def _build_attributes_autosummary(self):
from abjad.tools import documentationtools
pieces = []
attributes = []
attributes.extend(self.readonly_properties)
attributes.extend(self.readwrite_properties)
attributes.extend(self.methods)
attributes.extend(self.class_methods)
attributes.extend(self.static_methods)
attributes.sort(key=lambda x: x.name)
attributes.extend(self.special_methods)
autosummary = documentationtools.ReSTAutosummaryDirective()
for attribute in attributes:
autosummary.append('~{}.{}'.format(
self.module_name,
attribute.name,
))
html_only = documentationtools.ReSTOnlyDirective(argument='html')
html_only.append(
documentationtools.ReSTHeading(
level=3,
text='Attribute summary',
))
html_only.append(autosummary)
pieces.append(html_only)
return pieces
def _build_bases_section(self):
from abjad.tools import documentationtools
pieces = []
pieces.append(documentationtools.ReSTHeading(
level=3,
text='Bases',
))
mro = inspect.getmro(self.subject)[1:]
for cls in mro:
packagesystem_path = '.'.join((cls.__module__, cls.__name__))
stripped_packagesystem_path = self._shrink_module_name(
packagesystem_path)
if packagesystem_path.startswith('__builtin__'):
packagesystem_path = \
packagesystem_path.partition('__builtin__.')[-1]
text = '- :py:class:`{} <{}>`'.format(
stripped_packagesystem_path,
packagesystem_path,
)
paragraph = documentationtools.ReSTParagraph(
text=text,
wrap=False,
)
pieces.append(paragraph)
return pieces
def __call__(self):
r'''Generate documentation.
Returns string.
'''
from abjad.tools import documentationtools
document = documentationtools.ReSTDocument()
stripped_function_name = self._shrink_module_name(
self.subject.__module__)
parts = self.subject.__module__.split('.')
tools_package_path = '.'.join(parts[:3])
tools_package_name, sep, function_name = \
stripped_function_name.partition('.')
banner = '{}.{}'.format(tools_package_name, function_name)
# banner = ':py:mod:`{} <{}>`.{}'.format(
# tools_package_name,
# tools_package_path,
# function_name,
# )
heading = documentationtools.ReSTHeading(
level=2,
text=banner,
)
autodoc = documentationtools.ReSTAutodocDirective(
argument=self.module_name,
directive='autofunction',
options={},
)
document.extend([heading, autodoc])
return document.rest_format
def make_subsection(banner, documenters, only_html, only_latex):
only_latex.append(
documentationtools.ReSTHeading(level=3, text=banner))
toc_html = documentationtools.ReSTTOCDirective(
options={'maxdepth': 1}, )
toc_latex = documentationtools.ReSTTOCDirective()
for documenter in documenters:
toc_entry = module_name_to_toc_entry(documenter.module_name)
toc_html.append(toc_entry)
toc_latex.append(toc_entry)
only_html.append(toc_html)
only_latex.append(toc_latex)
def _build_autosummary_section(self, banner, documenters):
from abjad.tools import documentationtools
result = []
heading = documentationtools.ReSTHeading(
level=3,
text=banner,
)
result.append(heading)
autosummary = documentationtools.ReSTAutosummaryDirective()
for documenter in documenters:
autosummary.append('~{}'.format(documenter.module_name))
result.append(autosummary)
return result
def __call__(self):
r'''Calls tools package documenter.
Generates documentation:
::
>>> module = scoretools
>>> documenter = documentationtools.ToolsPackageDocumenter(
... scoretools)
>>> restructured_text = documenter()
Returns string.
'''
from abjad.tools import documentationtools
document = documentationtools.ReSTDocument()
document.append(
documentationtools.ReSTHeading(level=2,
text=self._shrink_module_name(
self.module_name)))
document.append(
documentationtools.ReSTAutodocDirective(
argument=self.module_name,
directive='automodule',
))
html_only = documentationtools.ReSTOnlyDirective(argument='html')
if self.abstract_class_documenters:
html_only.extend(
self._build_autosummary_section(
'Abstract classes',
self.abstract_class_documenters,
))
if self.concrete_class_documenters:
html_only.extend(
self._build_autosummary_section(
'Concrete classes',
self.concrete_class_documenters,
))
if self.function_documenters:
html_only.extend(
self._build_autosummary_section(
'Functions',
self.function_documenters,
))
document.append(html_only)
return document.rest_format
def _build_attribute_section(
self,
cls,
attrs,
directive,
title,
):
from abjad.tools import documentationtools
result = []
if attrs:
result.append(documentationtools.ReSTHeading(
level=3,
text=title,
))
for attr in attrs:
options = {
#'noindex': True,
}
autodoc = documentationtools.ReSTAutodocDirective(
argument='{}.{}.{}'.format(
cls.__module__,
cls.__name__,
attr.name,
),
directive=directive,
options=options,
)
if cls is attr.defining_class:
result.append(autodoc)
else:
container = documentationtools.ReSTDirective(
argument='inherited',
directive='container',
)
container.append(autodoc)
html_only = documentationtools.ReSTDirective(
argument='html',
directive='only',
)
html_only.append(container)
result.append(html_only)
return result
def _build_bases_section(self, cls):
from abjad.tools import documentationtools
result = []
result.append(documentationtools.ReSTHeading(
level=3,
text='Bases',
))
mro = inspect.getmro(cls)[1:]
for cls in mro:
parts = cls.__module__.split('.') + [cls.__name__]
while 1 < len(parts) and parts[-1] == parts[-2]:
parts.pop()
packagesystem_path = '.'.join(parts)
text = '- :py:class:`{}`'.format(packagesystem_path)
paragraph = documentationtools.ReSTParagraph(
text=text,
wrap=False,
)
result.append(paragraph)
return result
def _build_attributes_autosummary(
self,
cls,
class_methods,
data,
inherited_attributes,
methods,
readonly_properties,
readwrite_properties,
special_methods,
static_methods,
):
r'''
'''
from abjad.tools import documentationtools
result = []
attributes = []
attributes.extend(readonly_properties)
attributes.extend(readwrite_properties)
attributes.extend(methods)
attributes.extend(class_methods)
attributes.extend(static_methods)
attributes.sort(key=lambda x: x.name)
attributes.extend(special_methods)
if attributes:
autosummary = documentationtools.ReSTAutosummaryDirective()
for attribute in attributes:
autosummary.append('~{}.{}.{}'.format(
cls.__module__,
cls.__name__,
attribute.name,
))
html_only = documentationtools.ReSTOnlyDirective(argument='html')
html_only.append(
documentationtools.ReSTHeading(
level=3,
text='Attribute summary',
))
html_only.append(autosummary)
result.append(html_only)
return result
def _build_enumeration_section(self, cls):
from abjad.tools import documentationtools
result = []
if not issubclass(cls, enum.Enum):
return result
items = sorted(cls, key=lambda x: x.name)
if items:
result.append(documentationtools.ReSTHeading(
level=3,
text='Enumeration Items',
))
for item in items:
name = item.name
value = item.value
line = '- `{}`: {}'.format(name, value)
paragraph = documentationtools.ReSTParagraph(
text=line,
wrap=False,
)
result.append(paragraph)
return result
def _build_attribute_section(self, attrs, title, directive):
from abjad.tools import documentationtools
result = []
if attrs:
result.append(documentationtools.ReSTHeading(
level=3,
text=title,
))
for attr in attrs:
autodoc = documentationtools.ReSTAutodocDirective(
argument='{}.{}'.format(
self.module_name,
attr.name,
),
directive=directive,
options={
'noindex': True,
},
)
result.append(autodoc)
return result
def _get_api_index_rst(self, tools_packages):
r'''
'''
from abjad.tools import documentationtools
document = documentationtools.ReSTDocument()
heading = documentationtools.ReSTHeading(
level=2,
text=self.api_title,
)
document.append(heading)
toc = documentationtools.ReSTTOCDirective(options={
'maxdepth': 3,
'includehidden': True,
}, )
for tools_package in tools_packages:
tools_package_parts = tools_package.__package__.split('.')[1:]
tools_package_path = '/'.join(tools_package_parts)
toc_item = documentationtools.ReSTTOCItem(
text='{}/index'.format(tools_package_path), )
toc.append(toc_item)
document.append(toc)
return document
def __call__(self):
r'''Calls class documenter.
Generates documentation.
Returns string.
'''
from abjad.tools import documentationtools
stripped_class_name = self._shrink_module_name(self.subject.__module__)
parts = self.subject.__module__.split('.')
tools_package_path = '.'.join(parts[:3])
tools_package_name, sep, class_name = stripped_class_name.partition(
'.')
banner = '{}.{}'.format(tools_package_name, class_name)
# banner = ':py:mod:`{} <{}>`.{}'.format(
# tools_package_name,
# tools_package_path,
# class_name,
# )
document = documentationtools.ReSTDocument()
document.append(documentationtools.ReSTHeading(
level=2,
text=banner,
))
# document.append(documentationtools.ReSTLineageDirective(
# argument=self.module_name,
# ))
document.append(
documentationtools.ReSTAutodocDirective(
argument=self.module_name,
directive='autoclass',
options={
#'noindex': True,
},
))
try:
lineage_heading = documentationtools.ReSTHeading(
level=3,
text='Lineage',
)
document.append(lineage_heading)
lineage_graph = self._build_lineage_graph(self.subject)
lineage_graph.attributes['background'] = 'transparent'
lineage_graph.attributes['rankdir'] = 'LR'
graphviz_directive = documentationtools.GraphvizDirective(
graph=lineage_graph, )
document.append(graphviz_directive)
except:
pass
document.extend(self._build_attributes_autosummary())
document.extend(self._build_bases_section())
# document.extend(self._build_attribute_section(
# self.data,
# 'Class variables',
# 'autodata',
# ))
document.extend(
self._build_attribute_section(
self.readonly_properties,
'Read-only properties',
'autoattribute',
))
document.extend(
self._build_attribute_section(
self.readwrite_properties,
'Read/write properties',
'autoattribute',
))
document.extend(
self._build_attribute_section(
self.methods,
'Methods',
'automethod',
))
document.extend(
self._build_attribute_section(
self.class_methods,
'Class methods',
'automethod',
))
document.extend(
self._build_attribute_section(
self.static_methods,
'Static methods',
'automethod',
))
document.extend(
self._build_attribute_section(
self.special_methods,
'Special methods',
'automethod',
))
return document.rest_format
def __call__(self, verbose=False):
r'''Calls Abjad API generator.
Returns none.
'''
from abjad.tools import documentationtools
if verbose:
print('Now writing restructured text files ...')
print('')
ignored_directory_names = [
'__pycache__',
'.git',
'.svn',
'scores',
'test',
]
ignored_directory_names.extend(self._undocumented_packages)
api_index_document = documentationtools.ReSTDocument()
api_index_document.append(
documentationtools.ReSTHeading(
level=0,
text=self._api_title,
))
documentation_sections = {}
for code_path, docs_path, package_prefix in self.path_definitions:
if not os.path.exists(code_path):
os.makedirs(code_path)
if not os.path.exists(docs_path):
os.makedirs(docs_path)
self._prune_obsolete_documents(code_path, docs_path)
for name in os.listdir(code_path):
if name in ignored_directory_names:
continue
path = os.path.join(code_path, name)
if not os.path.isdir(path):
continue
if not os.path.exists(os.path.join(path, '__init__.py')):
continue
packagesystem_path = ''.join((package_prefix, name))
module = importlib.import_module(packagesystem_path)
documenter = documentationtools.ToolsPackageDocumenter(
module,
ignored_directory_names=ignored_directory_names,
prefix=package_prefix,
)
if not documenter.all_documenters:
continue
section = documenter.documentation_section
if section not in documentation_sections:
documentation_sections[section] = []
payload = (documenter, code_path, docs_path, package_prefix)
documentation_sections[section].append(payload)
for section in sorted(documentation_sections):
documenters = sorted(
documentation_sections[section],
key=lambda x: x[0].module_name,
)
text = self._package_descriptions.get(
section,
'Undefined documentation section',
)
section_heading = documentationtools.ReSTHeading(
level=1,
text=text,
)
api_index_document.append(section_heading)
for payload in documenters:
tools_package_documenter = payload[0]
code_path = payload[1]
docs_path = payload[2]
package_prefix = payload[3]
tools_package_toc = \
tools_package_documenter.create_api_toc_section()
api_index_document.extend(tools_package_toc)
self._write_document(
tools_package_documenter,
code_path,
docs_path,
package_prefix,
)
for documenter in tools_package_documenter.all_documenters:
self._write_document(
documenter,
code_path,
docs_path,
package_prefix,
)
documentationtools.Documenter.write(
self.docs_api_index_path,
api_index_document.rest_format,
)
if verbose:
#print ''
print('... done.')
print('')
def create_api_toc_section(self):
r'''Creates a TOC section to be included in the master API index.
::
>>> module = scoretools
>>> documenter = documentationtools.ToolsPackageDocumenter(module)
>>> result = documenter.create_api_toc_section()
Returns list.
'''
from abjad.tools import documentationtools
result = []
heading = documentationtools.ReSTHeading(
level=2,
text=':py:mod:`{} <{}>`'.format(
self._shrink_module_name(self.module_name), self.module_name))
result.append(heading)
only_html = documentationtools.ReSTOnlyDirective(argument='html')
only_latex = documentationtools.ReSTOnlyDirective(argument='latex')
hidden_toc = documentationtools.ReSTTOCDirective(options={
'hidden': True,
'maxdepth': 1,
}, )
index_path = '/'.join(self.module_name.split('.')[1:] + ['index'])
hidden_toc.append(index_path)
only_html.append(hidden_toc)
def module_name_to_toc_entry(module_name):
return '/'.join(module_name.split('.')[1:-1])
def make_subsection(banner, documenters, only_html, only_latex):
only_latex.append(
documentationtools.ReSTHeading(level=3, text=banner))
toc_html = documentationtools.ReSTTOCDirective(
options={'maxdepth': 1}, )
toc_latex = documentationtools.ReSTTOCDirective()
for documenter in documenters:
toc_entry = module_name_to_toc_entry(documenter.module_name)
toc_html.append(toc_entry)
toc_latex.append(toc_entry)
only_html.append(toc_html)
only_latex.append(toc_latex)
if self.abstract_class_documenters:
make_subsection(
'Abstract classes',
self.abstract_class_documenters,
only_html,
only_latex,
)
if self.concrete_class_documenters:
make_subsection(
'Concrete classes',
self.concrete_class_documenters,
only_html,
only_latex,
)
if self.function_documenters:
make_subsection(
'Functions',
self.function_documenters,
only_html,
only_latex,
)
result.extend((only_html, only_latex))
return result
def _get_tools_package_rst(self, tools_package):
from abjad.tools import documentationtools
classes, functions = self._get_tools_package_contents(
tools_package,
)
document = documentationtools.ReSTDocument()
if self.__class__.__name__.startswith('ScoreLibrary'):
heading = documentationtools.ReSTHeading(
level=2,
text=tools_package.__name__,
)
else:
heading = documentationtools.ReSTHeading(
level=2,
text=tools_package.__name__.split('.')[-1],
)
document.append(heading)
automodule_directive = documentationtools.ReSTAutodocDirective(
argument=tools_package.__name__,
directive='automodule',
)
document.append(automodule_directive)
ignored_classes = self._get_ignored_classes()
classes = [_ for _ in classes if _ not in ignored_classes]
if not self.__class__.__name__.startswith('ScoreLibrary'):
if classes:
rule = documentationtools.ReSTHorizontalRule()
document.append(rule)
lineage_heading = documentationtools.ReSTHeading(
level=3,
text='Lineage',
)
document.append(lineage_heading)
lineage_graph = self._get_tools_package_graph(tools_package)
graphviz_directive = documentationtools.ReSTGraphvizDirective(
graph=lineage_graph,
)
graphviz_container = documentationtools.ReSTDirective(
directive='container',
argument='graphviz',
)
graphviz_container.append(graphviz_directive)
document.append(graphviz_container)
if classes:
sections = {}
for cls in classes:
documentation_section = getattr(
cls,
'__documentation_section__',
None,
)
if documentation_section is None:
#if issubclass(cls, enum.Enum):
# documentation_section = 'Enumerations'
#elif issubclass(cls, Exception):
if issubclass(cls, Exception):
documentation_section = 'Errors'
else:
documentation_section = 'Classes'
if inspect.isabstract(cls):
documentation_section = 'Abstract Classes'
if documentation_section not in sections:
sections[documentation_section] = []
sections[documentation_section].append(cls)
section_names = sorted(sections)
if 'Main Classes' in sections:
section_names.remove('Main Classes')
section_names.insert(0, 'Main Classes')
if 'Errors' in sections:
section_names.remove('Errors')
section_names.append('Errors')
for section_name in section_names:
rule = documentationtools.ReSTHorizontalRule()
document.append(rule)
heading = documentationtools.ReSTHeading(
level=3,
text=section_name,
)
document.append(heading)
toc = documentationtools.ReSTTOCDirective(
options={
'hidden': True,
},
)
for cls in sections[section_name]:
class_name = cls.__name__
if class_name == 'Index':
class_name = '_Index'
toc_item = documentationtools.ReSTTOCItem(
text=class_name,
)
toc.append(toc_item)
document.append(toc)
autosummary = documentationtools.ReSTAutosummaryDirective(
options={
'nosignatures': True,
},
)
for cls in sections[section_name]:
item = documentationtools.ReSTAutosummaryItem(
text=cls.__name__,
)
autosummary.append(item)
document.append(autosummary)
if functions:
if classes:
rule = documentationtools.ReSTHorizontalRule()
document.append(rule)
section_name = 'Functions'
heading = documentationtools.ReSTHeading(
level=3,
text=section_name,
)
document.append(heading)
toc = documentationtools.ReSTTOCDirective(
options={
'hidden': True,
},
)
for function in functions:
toc_item = documentationtools.ReSTTOCItem(
text=function.__name__,
)
toc.append(toc_item)
document.append(toc)
autosummary = documentationtools.ReSTAutosummaryDirective(
options={
'nosignatures': True,
},
)
for function in functions:
item = documentationtools.ReSTAutosummaryItem(
text=function.__name__,
)
autosummary.append(item)
document.append(autosummary)
return document
