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