IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge from master

Browse Source
This commit is contained in:
Jakob Lykke Andersen 2015-02-04 23:23:28 +01:00
commit 89c919911f
206 changed files with 643 additions and 395 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
AUTHORS
View File

@ -8,7 +8,7 @@ Other co-maintainers:
* Takayuki Shimizukawa <shimizukawa@gmail.com>
* Daniel Neuhäuser <@DasIch>
* Jon Waltman <@jonwaltman>
* Rob Ruana <@RelentlessIdiot>
* Rob Ruana <@RobRuana>
* Robert Lehmann <@lehmannro>
* Roland Meister <@rolmei>

18
CHANGES
View File

@ -9,9 +9,23 @@ Incompatible changes
Features added
--------------
* Added ``highlight_options`` configuration value.
* The ``language`` config value is now available in the HTML templates.
* The ``env-updated`` event can now return a value, which is interpreted
as an iterable of additional docnames that need to be rewritten.
Bugs fixed
----------
* LaTeX writer now generates correct markup for cells spanning multiple rows.
* #1674: Do not crash if a module's ``__all__`` is not a list of strings.
* #1629: Use VerbatimBorderColor to add frame to code-block in LaTeX
* On windows, make-mode didn't work on Win32 platform if sphinx was invoked as
``python sphinx-build.py``.
* #1687: linkcheck now treats 401 Unauthorized responses as "working".
* #1690: toctrees with ``glob`` option now can also contain entries for single
documents with explicit title.
Release 1.3b2 (released Dec 5, 2014)
====================================
@ -224,6 +238,10 @@ Bugs fixed
* #1585: Autosummary of modules broken in Sphinx-1.2.3.
* #1610: Sphinx cause AttributeError when MeCab search option is enabled and
python-mecab is not installed.
* #1674: Do not crash if a module's ``__all__`` is not a list of strings.
* #1673: Fix crashes with :confval:`nitpick_ignore` and ``:doc:`` references.
* #1686: ifconfig directive doesn't care about default config values.
* #1642: Fix only one search result appearing in Chrome.
Documentation
-------------

2
LICENSE
View File

@ -1,7 +1,7 @@
License for Sphinx
==================
Copyright (c) 2007-2014 by the Sphinx team (see AUTHORS file).
Copyright (c) 2007-2015 by the Sphinx team (see AUTHORS file).
All rights reserved.
Redistribution and use in source and binary forms, with or without

4
README.rst
View File

@ -51,8 +51,8 @@ Contributing
feature idea or a bug.
#. If you feel uncomfortable or uncertain about an issue or your changes, feel
free to email sphinx-dev@googlegroups.com.
#. Fork the repository on Bitbucket https://github.com/sphinx-doc/sphinx
to start making your changes to the **default** branch for next major
#. Fork the repository on GitHub https://github.com/sphinx-doc/sphinx
to start making your changes to the **master** branch for next major
version, or **stable** branch for next minor version.
#. Write a test which shows that the bug was fixed or that the feature works
as expected.

2
doc/_themes/sphinx13/layout.html vendored
View File

@ -4,7 +4,7 @@
Sphinx layout template for the sphinxdoc theme.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- extends "basic/layout.html" %}

2
doc/_themes/sphinx13/static/sphinx13.css vendored
View File

@ -4,7 +4,7 @@
*
* Sphinx stylesheet -- sphinx13 theme.
*
* :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/

2
doc/conf.py
View File

@ -15,7 +15,7 @@ templates_path = ['_templates']
exclude_patterns = ['_build']
project = 'Sphinx'
copyright = '2007-2014, Georg Brandl and the Sphinx team'
copyright = '2007-2015, Georg Brandl and the Sphinx team'
version = sphinx.__released__
release = version
show_authors = True

13
doc/config.rst
View File

@ -303,10 +303,19 @@ Project information
.. versionadded:: 0.5
.. confval:: highlight_options
A dictionary of options that modify how the lexer specified by
:confval:`highlight_language` generates highlighted source code. These are
lexer-specific; for the options understood by each, see the
`Pygments documentation <http://pygments.org/docs/lexers/>`_.
.. versionadded:: 1.3
.. confval:: pygments_style
The style name to use for Pygments highlighting of source code. The default
style is selected by the theme for HTML output, and ``'sphinx'`` otherwise.
The style name to use for Pygments highlighting of source code. If not set,
either the theme's default style or ``'sphinx'`` is selected for HTML output.
.. versionchanged:: 0.3
If the value is a fully-qualified name of a custom Pygments style class,

7
doc/extdev/appapi.rst
View File

@ -530,8 +530,15 @@ handlers to the events. Example:
Emitted when the :meth:`update` method of the build environment has
completed, that is, the environment and all doctrees are now up-to-date.
You can return an iterable of docnames from the handler. These documents
will then be considered updated, and will be (re-)written during the writing
phase.
.. versionadded:: 0.5
.. versionchanged:: 1.3
The handlers' return value is now used.
.. event:: html-collect-pages (app)
Emitted when the HTML builder is starting to write non-document pages. You

2
setup.py
View File

@ -190,7 +190,7 @@ setup(
'Topic :: Utilities',
],
platforms='any',
packages=find_packages(exclude=['test']),
packages=find_packages(exclude=['tests']),
include_package_data=True,
entry_points={
'console_scripts': [

2
sphinx-apidoc.py
View File

@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx-autogen.py
View File

@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx-build.py
View File

@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx-quickstart.py
View File

@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/__init__.py
View File

@ -5,7 +5,7 @@
The Sphinx documentation toolchain.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/__main__.py
View File

@ -5,7 +5,7 @@
The Sphinx documentation toolchain.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import sys

2
sphinx/addnodes.py
View File

@ -5,7 +5,7 @@
Additional docutils nodes.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/apidoc.py
View File

@ -11,7 +11,7 @@
Copyright 2008 Société des arts technologiques (SAT),
http://www.sat.qc.ca/
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function

4
sphinx/application.py
View File

@ -7,7 +7,7 @@
Gracefully adapted from the TextPress system by Armin.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function
@ -218,7 +218,7 @@ class Sphinx(object):
self.env.domains[domain] = self.domains[domain](self.env)
self.info('done')
except Exception as err:
if type(err) is IOError and err.errno == ENOENT:
if isinstance(err, IOError) and err.errno == ENOENT:
self.info('not yet created')
else:
self.info('failed: %s' % err)

5
sphinx/builders/__init__.py
View File

@ -5,7 +5,7 @@
Builder superclass for all builders.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -388,6 +388,9 @@ class Builder(object):
self.info(bold('waiting for workers...'))
tasks.join()
for warning in warnings:
self.warn(*warning)
def prepare_writing(self, docnames):
"""A place where you can add logic before :meth:`write_doc` is run"""
raise NotImplementedError

2
sphinx/builders/changes.py
View File

@ -5,7 +5,7 @@
Changelog builder.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/devhelp.py
View File

@ -7,7 +7,7 @@
.. _Devhelp: http://live.gnome.org/devhelp
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import absolute_import

2
sphinx/builders/epub.py
View File

@ -6,7 +6,7 @@
Build epub files.
Originally derived from qthelp.py.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/gettext.py
View File

@ -5,7 +5,7 @@
The MessageCatalogBuilder class.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

10
sphinx/builders/html.py
View File

@ -5,7 +5,7 @@
Several HTML builders.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -17,7 +17,7 @@ import posixpath
from os import path
from hashlib import md5
from six import iteritems, itervalues, text_type, string_types
from six import iteritems, text_type, string_types
from six.moves import cPickle as pickle
from docutils import nodes
from docutils.io import DocTreeInput, StringOutput
@ -268,7 +268,8 @@ class StandaloneHTMLBuilder(Builder):
# html_domain_indices can be False/True or a list of index names
indices_config = self.config.html_domain_indices
if indices_config:
for domain in itervalues(self.env.domains):
for domain_name in sorted(self.env.domains):
domain = self.env.domains[domain_name]
for indexcls in domain.indices:
indexname = '%s-%s' % (domain.name, indexcls.name)
if isinstance(indices_config, list):
@ -337,6 +338,7 @@ class StandaloneHTMLBuilder(Builder):
show_source = self.config.html_show_sourcelink,
file_suffix = self.out_suffix,
script_files = self.script_files,
language = self.config.language,
css_files = self.css_files,
sphinx_version = __version__,
style = stylename,
@ -816,7 +818,7 @@ class StandaloneHTMLBuilder(Builder):
compressor = zlib.compressobj(9)
for domainname, domain in iteritems(self.env.domains):
for name, dispname, type, docname, anchor, prio in \
domain.get_objects():
sorted(domain.get_objects()):
if anchor.endswith(name):
# this can shorten the inventory by as much as 25%
anchor = anchor[:-len(name)] + '$'

2
sphinx/builders/htmlhelp.py
View File

@ -6,7 +6,7 @@
Build HTML help support files.
Parts adapted from Python's Doc/tools/prechm.py.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function

2
sphinx/builders/latex.py
View File

@ -5,7 +5,7 @@
LaTeX builder.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

19
sphinx/builders/linkcheck.py
View File

@ -5,7 +5,7 @@
The CheckExternalLinksBuilder class.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -122,7 +122,7 @@ class CheckExternalLinksBuilder(Builder):
elif not (uri[0:5] == 'http:' or uri[0:6] == 'https:'):
return 'local', '', 0
elif uri in self.good:
return 'working', '', 0
return 'working', 'old', 0
elif uri in self.broken:
return 'broken', self.broken[uri], 0
elif uri in self.redirected:
@ -166,13 +166,20 @@ class CheckExternalLinksBuilder(Builder):
req = Request(req_url)
f = opener.open(req, **kwargs)
f.close()
except HTTPError as err:
if err.code == 401:
# We'll take "Unauthorized" as working.
self.good.add(uri)
return 'working', ' - unauthorized', 0
else:
self.broken[uri] = str(err)
return 'broken', str(err), 0
except Exception as err:
self.broken[uri] = str(err)
return 'broken', str(err), 0
if f.url.rstrip('/') == req_url.rstrip('/'):
self.good.add(uri)
return 'working', 'new', 0
return 'working', '', 0
else:
new_url = f.url
if hash:
@ -192,7 +199,7 @@ class CheckExternalLinksBuilder(Builder):
uri, docname, lineno, status, info, code = result
if status == 'unchecked':
return
if status == 'working' and info != 'new':
if status == 'working' and info == 'old':
return
if lineno:
self.info('(line %4d) ' % lineno, nonl=1)
@ -202,7 +209,7 @@ class CheckExternalLinksBuilder(Builder):
self.info(darkgray('-local- ') + uri)
self.write_entry('local', docname, lineno, uri)
elif status == 'working':
self.info(darkgreen('ok ') + uri)
self.info(darkgreen('ok ') + uri + info)
elif status == 'broken':
self.info(red('broken ') + uri + red(' - ' + info))
self.write_entry('broken', docname, lineno, uri + ': ' + info)

2
sphinx/builders/manpage.py
View File

@ -5,7 +5,7 @@
Manual pages builder.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/qthelp.py
View File

@ -5,7 +5,7 @@
Build input files for the Qt collection generator.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/texinfo.py
View File

@ -5,7 +5,7 @@
Texinfo builder.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/text.py
View File

@ -5,7 +5,7 @@
Plain-text Sphinx builder.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/websupport.py
View File

@ -5,7 +5,7 @@
Builder for the web support package.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/xml.py
View File

@ -5,7 +5,7 @@
Docutils-native XML and pseudo-XML builders.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/cmdline.py
View File

@ -5,7 +5,7 @@
sphinx-build command-line handling.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function

3
sphinx/config.py
View File

@ -5,7 +5,7 @@
Build configuration file handling.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -61,6 +61,7 @@ class Config(object):
show_authors = (False, 'env'),
pygments_style = (None, 'html'),
highlight_language = ('python', 'env'),
highlight_options = ({}, 'env'),
templates_path = ([], 'html'),
template_bridge = (None, 'html'),
keep_warnings = (False, 'env'),

2
sphinx/directives/__init__.py
View File

@ -5,7 +5,7 @@
Handlers for additional ReST directives.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/directives/code.py
View File

@ -3,7 +3,7 @@
sphinx.directives.code
~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

27
sphinx/directives/other.py
View File

@ -3,7 +3,7 @@
sphinx.directives.other
~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -62,7 +62,18 @@ class TocTree(Directive):
for entry in self.content:
if not entry:
continue
if not glob:
if glob and ('*' in entry or '?' in entry or '[' in entry):
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(self.state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents'
% entry, line=self.lineno))
else:
# look for explicit titles ("Some Title <document>")
m = explicit_title_re.match(entry)
if m:
@ -85,19 +96,9 @@ class TocTree(Directive):
'document %r' % docname, line=self.lineno))
env.note_reread()
else:
all_docnames.discard(docname)
entries.append((title, docname))
includefiles.append(docname)
else:
patname = docname_join(env.docname, entry)
docnames = sorted(patfilter(all_docnames, patname))
for docname in docnames:
all_docnames.remove(docname) # don't include it again
entries.append((None, docname))
includefiles.append(docname)
if not docnames:
ret.append(self.state.document.reporter.warning(
'toctree glob pattern %r didn\'t match any documents'
% entry, line=self.lineno))
subnode = addnodes.toctree()
subnode['parent'] = env.docname
# entries contains all entries (self references, external links etc.)

2
sphinx/domains/__init__.py
View File

@ -6,7 +6,7 @@
Support for domains, which are groupings of description directives
and roles describing e.g. constructs of one programming language.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/domains/c.py
View File

@ -5,7 +5,7 @@
The C language domain.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

178
sphinx/domains/cpp.py
View File

@ -5,7 +5,7 @@
The C++ language domain.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -858,11 +858,8 @@ class ASTParametersQualifiers(ASTBase):
_add_text(signode, '= ' + text_type(self.initializer))
class ASTDeclSpecs(ASTBase):
def __init__(self, outer, visibility, storage, inline, virtual, explicit,
constexpr, volatile, const, trailing):
self.outer = outer
self.visibility = visibility
class ASTDeclSpecsSimple(ASTBase):
def __init__(self, storage, inline, virtual, explicit, constexpr, volatile, const):
self.storage = storage
self.inline = inline
self.virtual = virtual
@ -870,40 +867,9 @@ class ASTDeclSpecs(ASTBase):
self.constexpr = constexpr
self.volatile = volatile
self.const = const
self.trailingTypeSpec = trailing
@property
def name(self):
return self.trailingTypeSpec.name
def get_id_v1(self):
res = []
res.append(self.trailingTypeSpec.get_id_v1())
if self.volatile:
res.append('V')
if self.const:
res.append('C')
return u''.join(res)
def get_id_v2(self):
res = []
if self.volatile:
res.append('V')
if self.const:
res.append('K')
res.append(self.trailingTypeSpec.get_id_v2())
return u''.join(res)
def _print_visibility(self):
return (self.visibility and
not (
self.outer in ('type', 'member', 'function') and
self.visibility == 'public'))
def __unicode__(self):
res = []
if self._print_visibility():
res.append(self.visibility)
if self.storage:
res.append(self.storage)
if self.inline:
@ -918,21 +884,13 @@ class ASTDeclSpecs(ASTBase):
res.append('volatile')
if self.const:
res.append('const')
if self.trailingTypeSpec:
res.append(text_type(self.trailingTypeSpec))
return u' '.join(res)
def describe_signature(self, signode, mode, env):
_verify_description_mode(mode)
modifiers = []
def describe_signature(self, modifiers):
def _add(modifiers, text):
if len(modifiers) > 0:
modifiers.append(nodes.Text(' '))
modifiers.append(addnodes.desc_annotation(text, text))
if self._print_visibility():
_add(modifiers, self.visibility)
if self.storage:
_add(modifiers, self.storage)
if self.inline:
@ -947,13 +905,87 @@ class ASTDeclSpecs(ASTBase):
_add(modifiers, 'volatile')
if self.const:
_add(modifiers, 'const')
class ASTDeclSpecs(ASTBase):
def __init__(self, outer, visibility, leftSpecs, rightSpecs, trailing):
self.outer = outer
self.visibility = visibility
self.leftSpecs = leftSpecs
self.rightSpecs = rightSpecs
self.trailingTypeSpec = trailing
@property
def name(self):
return self.trailingTypeSpec.name
def get_id_v1(self):
res = []
res.append(self.trailingTypeSpec.get_id_v1())
if self.leftSpecs.volatile or self.rightSpecs.volatile:
res.append('V')
if self.leftSpecs.const or self.rightSpecs.volatile:
res.append('C')
return u''.join(res)
def get_id_v2(self):
res = []
if self.leftSpecs.volatile or self.rightSpecs.volatile:
res.append('V')
if self.leftSpecs.const or self.rightSpecs.volatile:
res.append('K')
res.append(self.trailingTypeSpec.get_id_v2())
return u''.join(res)
def _print_visibility(self):
return (self.visibility and
not (self.outer in ('type', 'member', 'function') and
self.visibility == 'public'))
def __unicode__(self):
res = []
if self._print_visibility():
res.append(self.visibility)
l = text_type(self.leftSpecs)
if len(l) > 0:
if len(res) > 0:
res.append(" ")
res.append(l)
if self.trailingTypeSpec:
if len(res) > 0:
res.append(" ")
res.append(text_type(self.trailingTypeSpec))
r = text_type(self.rightSpecs)
if len(r) > 0:
if len(res) > 0:
res.append(" ")
res.append(r)
return "".join(res)
def describe_signature(self, signode, mode, env):
_verify_description_mode(mode)
modifiers = []
def _add(modifiers, text):
if len(modifiers) > 0:
modifiers.append(nodes.Text(' '))
modifiers.append(addnodes.desc_annotation(text, text))
if self._print_visibility():
_add(modifiers, self.visibility)
self.leftSpecs.describe_signature(modifiers)
for m in modifiers:
signode += m
if self.trailingTypeSpec:
if len(modifiers) > 0:
signode += nodes.Text(' ')
self.trailingTypeSpec.describe_signature(signode, mode, env)
modifiers = []
self.rightSpecs.describe_signature(modifiers)
if len(modifiers) > 0:
signode += nodes.Text(' ')
for m in modifiers:
signode += m
class ASTPtrOpPtr(ASTBase):
def __init__(self, volatile, const):
@ -1190,7 +1222,6 @@ class ASTType(ASTBase):
signode += nodes.Text(' ')
self.decl.describe_signature(signode, mode, env)
class ASTTypeWithInit(ASTBase):
def __init__(self, type, init):
self.objectType = None
@ -1588,20 +1619,8 @@ class DefinitionParser(object):
args, volatile, const, refQual, exceptionSpec, override, final,
initializer)
def _parse_decl_specs(self, outer, typed=True):
"""
visibility storage-class-specifier function-specifier "constexpr"
"volatile" "const" trailing-type-specifier
storage-class-specifier -> "static" (only for member_object and
function_object)
function-specifier -> "inline" | "virtual" | "explicit" (only for
function_object)
"constexpr" (only for member_object and function_object)
"""
visibility = None
def _parse_decl_specs_simple(self, outer, typed):
"""Just parse the simple ones."""
storage = None
inline = None
virtual = None
@ -1609,12 +1628,6 @@ class DefinitionParser(object):
constexpr = None
volatile = None
const = None
if outer:
self.skip_ws()
if self.match(_visibility_re):
visibility = self.matched_text
while 1: # accept any permutation of a subset of some decl-specs
self.skip_ws()
if not storage:
@ -1660,14 +1673,37 @@ class DefinitionParser(object):
if const:
continue
break
return ASTDeclSpecsSimple(storage, inline, virtual, explicit, constexpr,
volatile, const)
def _parse_decl_specs(self, outer, typed=True):
"""
visibility storage-class-specifier function-specifier "constexpr"
"volatile" "const" trailing-type-specifier
storage-class-specifier -> "static" (only for member_object and
function_object)
function-specifier -> "inline" | "virtual" | "explicit" (only for
function_object)
"constexpr" (only for member_object and function_object)
"""
visibility = None
leftSepcs = None
rightSpecs = None
if outer:
self.skip_ws()
if self.match(_visibility_re):
visibility = self.matched_text
leftSpecs = self._parse_decl_specs_simple(outer, typed)
if typed:
trailing = self._parse_trailing_type_spec()
rightSpecs = self._parse_decl_specs_simple(outer, typed)
else:
trailing = None
return ASTDeclSpecs(
outer, visibility, storage, inline, virtual, explicit, constexpr,
volatile, const, trailing)
return ASTDeclSpecs(outer, visibility, leftSpecs, rightSpecs, trailing)
def _parse_declerator(self, named, paramMode=None, typed=True):
if paramMode:

2
sphinx/domains/javascript.py
View File

@ -5,7 +5,7 @@
The JavaScript domain.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/domains/python.py
View File

@ -5,7 +5,7 @@
The Python domain.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/domains/rst.py
View File

@ -5,7 +5,7 @@
The reStructuredText domain.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/domains/std.py
View File

@ -5,7 +5,7 @@
The standard domain.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

23
sphinx/environment.py
View File

@ -5,7 +5,7 @@
Global creation environment.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -14,6 +14,7 @@ import os
import sys
import time
import types
import bisect
import codecs
import imghdr
import string
@ -589,8 +590,12 @@ class BuildEnvironment:
self.doc2path(config.master_doc))
self.app = None
app.emit('env-updated', self)
return docnames
for retval in app.emit('env-updated', self):
if retval is not None:
docnames.extend(retval)
return sorted(docnames)
def _read_serial(self, docnames, app):
for docname in app.status_iterator(docnames, 'reading sources... ',
@ -1521,7 +1526,8 @@ class BuildEnvironment:
if (dtype, target) in self._nitpick_ignore:
warn = False
# for "std" types also try without domain name
if domain.name == 'std' and (typ, target) in self._nitpick_ignore:
if (not domain or domain.name == 'std') and \
(typ, target) in self._nitpick_ignore:
warn = False
if not warn:
return
@ -1795,7 +1801,8 @@ class BuildEnvironment:
except NoUri:
pass
else:
entry[0].append((main, uri))
# maintain links in sorted/deterministic order
bisect.insort(entry[0], (main, uri))
for fn, entries in iteritems(self.indexentries):
# new entry types must be listed in directives/other.py!
@ -1833,8 +1840,10 @@ class BuildEnvironment:
def keyfunc(entry, lcletters=string.ascii_lowercase + '_'):
lckey = unicodedata.normalize('NFD', entry[0].lower())
if lckey[0:1] in lcletters:
return chr(127) + lckey
return lckey
lckey = chr(127) + lckey
# ensure a determinstic order *within* letters by also sorting on
# the entry itself
return (lckey, entry[0])
newlist = sorted(new.items(), key=keyfunc)
if group_entries:

2
sphinx/errors.py
View File

@ -6,7 +6,7 @@
Contains SphinxError and a few subclasses (in an extra module to avoid
circular import problems).
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/__init__.py
View File

@ -5,6 +5,6 @@
Contains Sphinx features not activated by default.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

78
sphinx/ext/autodoc.py
View File

@ -7,7 +7,7 @@
the doctree, thus avoiding duplication between docstrings and documentation
for those who like elaborate docstrings.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -30,7 +30,7 @@ from sphinx.application import ExtensionError
from sphinx.util.nodes import nested_parse_with_titles
from sphinx.util.compat import Directive
from sphinx.util.inspect import getargspec, isdescriptor, safe_getmembers, \
safe_getattr, safe_repr, is_builtin_class_method
safe_getattr, object_description, is_builtin_class_method
from sphinx.util.docstrings import prepare_docstring
@ -243,6 +243,11 @@ def between(marker, what=None, keepempty=False, exclude=False):
return process
def formatargspec(*argspec):
return inspect.formatargspec(*argspec,
formatvalue=lambda x: '=' + object_description(x))
class Documenter(object):
"""
A Documenter knows how to autodocument a single object type. When
@ -481,14 +486,15 @@ class Documenter(object):
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."""
@ -514,9 +520,7 @@ class Documenter(object):
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):
@ -524,8 +528,14 @@ class Documenter(object):
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])
@ -534,8 +544,6 @@ class Documenter(object):
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:
@ -794,17 +802,19 @@ class Documenter(object):
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
@ -854,15 +864,17 @@ class ModuleDocumenter(Documenter):
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:
@ -872,6 +884,15 @@ class ModuleDocumenter(Documenter):
return True, safe_getmembers(self.object)
else:
memberlist = self.object.__all__
# Sometimes __all__ is broken...
if not isinstance(memberlist, (list, tuple)) or not \
all(isinstance(entry, str) for entry in memberlist):
self.directive.warn(
'__all__ should be a list of strings, not %r '
'(in module %s) -- ignoring __all__' %
(memberlist, self.fullname))
# fall back to all members
return True, safe_getmembers(self.object)
else:
memberlist = self.options.members or []
ret = []
@ -1038,7 +1059,7 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):
argspec = getargspec(self.object.__init__)
if argspec[0]:
del argspec[0][0]
args = inspect.formatargspec(*argspec)
args = formatargspec(*argspec)
# escape backslashes for reST
args = args.replace('\\', '\\\\')
return args
@ -1093,7 +1114,7 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):
return None
if argspec[0] and argspec[0][0] in ('cls', 'self'):
del argspec[0][0]
return inspect.formatargspec(*argspec)
return formatargspec(*argspec)
def format_signature(self):
if self.doc_as_attr:
@ -1108,14 +1129,15 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):
# 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)
@ -1200,18 +1222,19 @@ class DataDocumenter(ModuleLevelDocumenter):
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)
objrepr = object_description(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
@ -1258,7 +1281,7 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):
argspec = getargspec(self.object)
if argspec[0] and argspec[0][0] in ('cls', 'self'):
del argspec[0][0]
args = inspect.formatargspec(*argspec)
args = formatargspec(*argspec)
# escape backslashes for reST
args = args.replace('\\', '\\\\')
return args
@ -1311,19 +1334,20 @@ class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):
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)
objrepr = object_description(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:

9
sphinx/ext/autosummary/__init__.py
View File

@ -49,7 +49,7 @@
resolved to a Python object, and otherwise it becomes simple emphasis.
This can be used as the default role to make links 'smart'.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -69,6 +69,7 @@ import sphinx
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 ------------------------------------------------------
@ -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
@ -194,7 +195,7 @@ class Autosummary(Directive):
def run(self):
self.env = env = self.state.document.settings.env
self.genopt = {}
self.genopt = Options()
self.warnings = []
self.result = ViewList()
@ -269,6 +270,8 @@ class Autosummary(Directive):
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:

2
sphinx/ext/autosummary/generate.py
View File

@ -14,7 +14,7 @@
generate:
sphinx-autogen -o source/generated source/*.rst
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function

2
sphinx/ext/coverage.py
View File

@ -6,7 +6,7 @@
Check Python modules and C API for coverage. Mostly written by Josip
Dzolonga for the Google Highly Open Participation contest.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/doctest.py
View File

@ -6,7 +6,7 @@
Mimic doctest by automatically executing code snippets and checking
their results.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/extlinks.py
View File

@ -20,7 +20,7 @@
You can also give an explicit caption, e.g. :exmpl:`Foo <foo>`.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/graphviz.py
View File

@ -6,7 +6,7 @@
Allow graphviz-formatted graphs to be included in Sphinx-generated
documents inline.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

5
sphinx/ext/ifconfig.py
View File

@ -16,7 +16,7 @@
namespace of the project configuration (that is, all variables from
``conf.py`` are available.)
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -49,7 +49,8 @@ class IfConfig(Directive):
def process_ifconfig_nodes(app, doctree, docname):
ns = app.config.__dict__.copy()
ns = {k: app.config[k] for k in app.config.values}
ns.update(app.config.__dict__.copy())
ns['builder'] = app.builder.name
for node in doctree.traverse(ifconfig):
try:

4
sphinx/ext/inheritance_diagram.py
View File

@ -32,7 +32,7 @@ r"""
The graph is inserted as a PNG+image map into HTML and a PDF in
LaTeX.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -186,7 +186,7 @@ class InheritanceGraph(object):
for cls in classes:
recurse(cls)
return all_classes.values()
return list(all_classes.values())
def class_name(self, cls, parts=0):
"""Given a class object, return a fully-qualified name.

2
sphinx/ext/intersphinx.py
View File

@ -20,7 +20,7 @@
also be specified individually, e.g. if the docs should be buildable
without Internet access.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/jsmath.py
View File

@ -6,7 +6,7 @@
Set up everything for use of JSMath to display math in HTML
via JavaScript.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/linkcode.py
View File

@ -5,7 +5,7 @@
Add external links to module code in Python object descriptions.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/mathbase.py
View File

@ -5,7 +5,7 @@
Set up math support in source files and LaTeX/text output.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

4
sphinx/ext/mathjax.py
View File

@ -7,7 +7,7 @@
Sphinx's HTML writer -- requires the MathJax JavaScript library on your
webserver/computer.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -64,7 +64,7 @@ def setup(app):
# more information for mathjax secure url is here:
# http://docs.mathjax.org/en/latest/start.html#secure-access-to-the-cdn
app.add_config_value('mathjax_path',
'https://c328740.ssl.cf1.rackcdn.com/mathjax/latest/MathJax.js?'
'https://cdn.mathjax.org/mathjax/latest/MathJax.js?'
'config=TeX-AMS-MML_HTMLorMML', False)
app.add_config_value('mathjax_inline', [r'\(', r'\)'], 'html')
app.add_config_value('mathjax_display', [r'\[', r'\]'], 'html')

2
sphinx/ext/napoleon/__init__.py
View File

@ -5,7 +5,7 @@
Support for NumPy and Google style docstrings.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

34
sphinx/ext/napoleon/docstring.py
View File

@ -7,7 +7,7 @@
Classes for docstring parsing and formatting.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -23,8 +23,9 @@ from sphinx.util.pycompat import UnicodeMixin
_directive_regex = re.compile(r'\.\. \S+::')
_google_untyped_arg_regex = re.compile(r'\s*(\w+)\s*:\s*(.*)')
_google_typed_arg_regex = re.compile(r'\s*(\w+)\s*\(\s*(.+?)\s*\)\s*:\s*(.*)')
_google_untyped_arg_regex = re.compile(r'\s*(\*?\*?\w+)\s*:\s*(.*)')
_google_typed_arg_regex = re.compile(r'\s*(\*?\*?\w+)\s*\(\s*(.+?)\s*\)\s*:'
r'\s*(.*)')
class GoogleDocstring(UnicodeMixin):
@ -90,6 +91,7 @@ class GoogleDocstring(UnicodeMixin):
<BLANKLINE>
:returns: Description of return value.
:rtype: str
<BLANKLINE>
"""
def __init__(self, docstring, config=None, app=None, what='', name='',
@ -215,6 +217,11 @@ class GoogleDocstring(UnicodeMixin):
_name = match.group(1)
_desc = match.group(2)
if _name[:2] == '**':
_name = r'\*\*'+_name[2:]
elif _name[:1] == '*':
_name = r'\*'+_name[1:]
if prefer_type and not _type:
_type, _name = _name, _type
indent = self._get_indent(line) + 1
@ -254,6 +261,10 @@ class GoogleDocstring(UnicodeMixin):
else:
return []
def _consume_usage_section(self):
lines = self._dedent(self._consume_to_next_section())
return lines
def _consume_section_header(self):
section = next(self._line_iter)
stripped_section = section.strip(':')
@ -291,11 +302,10 @@ class GoogleDocstring(UnicodeMixin):
padding = ' ' * len(prefix)
result_lines = []
for i, line in enumerate(lines):
if line:
if i == 0:
result_lines.append(prefix + line)
else:
result_lines.append(padding + line)
if i == 0:
result_lines.append((prefix + line).rstrip())
elif line:
result_lines.append(padding + line)
else:
result_lines.append('')
return result_lines
@ -444,6 +454,13 @@ class GoogleDocstring(UnicodeMixin):
use_admonition = self._config.napoleon_use_admonition_for_examples
return self._parse_generic_section(section, use_admonition)
def _parse_usage_section(self, section):
header = ['.. rubric:: Usage:', '']
block = ['.. code-block:: python', '']
lines = self._consume_usage_section()
lines = self._indent(lines, 3)
return header + block + lines + ['']
def _parse_generic_section(self, section, use_admonition):
lines = self._strip_empty(self._consume_to_next_section())
lines = self._dedent(lines)
@ -664,6 +681,7 @@ class NumpyDocstring(GoogleDocstring):
<BLANKLINE>
:returns: Description of return value.
:rtype: str
<BLANKLINE>
Methods
-------

2
sphinx/ext/napoleon/iterators.py
View File

@ -7,7 +7,7 @@
A collection of helpful iterators.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/pngmath.py
View File

@ -5,7 +5,7 @@
Render math in HTML via dvipng.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/todo.py
View File

@ -8,7 +8,7 @@
all todos of your project and lists them along with a backlink to the
original location.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/viewcode.py
View File

@ -5,7 +5,7 @@
Add links to module code in Python object descriptions.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

10
sphinx/highlighting.py
View File

@ -5,7 +5,7 @@
Highlight code blocks using Pygments.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@ -96,7 +96,7 @@ class PygmentsBridge(object):
source = source.translate(escape_hl_chars)
# then, escape all characters nonrepresentable in LaTeX
source = source.translate(tex_hl_escape_map_new)
return '\\begin{Verbatim}[frame=single,commandchars=\\\\\\{\\}]\n' + \
return '\\begin{Verbatim}[commandchars=\\\\\\{\\}]\n' + \
source + '\\end{Verbatim}\n'
def try_parse(self, src):
@ -134,7 +134,7 @@ class PygmentsBridge(object):
else:
return True
def highlight_block(self, source, lang, warn=None, force=False, **kwargs):
def highlight_block(self, source, lang, opts=None, warn=None, force=False, **kwargs):
if not isinstance(source, text_type):
source = source.decode()
@ -164,7 +164,7 @@ class PygmentsBridge(object):
lexer = lexers[lang]
else:
try:
lexer = lexers[lang] = get_lexer_by_name(lang)
lexer = lexers[lang] = get_lexer_by_name(lang, **opts or {})
except ClassNotFound:
if warn:
warn('Pygments lexer name %r is not known' % lang)
@ -190,8 +190,6 @@ class PygmentsBridge(object):
if self.dest == 'html':
return hlsource
else:
hlsource = re.sub(r'(?<=\\begin{Verbatim}\[)(?=commandchars)',
r'frame=single,', hlsource)
if not isinstance(hlsource, text_type): # Py2 / Pygments < 1.6
hlsource = hlsource.decode()
return hlsource.translate(tex_hl_escape_map_new)

2
sphinx/jinja2glue.py
View File

@ -5,7 +5,7 @@
Glue code for the jinja2 templating engine.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/locale/__init__.py
View File

@ -5,7 +5,7 @@
Locale utilities.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

12
sphinx/make_mode.py
View File

@ -11,7 +11,7 @@
This is in its own module so that importing it is fast. It should not
import the main Sphinx modules (like sphinx.applications, sphinx.builders).
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function
@ -251,11 +251,15 @@ class Make(object):
doctreedir = self.builddir_join('doctrees')
orig_cmd = sys.argv[0]
if orig_cmd.endswith('.exe'):
if sys.platform == 'win32' and orig_cmd.endswith('.exe'):
# win32: 'sphinx-build.exe'
cmd = [orig_cmd]
elif sys.platform == 'win32':
elif sys.platform == 'win32' and os.path.splitext(orig_cmd)[1] == '':
# win32: 'sphinx-build' without extension
cmd = [orig_cmd + '.exe']
else: # ex. 'sphinx-build' or 'sphinx-build.py'
else:
# win32: 'sphinx-build.py'
# linux, mac: 'sphinx-build' or 'sphinx-build.py'
cmd = [sys.executable, orig_cmd]
return call(cmd + ['-b', builder] + opts +

2
sphinx/pycode/__init__.py
View File

@ -5,7 +5,7 @@
Utilities parsing and analyzing Python code.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function

2
sphinx/pycode/nodes.py
View File

@ -5,7 +5,7 @@
Parse tree node implementations.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/pygments_styles.py
View File

@ -5,7 +5,7 @@
Sphinx theme specific highlighting styles.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/quickstart.py
View File

@ -5,7 +5,7 @@
Quickly setup documentation source to work with Sphinx.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function

2
sphinx/roles.py
View File

@ -5,7 +5,7 @@
Handlers for additional ReST roles.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

8
sphinx/search/__init__.py
View File

@ -5,7 +5,7 @@
Create a full-text search index for offline search.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import re
@ -313,13 +313,13 @@ class IndexBuilder(object):
if fn in fn2index:
rv[k] = fn2index[fn]
else:
rv[k] = [fn2index[fn] for fn in v if fn in fn2index]
rv[k] = sorted([fn2index[fn] for fn in v if fn in fn2index])
return rvs
def freeze(self):
"""Create a usable data structure for serializing."""
filenames = list(self._titles.keys())
titles = list(self._titles.values())
filenames = sorted(self._titles.keys())
titles = sorted(self._titles.values())
fn2index = dict((f, i) for (i, f) in enumerate(filenames))
terms, title_terms = self.get_terms(fn2index)

2
sphinx/search/en.py
View File

@ -5,7 +5,7 @@
English search language: includes the JS porter stemmer.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/search/ja.py
View File

@ -5,7 +5,7 @@
Japanese search language: includes routine to split words.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

6
sphinx/setup_command.py
View File

@ -8,7 +8,7 @@
:author: Sebastian Wiesner
:contact: basti.wiesner@gmx.net
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function
@ -77,6 +77,7 @@ class BuildDoc(Command):
('today=', None, 'How to format the current date, used as the '
'replacement for |today|'),
('link-index', 'i', 'Link index.html to the master doc'),
('copyright', None, 'The copyright string'),
]
boolean_options = ['fresh-env', 'all-files', 'link-index']
@ -91,6 +92,7 @@ class BuildDoc(Command):
self.today = ''
self.config_dir = None
self.link_index = False
self.copyright = ''
def _guess_source_dir(self):
for guess in ('doc', 'docs'):
@ -152,6 +154,8 @@ class BuildDoc(Command):
confoverrides['release'] = self.release
if self.today:
confoverrides['today'] = self.today
if self.copyright:
confoverrides['copyright'] = self.copyright
app = Sphinx(self.source_dir, self.config_dir,
self.builder_target_dir, self.doctree_dir,
self.builder, confoverrides, status_stream,

4
sphinx/texinputs/sphinx.sty
View File

@ -39,10 +39,10 @@
\definecolor{TitleColor}{rgb}{0.126,0.263,0.361}
\definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486}
\definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388}
% Redefine these colors to something not white if you want to have colored
% Redefine these colors to something if you want to have colored
% background and border for code examples.
\definecolor{VerbatimColor}{rgb}{1,1,1}
\definecolor{VerbatimBorderColor}{rgb}{1,1,1}
\definecolor{VerbatimBorderColor}{rgb}{0,0,0}
% Uncomment these two lines to ignore the paper size and make the page
% size more like a typical published manual.

2
sphinx/themes/agogo/layout.html
View File

@ -5,7 +5,7 @@
Sphinx layout template for the agogo theme, originally written
by Andi Albrecht.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- extends "basic/layout.html" %}

2
sphinx/themes/agogo/static/agogo.css_t
View File

@ -4,7 +4,7 @@
*
* Sphinx stylesheet -- agogo theme.
*
* :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/

2
sphinx/themes/basic/defindex.html
View File

@ -4,7 +4,7 @@
Default template for the "index" page.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- extends "layout.html" %}

2
sphinx/themes/basic/domainindex.html
View File

@ -4,7 +4,7 @@
Template for domain indices (module index, ...).
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- extends "layout.html" %}

2
sphinx/themes/basic/genindex-single.html
View File

@ -4,7 +4,7 @@
Template for a "single" page of a split index.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{% macro indexentries(firstname, links) %}

2
sphinx/themes/basic/genindex-split.html
View File

@ -4,7 +4,7 @@
Template for a "split" index overview page.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- extends "layout.html" %}

2
sphinx/themes/basic/genindex.html
View File

@ -4,7 +4,7 @@
Template for an "all-in-one" index.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{% macro indexentries(firstname, links) %}

2
sphinx/themes/basic/globaltoc.html
View File

@ -4,7 +4,7 @@
Sphinx sidebar template: global table of contents.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>

2
sphinx/themes/basic/layout.html
View File

@ -4,7 +4,7 @@
Master layout template for Sphinx themes.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- block doctype -%}

2
sphinx/themes/basic/localtoc.html
View File

@ -4,7 +4,7 @@
Sphinx sidebar template: local table of contents.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- if display_toc %}

2
sphinx/themes/basic/page.html
View File

@ -4,7 +4,7 @@
Master template for simple pages.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- extends "layout.html" %}

2
sphinx/themes/basic/relations.html
View File

@ -4,7 +4,7 @@
Sphinx sidebar template: relation links.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- if prev %}

2
sphinx/themes/basic/search.html
View File

@ -4,7 +4,7 @@
Template for the search page.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- extends "layout.html" %}

2
sphinx/themes/basic/searchbox.html
View File

@ -4,7 +4,7 @@
Sphinx sidebar template: quick search box.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- if pagename != "search" and builder != "singlehtml" %}

2
sphinx/themes/basic/searchresults.html
View File

@ -4,7 +4,7 @@
Template for the body of the search results page.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
<h1 id="search-documentation">{{ _('Search') }}</h1>

2
sphinx/themes/basic/sourcelink.html
View File

@ -4,7 +4,7 @@
Sphinx sidebar template: "show source" link.
:copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- if show_source and has_source and sourcename %}

2
sphinx/themes/basic/static/basic.css_t
View File

@ -4,7 +4,7 @@
*
* Sphinx stylesheet -- basic theme.
*
* :copyright: Copyright 2007-2014 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/

Some files were not shown because too many files have changed in this diff Show More