示例#1
0
 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
示例#2
0
    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
示例#3
0
    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
示例#4
0
 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
示例#5
0
    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
示例#6
0
 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
示例#7
0
    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('')