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