Skip to content

Commit

Permalink
autodoc: use sourcename also for content generated by autodoc itself
Browse files Browse the repository at this point in the history 
Fixes sphinx-doc#1061
Fixes sphinx-doc#1656
  • Loading branch information
@lsaffre @birkenfeld
lsaffre authored and birkenfeld committed Jan 6, 2015
1 parent b9fe829 commit 21b8384
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 22 deletions.
50 changes: 30 additions & 20 deletions sphinx/ext/autodoc.py
View file
Expand Up @@ -481,14 +481,15 @@ def add_directive_header(self, sig):
domain = getattr(self, 'domain', 'py')
directive = getattr(self, 'directivetype', self.objtype)
name = self.format_name()
sourcename = self.get_sourcename()
self.add_line(u'.. %s:%s:: %s%s' % (domain, directive, name, sig),
'<autodoc>')
sourcename)
if self.options.noindex:
self.add_line(u' :noindex:', '<autodoc>')
self.add_line(u' :noindex:', sourcename)
if self.objpath:
# Be explicit about the module, this is necessary since .. class::
# etc. don't support a prepended module name
self.add_line(u' :module: %s' % self.modname, '<autodoc>')
self.add_line(u' :module: %s' % self.modname, sourcename)

def get_doc(self, encoding=None, ignore=1):
"""Decode and return lines of the docstring(s) for the object."""
Expand All @@ -514,18 +515,22 @@ def process_doc(self, docstrings):
for line in docstringlines:
yield line

def add_content(self, more_content, no_docstring=False):
"""Add content from docstrings, attribute documentation and user."""
# set sourcename and add content from attribute documentation
def get_sourcename(self):
if self.analyzer:
# prevent encoding errors when the file name is non-ASCII
if not isinstance(self.analyzer.srcname, text_type):
filename = text_type(self.analyzer.srcname,
sys.getfilesystemencoding(), 'replace')
else:
filename = self.analyzer.srcname
sourcename = u'%s:docstring of %s' % (filename, self.fullname)
return u'%s:docstring of %s' % (filename, self.fullname)
return u'docstring of %s' % self.fullname

def add_content(self, more_content, no_docstring=False):
"""Add content from docstrings, attribute documentation and user."""
# set sourcename and add content from attribute documentation
sourcename = self.get_sourcename()
if self.analyzer:
attr_docs = self.analyzer.find_attr_docs()
if self.objpath:
key = ('.'.join(self.objpath[:-1]), self.objpath[-1])
Expand All @@ -534,8 +539,6 @@ def add_content(self, more_content, no_docstring=False):
docstrings = [attr_docs[key]]
for i, line in enumerate(self.process_doc(docstrings)):
self.add_line(line, sourcename, i)
else:
sourcename = u'docstring of %s' % self.fullname

# add content from docstrings
if not no_docstring:
Expand Down Expand Up @@ -794,17 +797,19 @@ def generate(self, more_content=None, real_modname=None,
if not self.check_module():
return

sourcename = self.get_sourcename()

# make sure that the result starts with an empty line. This is
# necessary for some situations where another directive preprocesses
# reST and no starting newline is present
self.add_line(u'', '<autodoc>')
self.add_line(u'', sourcename)

# format the object's signature, if any
sig = self.format_signature()

# generate the directive header and options, if applicable
self.add_directive_header(sig)
self.add_line(u'', '<autodoc>')
self.add_line(u'', sourcename)

# e.g. the module directive doesn't have content
self.indent += self.content_indent
Expand Down Expand Up @@ -854,15 +859,17 @@ def parse_name(self):
def add_directive_header(self, sig):
Documenter.add_directive_header(self, sig)

sourcename = self.get_sourcename()

# add some module-specific options
if self.options.synopsis:
self.add_line(
u' :synopsis: ' + self.options.synopsis, '<autodoc>')
u' :synopsis: ' + self.options.synopsis, sourcename)
if self.options.platform:
self.add_line(
u' :platform: ' + self.options.platform, '<autodoc>')
u' :platform: ' + self.options.platform, sourcename)
if self.options.deprecated:
self.add_line(u' :deprecated:', '<autodoc>')
self.add_line(u' :deprecated:', sourcename)

def get_object_members(self, want_all):
if want_all:
Expand Down Expand Up @@ -1108,14 +1115,15 @@ def add_directive_header(self, sig):

# add inheritance info, if wanted
if not self.doc_as_attr and self.options.show_inheritance:
self.add_line(u'', '<autodoc>')
sourcename = self.get_sourcename()
self.add_line(u'', sourcename)
if hasattr(self.object, '__bases__') and len(self.object.__bases__):
bases = [b.__module__ in ('__builtin__', 'builtins') and
u':class:`%s`' % b.__name__ or
u':class:`%s.%s`' % (b.__module__, b.__name__)
for b in self.object.__bases__]
self.add_line(_(u' Bases: %s') % ', '.join(bases),
'<autodoc>')
sourcename)

def get_doc(self, encoding=None, ignore=1):
lines = getattr(self, '_new_docstrings', None)
Expand Down Expand Up @@ -1200,18 +1208,19 @@ def can_document_member(cls, member, membername, isattr, parent):

def add_directive_header(self, sig):
ModuleLevelDocumenter.add_directive_header(self, sig)
sourcename = self.get_sourcename()
if not self.options.annotation:
try:
objrepr = safe_repr(self.object)
except ValueError:
pass
else:
self.add_line(u' :annotation: = ' + objrepr, '<autodoc>')
self.add_line(u' :annotation: = ' + objrepr, sourcename)
elif self.options.annotation is SUPPRESS:
pass
else:
self.add_line(u' :annotation: %s' % self.options.annotation,
'<autodoc>')
sourcename)

def document_members(self, all_members=False):
pass
Expand Down Expand Up @@ -1311,19 +1320,20 @@ def get_real_modname(self):

def add_directive_header(self, sig):
ClassLevelDocumenter.add_directive_header(self, sig)
sourcename = self.get_sourcename()
if not self.options.annotation:
if not self._datadescriptor:
try:
objrepr = safe_repr(self.object)
except ValueError:
pass
else:
self.add_line(u' :annotation: = ' + objrepr, '<autodoc>')
self.add_line(u' :annotation: = ' + objrepr, sourcename)
elif self.options.annotation is SUPPRESS:
pass
else:
self.add_line(u' :annotation: %s' % self.options.annotation,
'<autodoc>')
sourcename)

def add_content(self, more_content, no_docstring=False):
if not self._datadescriptor:
Expand Down
7 changes: 5 additions & 2 deletions sphinx/ext/autosummary/__init__.py
View file
Expand Up @@ -69,6 +69,7 @@
from sphinx import addnodes
from sphinx.util.compat import Directive
from sphinx.pycode import ModuleAnalyzer, PycodeError
from sphinx.ext.autodoc import Options


# -- autosummary_toc node ------------------------------------------------------
Expand Down Expand Up @@ -131,7 +132,7 @@ def autosummary_table_visit_html(self, node):

class FakeDirective:
env = {}
genopt = {}
genopt = Options()

def get_documenter(obj, parent):
"""Get an autodoc.Documenter class suitable for documenting the given
Expand Down Expand Up @@ -194,7 +195,7 @@ def warn(self, msg):

def run(self):
self.env = env = self.state.document.settings.env
self.genopt = {}
self.genopt = Options()
self.warnings = []
self.result = ViewList()

Expand Down Expand Up @@ -269,6 +270,8 @@ def get_items(self, names):
self.warn('failed to import object %s' % real_name)
items.append((display_name, '', '', real_name))
continue
if not documenter.check_module():
continue

# try to also get a source code analyzer for attribute docs
try:
Expand Down

0 comments on commit 21b8384

Please sign in to comment.