mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
merge with stable
This commit is contained in:
Takayuki Shimizukawa
139
CHANGES
139
CHANGES
@@ -158,6 +158,145 @@ Documentation
|
||||
* Extended the :ref:`documentation about building extensions <dev-extensions>`.
|
||||
|
||||
|
||||
Release 1.2.3 (in development)
|
||||
==============================
|
||||
|
||||
Bugs fixed
|
||||
----------
|
||||
|
||||
* #636: Keep straight single quotes in literal blocks in the LaTeX build.
|
||||
* #1419: Generated i18n sphinx.js files are missing message catalog entries
|
||||
from '.js_t' and '.html'. The issue was introduced from Sphinx-1.1
|
||||
* #1363: Fix i18n: missing python domain's cross-references with currentmodule
|
||||
directive or currentclass directive.
|
||||
* #1444: autosummary does not create the description from attributes docstring.
|
||||
* #1457: In python3 environment, make linkcheck cause "Can't convert 'bytes'
|
||||
object to str implicitly" error when link target url has a hash part.
|
||||
Thanks to Jorge_C.
|
||||
* #1467: Exception on Python3 if nonexistent method is specified by automethod
|
||||
|
||||
Release 1.2.2 (released Mar 2, 2014)
|
||||
====================================
|
||||
|
||||
Bugs fixed
|
||||
----------
|
||||
|
||||
* PR#211: When checking for existence of the :confval:`html_logo` file, check
|
||||
the full relative path and not the basename.
|
||||
* PR#212: Fix traceback with autodoc and ``__init__`` methods without docstring.
|
||||
* PR#213: Fix a missing import in the setup command.
|
||||
* #1357: Option names documented by :rst:dir:`option` are now again allowed to
|
||||
not start with a dash or slash, and referencing them will work correctly.
|
||||
* #1358: Fix handling of image paths outside of the source directory when using
|
||||
the "wildcard" style reference.
|
||||
* #1374: Fix for autosummary generating overly-long summaries if first line
|
||||
doesn't end with a period.
|
||||
* #1383: Fix Python 2.5 compatibility of sphinx-apidoc.
|
||||
* #1391: Actually prevent using "pngmath" and "mathjax" extensions at the same
|
||||
time in sphinx-quickstart.
|
||||
* #1386: Fix bug preventing more than one theme being added by the entry point
|
||||
mechanism.
|
||||
* #1370: Ignore "toctree" nodes in text writer, instead of raising.
|
||||
* #1364: Fix 'make gettext' fails when the '.. todolist::' directive is present.
|
||||
* #1367: Fix a change of PR#96 that break sphinx.util.docfields.Field.make_field
|
||||
interface/behavior for `item` argument usage.
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
* Extended the :ref:`documentation about building extensions <dev-extensions>`.
|
||||
|
||||
|
||||
Release 1.2.1 (released Jan 19, 2014)
|
||||
=====================================
|
||||
|
||||
Bugs fixed
|
||||
----------
|
||||
|
||||
* #1335: Fix autosummary template overloading with exclamation prefix like
|
||||
``{% extends "!autosummary/class.rst" %}`` cause infinite recursive function
|
||||
call. This was caused by PR#181.
|
||||
* #1337: Fix autodoc with ``autoclass_content="both"`` uses useless
|
||||
``object.__init__`` docstring when class does not have ``__init__``.
|
||||
This was caused by a change for #1138.
|
||||
* #1340: Can't search alphabetical words on the HTML quick search generated
|
||||
with language='ja'.
|
||||
* #1319: Do not crash if the :confval:`html_logo` file does not exist.
|
||||
* #603: Do not use the HTML-ized title for building the search index (that
|
||||
resulted in "literal" being found on every page with a literal in the
|
||||
title).
|
||||
* #751: Allow production lists longer than a page in LaTeX by using longtable.
|
||||
* #764: Always look for stopwords lowercased in JS search.
|
||||
* #814: autodoc: Guard against strange type objects that don't have
|
||||
``__bases__``.
|
||||
* #932: autodoc: Do not crash if ``__doc__`` is not a string.
|
||||
* #933: Do not crash if an :rst:role:`option` value is malformed (contains
|
||||
spaces but no option name).
|
||||
* #908: On Python 3, handle error messages from LaTeX correctly in the pngmath
|
||||
extension.
|
||||
* #943: In autosummary, recognize "first sentences" to pull from the docstring
|
||||
if they contain uppercase letters.
|
||||
* #923: Take the entire LaTeX document into account when caching
|
||||
pngmath-generated images. This rebuilds them correctly when
|
||||
:confval:`pngmath_latex_preamble` changes.
|
||||
* #901: Emit a warning when using docutils' new "math" markup without a Sphinx
|
||||
math extension active.
|
||||
* #845: In code blocks, when the selected lexer fails, display line numbers
|
||||
nevertheless if configured.
|
||||
* #929: Support parsed-literal blocks in LaTeX output correctly.
|
||||
* #949: Update the tabulary.sty packed with Sphinx.
|
||||
* #1050: Add anonymous labels into ``objects.inv`` to be referenced via
|
||||
:mod:`~sphinx.ext.intersphinx`.
|
||||
* #1095: Fix print-media stylesheet being included always in the "scrolls"
|
||||
theme.
|
||||
* #1085: Fix current classname not getting set if class description has
|
||||
``:noindex:`` set.
|
||||
* #1181: Report option errors in autodoc directives more gracefully.
|
||||
* #1155: Fix autodocumenting C-defined methods as attributes in Python 3.
|
||||
* #1233: Allow finding both Python classes and exceptions with the "class" and
|
||||
"exc" roles in intersphinx.
|
||||
* #1198: Allow "image" for the "figwidth" option of the :rst:dir:`figure`
|
||||
directive as documented by docutils.
|
||||
* #1152: Fix pycode parsing errors of Python 3 code by including two grammar
|
||||
versions for Python 2 and 3, and loading the appropriate version for the
|
||||
running Python version.
|
||||
* #1017: Be helpful and tell the user when the argument to :rst:dir:`option`
|
||||
does not match the required format.
|
||||
* #1345: Fix two bugs with :confval:`nitpick_ignore`; now you don't have to
|
||||
remove the store environment for changes to have effect.
|
||||
* #1072: In the JS search, fix issues searching for upper-cased words by
|
||||
lowercasing words before stemming.
|
||||
* #1299: Make behavior of the :rst:dir:`math` directive more consistent and
|
||||
avoid producing empty environments in LaTeX output.
|
||||
* #1308: Strip HTML tags from the content of "raw" nodes before feeding it
|
||||
to the search indexer.
|
||||
* #1249: Fix duplicate LaTeX page numbering for manual documents.
|
||||
* #1292: In the linkchecker, retry HEAD requests when denied by HTTP 405.
|
||||
Also make the redirect code apparent and tweak the output a bit to be
|
||||
more obvious.
|
||||
* #1285: Avoid name clashes between C domain objects and section titles.
|
||||
* #848: Always take the newest code in incremental rebuilds with the
|
||||
:mod:`sphinx.ext.viewcode` extension.
|
||||
* #979, #1266: Fix exclude handling in ``sphinx-apidoc``.
|
||||
* #1302: Fix regression in :mod:`sphinx.ext.inheritance_diagram` when
|
||||
documenting classes that can't be pickled.
|
||||
* #1316: Remove hard-coded ``font-face`` resources from epub theme.
|
||||
* #1329: Fix traceback with empty translation msgstr in .po files.
|
||||
* #1300: Fix references not working in translated documents in some instances.
|
||||
* #1283: Fix a bug in the detection of changed files that would try to access
|
||||
doctrees of deleted documents.
|
||||
* #1330: Fix :confval:`exclude_patterns` behavior with subdirectories in the
|
||||
:confval:`html_static_path`.
|
||||
* #1323: Fix emitting empty ``<ul>`` tags in the HTML writer, which is not
|
||||
valid HTML.
|
||||
* #1147: Don't emit a sidebar search box in the "singlehtml" builder.
|
||||
|
||||
Documentation
|
||||
-------------
|
||||
|
||||
* #1325: Added a "Intersphinx" tutorial section. (:file:`doc/tutorial.rst`)
|
||||
|
||||
|
||||
Release 1.2 (released Dec 10, 2013)
|
||||
===================================
|
||||
|
||||
|
||||
2
EXAMPLES
2
EXAMPLES
@@ -166,6 +166,8 @@ Documentation using a custom theme/integrated in a site
|
||||
* ObjectListView: http://objectlistview.sourceforge.net/python
|
||||
* Open ERP: http://doc.openerp.com/
|
||||
* OpenCV: http://docs.opencv.org/
|
||||
* Open Dylan: http://opendylan.org/documentation/ and also provides
|
||||
`dylan domain <https://github.com/dylan-lang/sphinx-extensions/blob/master/dylandomain/reference.rst>`__
|
||||
* OpenLayers: http://docs.openlayers.org/
|
||||
* PyEphem: http://rhodesmill.org/pyephem/
|
||||
* German Plone user manual: http://www.hasecke.com/plone-benutzerhandbuch/
|
||||
|
||||
@@ -11,8 +11,5 @@
|
||||
import sys
|
||||
|
||||
if __name__ == '__main__':
|
||||
from sphinx import main, make_main
|
||||
if sys.argv[1:2] == ['-M']:
|
||||
sys.exit(make_main(sys.argv))
|
||||
else:
|
||||
sys.exit(main(sys.argv))
|
||||
from sphinx import main
|
||||
sys.exit(main(sys.argv))
|
||||
|
||||
@@ -41,6 +41,13 @@ if '+' in __version__ or 'pre' in __version__:
|
||||
|
||||
|
||||
def main(argv=sys.argv):
|
||||
if sys.argv[1:2] == ['-M']:
|
||||
sys.exit(make_main(argv))
|
||||
else:
|
||||
sys.exit(build_main(argv))
|
||||
|
||||
|
||||
def build_main(argv=sys.argv):
|
||||
"""Sphinx build "main" command-line entry."""
|
||||
if (sys.version_info[:3] < (2, 6, 0) or
|
||||
(3, 0, 0) <= sys.version_info[:3] < (3, 3, 0)):
|
||||
|
||||
@@ -24,6 +24,7 @@ from docutils import nodes
|
||||
from sphinx.builders import Builder
|
||||
from sphinx.util.console import purple, red, darkgreen, darkgray, \
|
||||
darkred, turquoise
|
||||
from sphinx.util.pycompat import TextIOWrapper
|
||||
|
||||
|
||||
class RedirectHandler(HTTPRedirectHandler):
|
||||
@@ -142,7 +143,10 @@ class CheckExternalLinksBuilder(Builder):
|
||||
# Read the whole document and see if #hash exists
|
||||
req = Request(req_url)
|
||||
f = opener.open(req, **kwargs)
|
||||
found = check_anchor(f, unquote(hash))
|
||||
encoding = 'utf-8'
|
||||
if hasattr(f.headers, 'get_content_charset'):
|
||||
encoding = f.headers.get_content_charset() or encoding
|
||||
found = check_anchor(TextIOWrapper(f, encoding), unquote(hash))
|
||||
f.close()
|
||||
|
||||
if not found:
|
||||
|
||||
@@ -1216,6 +1216,8 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):
|
||||
if PY3:
|
||||
def import_object(self):
|
||||
ret = ClassLevelDocumenter.import_object(self)
|
||||
if not ret:
|
||||
return ret
|
||||
obj_from_parent = self.parent.__dict__.get(self.object_name)
|
||||
if isinstance(obj_from_parent, classmethod):
|
||||
self.directivetype = 'classmethod'
|
||||
@@ -1229,6 +1231,8 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):
|
||||
else:
|
||||
def import_object(self):
|
||||
ret = ClassLevelDocumenter.import_object(self)
|
||||
if not ret:
|
||||
return ret
|
||||
if isinstance(self.object, classmethod) or \
|
||||
(isinstance(self.object, MethodType) and
|
||||
self.object.__self__ is not None):
|
||||
|
||||
@@ -66,6 +66,7 @@ from docutils import nodes
|
||||
|
||||
from sphinx import addnodes
|
||||
from sphinx.util.compat import Directive
|
||||
from sphinx.pycode import ModuleAnalyzer, PycodeError
|
||||
|
||||
|
||||
# -- autosummary_toc node ------------------------------------------------------
|
||||
@@ -193,6 +194,7 @@ class Autosummary(Directive):
|
||||
self.env = env = self.state.document.settings.env
|
||||
self.genopt = {}
|
||||
self.warnings = []
|
||||
self.result = ViewList()
|
||||
|
||||
names = [x.strip().split()[0] for x in self.content
|
||||
if x.strip() and re.search(r'^[~a-zA-Z_]', x.strip()[0])]
|
||||
@@ -250,6 +252,7 @@ class Autosummary(Directive):
|
||||
|
||||
# NB. using real_name here is important, since Documenters
|
||||
# handle module prefixes slightly differently
|
||||
self.result = ViewList() # initialize for each documenter
|
||||
documenter = get_documenter(obj, parent)(self, real_name)
|
||||
if not documenter.parse_name():
|
||||
self.warn('failed to parse name %s' % real_name)
|
||||
@@ -260,6 +263,17 @@ class Autosummary(Directive):
|
||||
items.append((display_name, '', '', real_name))
|
||||
continue
|
||||
|
||||
# try to also get a source code analyzer for attribute docs
|
||||
try:
|
||||
documenter.analyzer = ModuleAnalyzer.for_module(documenter.get_real_modname())
|
||||
# parse right now, to get PycodeErrors on parsing (results will
|
||||
# be cached anyway)
|
||||
documenter.analyzer.find_attr_docs()
|
||||
except PycodeError as err:
|
||||
documenter.env.app.debug('[autodoc] module analyzer failed: %s', err)
|
||||
# no source file -- e.g. for builtin and C modules
|
||||
documenter.analyzer = None
|
||||
|
||||
# -- Grab the signature
|
||||
|
||||
sig = documenter.format_signature()
|
||||
@@ -272,7 +286,8 @@ class Autosummary(Directive):
|
||||
|
||||
# -- Grab the summary
|
||||
|
||||
doc = list(documenter.process_doc(documenter.get_doc()))
|
||||
documenter.add_content(None)
|
||||
doc = list(documenter.process_doc([self.result.data]))
|
||||
|
||||
while doc and not doc[0].strip():
|
||||
doc.pop(0)
|
||||
|
||||
@@ -245,8 +245,8 @@ class Make(object):
|
||||
opts.extend(['-D', 'latex_paper_size=' + papersize])
|
||||
if doctreedir is None:
|
||||
doctreedir = self.builddir_join('doctrees')
|
||||
return call([sys.executable, sys.argv[0], '-b', builder,
|
||||
'-d', doctreedir, self.srcdir, self.builddir_join(builder)] + opts)
|
||||
return call([sys.executable, sys.argv[0], '-b', builder] + opts +
|
||||
['-d', doctreedir, self.srcdir, self.builddir_join(builder)])
|
||||
|
||||
|
||||
def run_make_mode(args):
|
||||
|
||||
@@ -1,3 +1,11 @@
|
||||
"""
|
||||
.. autosummary::
|
||||
|
||||
module_attr
|
||||
C.class_attr
|
||||
C.prop_attr1
|
||||
C.prop_attr2
|
||||
"""
|
||||
|
||||
def withSentence():
|
||||
'''I have a sentence which
|
||||
@@ -19,3 +27,39 @@ def emptyLine():
|
||||
However, it did't end with a period.
|
||||
'''
|
||||
pass
|
||||
|
||||
|
||||
#: This is a module attribute
|
||||
#:
|
||||
#: value is integer.
|
||||
module_attr = 1
|
||||
|
||||
|
||||
class C:
|
||||
'''
|
||||
My C class
|
||||
|
||||
with class_attr attribute
|
||||
'''
|
||||
|
||||
#: This is a class attribute
|
||||
#:
|
||||
#: value is integer.
|
||||
class_attr = 42
|
||||
|
||||
def _prop_attr_get(self):
|
||||
"""
|
||||
This is a function docstring
|
||||
|
||||
return value is string.
|
||||
"""
|
||||
return 'spam egg'
|
||||
|
||||
prop_attr1 = property(_prop_attr_get)
|
||||
|
||||
prop_attr2 = property(_prop_attr_get)
|
||||
"""
|
||||
This is a attribute docstring
|
||||
|
||||
value is string.
|
||||
"""
|
||||
|
||||
@@ -540,6 +540,9 @@ def test_generate():
|
||||
# attributes missing
|
||||
assert_warns("failed to import function 'foobar' from module 'util'",
|
||||
'function', 'util.foobar', more_content=None)
|
||||
# method missing
|
||||
assert_warns("failed to import method 'Class.foobar' from module 'test_autodoc';",
|
||||
'method', 'test_autodoc.Class.foobar', more_content=None)
|
||||
|
||||
# test auto and given content mixing
|
||||
directive.env.temp_data['py:module'] = 'test_autodoc'
|
||||
|
||||
@@ -9,12 +9,47 @@
|
||||
:license: BSD, see LICENSE for details.
|
||||
"""
|
||||
import sys
|
||||
from functools import wraps
|
||||
|
||||
from six import iteritems
|
||||
|
||||
from sphinx.ext.autosummary import mangle_signature
|
||||
|
||||
from util import with_app, test_roots
|
||||
from util import test_roots, TestApp
|
||||
|
||||
|
||||
def with_autosummary_app(*args, **kw):
|
||||
default_kw = {
|
||||
'srcdir': (test_roots / 'test-autosummary'),
|
||||
'confoverrides': {
|
||||
'extensions': ['sphinx.ext.autosummary'],
|
||||
'autosummary_generate': True,
|
||||
'source_suffix': '.rst'
|
||||
}
|
||||
}
|
||||
default_kw.update(kw)
|
||||
def generator(func):
|
||||
@wraps(func)
|
||||
def deco(*args2, **kwargs2):
|
||||
# Now, modify the python path...
|
||||
srcdir = default_kw['srcdir']
|
||||
sys.path.insert(0, srcdir)
|
||||
try:
|
||||
app = TestApp(*args, **default_kw)
|
||||
func(app, *args2, **kwargs2)
|
||||
finally:
|
||||
if srcdir in sys.path:
|
||||
sys.path.remove(srcdir)
|
||||
# remove the auto-generated dummy_module.rst
|
||||
dummy_rst = srcdir / 'dummy_module.rst'
|
||||
if dummy_rst.isfile():
|
||||
dummy_rst.unlink()
|
||||
|
||||
# don't execute cleanup if test failed
|
||||
app.cleanup()
|
||||
return deco
|
||||
return generator
|
||||
|
||||
|
||||
def test_mangle_signature():
|
||||
TEST = """
|
||||
@@ -42,28 +77,10 @@ def test_mangle_signature():
|
||||
assert res == outp, (u"'%s' -> '%s' != '%s'" % (inp, res, outp))
|
||||
|
||||
|
||||
# I can't just run this directly, because I need to monkey-patch Autosummary and
|
||||
# modify the python path BEFORE creating the app... so I use
|
||||
# _do_test_get_items_summary func just as a handy way to build the app, and
|
||||
# test_get_items_summary will do the "setup", and is what is actually discovered
|
||||
# / run by nose...
|
||||
@with_autosummary_app(buildername='html')
|
||||
def test_get_items_summary(app):
|
||||
app.builddir.rmtree(True)
|
||||
|
||||
@with_app(confoverrides={'extensions': ['sphinx.ext.autosummary'],
|
||||
'autosummary_generate': True,
|
||||
'source_suffix': '.rst'},
|
||||
buildername='html', srcdir=(test_roots / 'test-autosummary'))
|
||||
def _do_test_get_items_summary(app):
|
||||
(app.srcdir / 'contents.rst').write_text(
|
||||
'\n.. autosummary::'
|
||||
'\n :nosignatures:'
|
||||
'\n :toctree:'
|
||||
'\n '
|
||||
'\n dummy_module'
|
||||
'\n')
|
||||
|
||||
app.builder.build_all()
|
||||
|
||||
def test_get_items_summary():
|
||||
# monkey-patch Autosummary.get_items so we can easily get access to it's
|
||||
# results..
|
||||
import sphinx.ext.autosummary
|
||||
@@ -79,18 +96,7 @@ def test_get_items_summary():
|
||||
|
||||
sphinx.ext.autosummary.Autosummary.get_items = new_get_items
|
||||
try:
|
||||
# Now, modify the python path...
|
||||
srcdir = test_roots / 'test-autosummary'
|
||||
sys.path.insert(0, srcdir)
|
||||
try:
|
||||
_do_test_get_items_summary()
|
||||
finally:
|
||||
if srcdir in sys.path:
|
||||
sys.path.remove(srcdir)
|
||||
# remove the auto-generated dummy_module.rst
|
||||
dummy_rst = srcdir / 'dummy_module.rst'
|
||||
if dummy_rst.isfile():
|
||||
dummy_rst.unlink()
|
||||
app.builder.build_all()
|
||||
finally:
|
||||
sphinx.ext.autosummary.Autosummary.get_items = orig_get_items
|
||||
|
||||
@@ -98,7 +104,21 @@ def test_get_items_summary():
|
||||
'withSentence': 'I have a sentence which spans multiple lines.',
|
||||
'noSentence': "this doesn't start with a",
|
||||
'emptyLine': "This is the real summary",
|
||||
'module_attr': 'This is a module attribute',
|
||||
'C.class_attr': 'This is a class attribute',
|
||||
'C.prop_attr1': 'This is a function docstring',
|
||||
'C.prop_attr2': 'This is a attribute docstring',
|
||||
}
|
||||
for key, expected in iteritems(expected_values):
|
||||
assert autosummary_items[key][2] == expected, 'Summary for %s was %r -'\
|
||||
' expected %r' % (key, autosummary_items[key], expected)
|
||||
|
||||
|
||||
@with_autosummary_app(buildername='html')
|
||||
def test_process_doc_event(app):
|
||||
app.builddir.rmtree(True)
|
||||
|
||||
def handler(app, what, name, obj, options, lines):
|
||||
assert isinstance(lines, list)
|
||||
app.connect('autodoc-process-docstring', handler)
|
||||
app.builder.build_all()
|
||||
|
||||
Reference in New Issue
Block a user