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 __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 _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 _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 __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('')