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 __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_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 __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 _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