Package logilab :: Package common :: Module sphinx_ext

[frames] | no frames]

# Source Code for Module logilab.common.sphinx_ext

     1  # copyright 2003-2011 LOGILAB S.A. (Paris, FRANCE), all rights reserved.
     2  # contact http://www.logilab.fr/ -- mailto:contact@logilab.fr
     3  #
     4  # This file is part of logilab-common.
     5  #
     6  # logilab-common is free software: you can redistribute it and/or modify it under
     7  # the terms of the GNU Lesser General Public License as published by the Free
     8  # Software Foundation, either version 2.1 of the License, or (at your option) any
     9  # later version.
    10  #
    11  # logilab-common is distributed in the hope that it will be useful, but WITHOUT
    12  # ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    13  # FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
    14  # details.
    15  #
    16  # You should have received a copy of the GNU Lesser General Public License along
    17  # with logilab-common.  If not, see <http://www.gnu.org/licenses/>.
    18  from logilab.common.decorators import monkeypatch
    19
    20  from sphinx.ext import autodoc
    21
    22 -class DocstringOnlyModuleDocumenter(autodoc.ModuleDocumenter):
    23      objtype = 'docstring'
    24 -    def format_signature(self):
    25          pass
    26 -    def add_directive_header(self, sig):
    27          pass
    28 -    def document_members(self, all_members=False):
    29          pass
    30
    31 -    def resolve_name(self, modname, parents, path, base):
    32          if modname is not None:
    33              return modname, parents + [base]
    34          return (path or '') + base, []
    35
    36
    37  #autodoc.add_documenter(DocstringOnlyModuleDocumenter)
    38
    39 -def setup(app):
    40      app.add_autodocumenter(DocstringOnlyModuleDocumenter)
    41
    42
    43
    44  from sphinx.ext.autodoc import (ViewList, Options, AutodocReporter, nodes,
    45                                  assemble_option_dict, nested_parse_with_titles)
    46
    47  @monkeypatch(autodoc.AutoDirective)
    48 -def run(self):
    49      self.filename_set = set()  # a set of dependent filenames
    50      self.reporter = self.state.document.reporter
    51      self.env = self.state.document.settings.env
    52      self.warnings = []
    53      self.result = ViewList()
    54
    55      # find out what documenter to call
    56      objtype = self.name[4:]
    57      doc_class = self._registry[objtype]
    58      # process the options with the selected documenter's option_spec
    59      self.genopt = Options(assemble_option_dict(
    60          self.options.items(), doc_class.option_spec))
    61      # generate the output
    62      documenter = doc_class(self, self.arguments[0])
    63      documenter.generate(more_content=self.content)
    64      if not self.result:
    65          return self.warnings
    66
    67      # record all filenames as dependencies -- this will at least
    68      # partially make automatic invalidation possible
    69      for fn in self.filename_set:
    70          self.env.note_dependency(fn)
    71
    72      # use a custom reporter that correctly assigns lines to source
    73      # filename/description and lineno
    74      old_reporter = self.state.memo.reporter
    75      self.state.memo.reporter = AutodocReporter(self.result,
    76                                                 self.state.memo.reporter)
    77      if self.name in ('automodule', 'autodocstring'):
    78          node = nodes.section()
    79          # necessary so that the child nodes get the right source/line set
    80          node.document = self.state.document
    81          nested_parse_with_titles(self.state, self.result, node)
    82      else:
    83          node = nodes.paragraph()
    84          node.document = self.state.document
    85          self.state.nested_parse(self.result, 0, node)
    86      self.state.memo.reporter = old_reporter
    87      return self.warnings + node.children
    88