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