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 branch 'master' into fixpdfinfo

Browse Source
This commit is contained in:
Jean-François B
2017-04-15 10:15:14 +02:00
committed by GitHub
parent a8627ac01c 6e7c75e642
commit 9a68db9513
297 changed files with 1213 additions and 517 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
CHANGES
View File

@@ -41,6 +41,7 @@ Incompatible changes
``xcolor`` packages should be used by extensions of Sphinx latex writer.
(refs #3550)
* ``Builder.env`` is not filled at instantiation
* #3594: LaTeX: single raw directive has been considered as block level element
Features removed
----------------
@@ -97,6 +98,11 @@ Features added
and docutils 0.13 and newer is installed.
* LaTeX macros to customize space before and after tables in PDF output (refs #3504)
* #3348: Show decorators in literalinclude and viewcode directives
* #3108: Show warning if :start-at: and other literalinclude options does not
match to the text
* #3609: Allow to suppress "duplicate citation" warnings using
``suppress_warnings``
* #2803: Discovery of builders by entry point
Bugs fixed
----------
@@ -109,6 +115,7 @@ Bugs fixed
* #2693: Sphinx latex style file wrongly inhibits colours for section headings
for latex+dvi(ps,pdf,pdfmx)
* C++, properly look up ``any`` references.
* #3624: sphinx.ext.intersphinx couldn't load inventories compressed with gzip
* #3551: PDF information dictionary is lacking author and title data
Deprecated
@@ -139,8 +146,9 @@ Deprecated
* #3429: deprecate config setting ``latex_keep_old_macro_names``. It will be
removed at 1.7, and already its default value has changed from ``True`` to
``False``.
* #3221: epub2 builder is deprecated
Release 1.5.4 (in development)
Release 1.5.6 (in development)
==============================
Incompatible changes
@@ -152,8 +160,28 @@ Deprecated
Features added
--------------
Bugs fixed
----------
Testing
--------
Release 1.5.5 (released Apr 03, 2017)
=====================================
Bugs fixed
----------
* #3597: python domain raises UnboundLocalError if invalid name given
* #3599: Move to new Mathjax CDN
Release 1.5.4 (released Apr 02, 2017)
=====================================
Features added
--------------
* #3470: Make genindex support all kinds of letters, not only Latin ones
* latex macros for directional double quotes (refs #3527)
Bugs fixed
----------
@@ -180,9 +208,6 @@ Bugs fixed
* A LaTeX command such as ``\\large`` inserted in the title items of
:confval:`latex_documents` causes failed PDF build (refs #3551, #3567)
Testing
--------
Release 1.5.3 (released Feb 26, 2017)
=====================================

2
LICENSE
View File

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

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

@@ -4,7 +4,7 @@
Sphinx layout template for the sphinxdoc theme.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2017 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-2016, Georg Brandl and the Sphinx team'
copyright = '2007-2017, Georg Brandl and the Sphinx team'
version = sphinx.__released__
release = version
show_authors = True

27
doc/domains.rst
View File

@@ -1104,6 +1104,22 @@ The JavaScript Domain
The JavaScript domain (name **js**) provides the following directives:
.. rst:directive:: .. js:module:: name
This directive sets the module name for object declarations that follow
after. The module name is used in the global module index and in cross
references. This directive does not create an object heading like
:rst:dir:`py:class` would, for example.
By default, this directive will create a linkable entity and will cause an
entry in the global module index, unless the ``noindex`` option is specified.
If this option is specified, the directive will only update the current
module name.
To clear the current module, set the module name to ``null`` or ``None``
.. versionadded:: 1.6
.. rst:directive:: .. js:function:: name(signature)
Describes a JavaScript function or method. If you want to describe
@@ -1136,6 +1152,13 @@ The JavaScript domain (name **js**) provides the following directives:
:throws SomeError: For whatever reason in that case.
:returns: Something.
.. rst:directive:: .. js:method:: name(signature)
This directive is an alias for :rst:dir:`js:function`, however it describes a
function that is implemented as a method on a class object.
.. versionadded:: 1.6
.. rst:directive:: .. js:class:: name
Describes a constructor that creates an object. This is basically like
@@ -1165,7 +1188,9 @@ The JavaScript domain (name **js**) provides the following directives:
These roles are provided to refer to the described objects:
.. rst:role:: js:func
.. rst:role:: js:mod
js:func
js:meth
js:class
js:data
js:attr

23
doc/ext/autosummary.rst
View File

@@ -158,7 +158,7 @@ is not supported.)
may indicate that it's a better idea to write custom narrative documentation
instead.
Autosummary uses the following template files:
Autosummary uses the following Jinja template files:
- :file:`autosummary/base.rst` -- fallback template
- :file:`autosummary/module.rst` -- template for modules
@@ -194,7 +194,8 @@ The following variables available in the templates:
.. data:: underline
A string containing ``len(full_name) * '='``.
A string containing ``len(full_name) * '='``. Use the ``underline`` filter
instead.
.. data:: members
@@ -227,7 +228,25 @@ The following variables available in the templates:
List containing names of "public" attributes in the class. Only available
for classes.
Additionally, the following filters are available
.. function:: escape(s)
Escape any special characters in the text to be used in formatting RST
contexts. For instance, this prevents asterisks making things bolt. This
replaces the builtin Jinja `escape filter`_ that does html-escaping.
.. function:: underline(s, line='=')
Add a title underline to a piece of text.
For instance, ``{{ fullname | escape | underline }}`` should be used to produce
the title of a page.
.. note::
You can use the :rst:dir:`autosummary` directive in the stub pages.
Stub pages are generated also based on these directives.
.. _`escape filter`: http://jinja.pocoo.org/docs/2.9/templates/#escape

6
doc/extdev/builderapi.rst
View File

@@ -11,6 +11,12 @@ Builder API
This is the base class for all builders.
These attributes should be set on builder classes:
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
These methods are predefined and will be called from the application:
.. automethod:: get_relative_uri

30
doc/extdev/index.rst
View File

@@ -22,6 +22,36 @@ The configuration file itself can be treated as an extension if it contains a
``setup()`` function. All other extensions to load must be listed in the
:confval:`extensions` configuration value.
Discovery of builders by entry point
------------------------------------
.. versionadded:: 1.6
:term:`Builder` extensions can be discovered by means of `entry points`_ so
that they do not have to be listed in the :confval:`extensions` configuration
value.
Builder extensions should define an entry point in the ``sphinx.builders``
group. The name of the entry point needs to match your builder's
:attr:`~.Builder.name` attribute, which is the name passed to the
:option:`sphinx-build -b` option. The entry point value should equal the
dotted name of the extension module. Here is an example of how an entry point
for 'mybuilder' can be defined in the extension's ``setup.py``::
setup(
# ...
entry_points={
'sphinx.builders': [
'mybuilder = my.extension.module',
],
}
)
Note that it is still necessary to register the builder using
:meth:`~.Sphinx.add_builder` in the extension's :func:`setup` function.
.. _entry points: https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins
Extension metadata
------------------

2
setup.cfg
View File

@@ -3,7 +3,7 @@ tag_build = .dev
tag_date = true
[aliases]
release = egg_info -RDb ''
release = egg_info -Db ''
upload = upload --sign --identity=36580288
[extract_messages]

1
setup.py
View File

@@ -52,6 +52,7 @@ requires = [
'imagesize',
'requests>=2.0.0',
'typing',
'setuptools',
]
extras_require = {
# Environment Marker works for wheel 0.24 or later

2
sphinx-apidoc.py
View File

@@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

13
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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function
@@ -23,9 +23,10 @@ from os import path
from six import binary_type
from fnmatch import fnmatch
from sphinx.util.osutil import FileAvoidWrite, walk
from sphinx import __display_version__
from sphinx.quickstart import EXTENSIONS
from sphinx.util import rst
from sphinx.util.osutil import FileAvoidWrite, walk
if False:
# For type annotation
@@ -74,9 +75,11 @@ def write_file(name, text, opts):
f.write(text)
def format_heading(level, text):
# type: (int, unicode) -> unicode
def format_heading(level, text, escape=True):
# type: (int, unicode, bool) -> unicode
"""Create a heading of <level> [1, 2 or 3 supported]."""
if escape:
text = rst.escape(text)
underlining = ['=', '-', '~', ][level - 1] * len(text)
return '%s\n%s\n\n' % (text, underlining)
@@ -161,7 +164,7 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs, is_
def create_modules_toc_file(modules, opts, name='modules'):
# type: (List[unicode], Any, unicode) -> None
"""Create the module's index."""
text = format_heading(1, '%s' % opts.header)
text = format_heading(1, '%s' % opts.header, escape=False)
text += '.. toctree::\n'
text += ' :maxdepth: %s\n\n' % opts.maxdepth

94
sphinx/application.py
View File

@@ -7,7 +7,7 @@
Gracefully adapted from the TextPress system by Armin.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function
@@ -17,7 +17,6 @@ import sys
import types
import warnings
import posixpath
import traceback
from os import path
from collections import deque
@@ -27,6 +26,7 @@ from six.moves import cStringIO
from docutils import nodes
from docutils.parsers.rst import convert_directive_function, \
directives, roles
from pkg_resources import iter_entry_points
import sphinx
from sphinx import package_dir, locale
@@ -38,6 +38,7 @@ from sphinx.domains.std import GenericObject, Target, StandardDomain
from sphinx.deprecation import RemovedInSphinx17Warning, RemovedInSphinx20Warning
from sphinx.environment import BuildEnvironment
from sphinx.events import EventManager
from sphinx.extension import load_extension, verify_required_extensions
from sphinx.io import SphinxStandaloneReader
from sphinx.locale import _
from sphinx.roles import XRefRole
@@ -59,6 +60,7 @@ if False:
from sphinx.builders import Builder # NOQA
from sphinx.domains import Domain, Index # NOQA
from sphinx.environment.collectors import EnvironmentCollector # NOQA
from sphinx.extension import Extension # NOQA
builtin_extensions = (
'sphinx.builders.applehelp',
@@ -97,15 +99,14 @@ builtin_extensions = (
'sphinx.environment.collectors.title',
'sphinx.environment.collectors.toctree',
'sphinx.environment.collectors.indexentries',
# Strictly, alabaster theme is not a builtin extension,
# but it is loaded automatically to use it as default theme.
'alabaster',
) # type: Tuple[unicode, ...]
CONFIG_FILENAME = 'conf.py'
ENV_PICKLE_FILENAME = 'environment.pickle'
# list of deprecated extensions. Keys are extension name.
# Values are Sphinx version that merge the extension.
EXTENSION_BLACKLIST = {"sphinxjp.themecore": "1.2"} # type: Dict[unicode, unicode]
logger = logging.getLogger(__name__)
@@ -117,8 +118,7 @@ class Sphinx(object):
parallel=0):
# type: (unicode, unicode, unicode, unicode, unicode, Dict, IO, IO, bool, bool, List[unicode], int, int) -> None # NOQA
self.verbosity = verbosity
self._extensions = {} # type: Dict[unicode, Any]
self._extension_metadata = {} # type: Dict[unicode, Dict[unicode, Any]]
self.extensions = {} # type: Dict[unicode, Extension]
self._additional_source_parsers = {} # type: Dict[unicode, Parser]
self._setting_up_extension = ['?'] # type: List[unicode]
self.domains = {} # type: Dict[unicode, Type[Domain]]
@@ -154,6 +154,7 @@ class Sphinx(object):
self._translators = {} # type: Dict[unicode, nodes.GenericNodeVisitor]
# keep last few messages for traceback
# This will be filled by sphinx.util.logging.LastMessagesWriter
self.messagelog = deque(maxlen=10) # type: deque
# say hello to the world
@@ -195,12 +196,6 @@ class Sphinx(object):
for extension in builtin_extensions:
self.setup_extension(extension)
# extension loading support for alabaster theme
# self.config.html_theme is not set from conf.py at here
# for now, sphinx always load a 'alabaster' extension.
if 'alabaster' not in self.config.extensions:
self.config.extensions.append('alabaster')
# load all user-given extension modules
for extension in self.config.extensions:
self.setup_extension(extension)
@@ -221,19 +216,7 @@ class Sphinx(object):
self.config.init_values()
# check extension versions if requested
if self.config.needs_extensions:
for extname, needs_ver in self.config.needs_extensions.items():
if extname not in self._extensions:
logger.warning(_('needs_extensions config value specifies a '
'version requirement for extension %s, but it is '
'not loaded'), extname)
continue
has_ver = self._extension_metadata[extname]['version']
if has_ver == 'unknown version' or needs_ver > has_ver:
raise VersionRequirementError(
_('This project needs the extension %s at least in '
'version %s and therefore cannot be built with the '
'loaded version (%s).') % (extname, needs_ver, has_ver))
verify_required_extensions(self, self.config.needs_extensions)
# check primary_domain if requested
if self.config.primary_domain and self.config.primary_domain not in self.domains:
@@ -317,8 +300,13 @@ class Sphinx(object):
logger.info(_('No builder selected, using default: html'))
buildername = 'html'
if buildername not in self.builderclasses:
raise SphinxError(_('Builder name %s not registered') % buildername)
entry_points = iter_entry_points('sphinx.builders', buildername)
try:
entry_point = next(entry_points)
except StopIteration:
raise SphinxError('Builder name %s not registered or available'
' through entry point' % buildername)
load_extension(self, entry_point.module_name)
builderclass = self.builderclasses[buildername]
return builderclass(self)
@@ -466,53 +454,11 @@ class Sphinx(object):
# ---- general extensibility interface -------------------------------------
def setup_extension(self, extension):
def setup_extension(self, extname):
# type: (unicode) -> None
"""Import and setup a Sphinx extension module. No-op if called twice."""
logger.debug('[app] setting up extension: %r', extension)
if extension in self._extensions:
return
if extension in EXTENSION_BLACKLIST:
logger.warning(_('the extension %r was already merged with Sphinx since '
'version %s; this extension is ignored.'),
extension, EXTENSION_BLACKLIST[extension])
return
self._setting_up_extension.append(extension)
try:
mod = __import__(extension, None, None, ['setup'])
except ImportError as err:
logger.verbose(_('Original exception:\n') + traceback.format_exc())
raise ExtensionError(_('Could not import extension %s') % extension,
err)
if not hasattr(mod, 'setup'):
logger.warning(_('extension %r has no setup() function; is it really '
'a Sphinx extension module?'), extension)
ext_meta = None
else:
try:
ext_meta = mod.setup(self)
except VersionRequirementError as err:
# add the extension name to the version required
raise VersionRequirementError(
_('The %s extension used by this project needs at least '
'Sphinx v%s; it therefore cannot be built with this '
'version.') % (extension, err))
if ext_meta is None:
ext_meta = {}
# special-case for compatibility
if extension == 'rst2pdf.pdfbuilder':
ext_meta = {'parallel_read_safe': True}
try:
if not ext_meta.get('version'):
ext_meta['version'] = 'unknown version'
except Exception:
logger.warning(_('extension %r returned an unsupported object from '
'its setup() function; it should return None or a '
'metadata dictionary'), extension)
ext_meta = {'version': 'unknown version'}
self._extensions[extension] = mod
self._extension_metadata[extension] = ext_meta
self._setting_up_extension.pop()
logger.debug('[app] setting up extension: %r', extname)
load_extension(self, extname)
def require_sphinx(self, version):
# type: (unicode) -> None

16
sphinx/builders/__init__.py
View File

@@ -5,7 +5,7 @@
Builder superclass for all builders.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -17,6 +17,7 @@ try:
except ImportError:
multiprocessing = None
from six import itervalues
from docutils import nodes
from sphinx.util import i18n, path_stabilize, logging, status_iterator
@@ -48,9 +49,9 @@ class Builder(object):
Builds target formats from the reST sources.
"""
# builder's name, for the -b command line options
#: The builder's name, for the -b command line option.
name = '' # type: unicode
# builder's output format, or '' if no document output is produced
#: The builder's output format, or '' if no document output is produced.
format = '' # type: unicode
# doctree versioning method
versioning_method = 'none' # type: unicode
@@ -156,6 +157,8 @@ class Builder(object):
"""Return list of paths for assets (ex. templates, CSS, etc.)."""
return []
#: The list of MIME types of image formats supported by the builder.
#: Image files are searched in the order in which they appear here.
supported_image_types = [] # type: List[unicode]
def post_process_images(self, doctree):
@@ -337,11 +340,10 @@ class Builder(object):
self.parallel_ok = False
if parallel_available and self.app.parallel > 1 and self.allow_parallel:
self.parallel_ok = True
for extname, md in self.app._extension_metadata.items():
par_ok = md.get('parallel_write_safe', True)
if not par_ok:
for extension in itervalues(self.app.extensions):
if not extension.parallel_write_safe:
logger.warning('the %s extension is not safe for parallel '
'writing, doing serial write', extname)
'writing, doing serial write', extension.name)
self.parallel_ok = False
break

2
sphinx/builders/applehelp.py
View File

@@ -5,7 +5,7 @@
Build Apple help books.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function

2
sphinx/builders/changes.py
View File

@@ -5,7 +5,7 @@
Changelog builder.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import absolute_import

12
sphinx/builders/epub.py
View File

@@ -6,12 +6,13 @@
Build epub files.
Originally derived from qthelp.py.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import os
import re
import warnings
from os import path
from zipfile import ZIP_DEFLATED, ZIP_STORED, ZipFile
from datetime import datetime
@@ -30,6 +31,7 @@ from docutils import nodes
from sphinx import addnodes
from sphinx import package_dir
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.deprecation import RemovedInSphinx17Warning
from sphinx.util import logging
from sphinx.util import status_iterator
from sphinx.util.osutil import ensuredir, copyfile, make_filename
@@ -713,10 +715,18 @@ class EpubBuilder(StandaloneHTMLBuilder):
epub.write(path.join(outdir, filename), filename, ZIP_DEFLATED) # type: ignore
def emit_deprecation_warning(app):
# type: (Sphinx) -> None
if app.builder.__class__ is EpubBuilder:
warnings.warn('epub2 builder is deprecated. Please use epub3 builder instead.',
RemovedInSphinx17Warning)
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.setup_extension('sphinx.builders.html')
app.add_builder(EpubBuilder)
app.connect('builder-inited', emit_deprecation_warning)
# config values
app.add_config_value('epub_basename', lambda self: make_filename(self.project), None)

2
sphinx/builders/gettext.py
View File

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

8
sphinx/builders/html.py
View File

@@ -5,7 +5,7 @@
Several HTML builders.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -119,9 +119,6 @@ class StandaloneHTMLBuilder(Builder):
imgpath = None # type: unicode
domain_indices = [] # type: List[Tuple[unicode, Type[Index], List[Tuple[unicode, List[List[Union[unicode, int]]]]], bool]] # NOQA
default_sidebars = ['localtoc.html', 'relations.html',
'sourcelink.html', 'searchbox.html']
# cached publisher object for snippets
_publisher = None
@@ -1024,7 +1021,8 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder):
if 'includehidden' not in kwds:
kwds['includehidden'] = False
toctree = TocTree(self.env).get_toctree_for(docname, self, collapse, **kwds)
self.fix_refuris(toctree)
if toctree is not None:
self.fix_refuris(toctree)
return self.render_partial(toctree)['fragment']
def assemble_doctree(self):

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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/builders/linkcheck.py
View File

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

2
sphinx/builders/manpage.py
View File

@@ -5,7 +5,7 @@
Manual pages builder.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function

2
sphinx/config.py
View File

@@ -5,7 +5,7 @@
Build configuration file handling.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/deprecation.py
View File

@@ -5,7 +5,7 @@
Sphinx deprecation classes and utilities.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/directives/__init__.py
View File

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

14
sphinx/directives/code.py
View File

@@ -3,7 +3,7 @@
sphinx.directives.code
~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -314,6 +314,11 @@ class LiteralIncludeReader(object):
self.lineno_start += lineno
return lines[lineno:]
else:
if inclusive is True:
raise ValueError('start-after pattern not found: %s' % start)
else:
raise ValueError('start-at pattern not found: %s' % start)
return lines
@@ -338,6 +343,11 @@ class LiteralIncludeReader(object):
return []
else:
return lines[:lineno]
else:
if inclusive is True:
raise ValueError('end-at pattern not found: %s' % end)
else:
raise ValueError('end-before pattern not found: %s' % end)
return lines
@@ -424,7 +434,7 @@ class LiteralInclude(Directive):
'lineno-match' in self.options)
retnode['classes'] += self.options.get('class', [])
extra_args = retnode['highlight_args'] = {}
if 'empahsize-lines' in self.options:
if 'emphasize-lines' in self.options:
hl_lines = parselinenos(self.options['emphasize-lines'], lines)
if any(i >= lines for i in hl_lines):
logger.warning('line number spec is out of range(1-%d): %r' %

2
sphinx/directives/other.py
View File

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

2
sphinx/directives/patches.py
View File

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

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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/domains/cpp.py
View File

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

243
sphinx/domains/javascript.py
View File

@@ -5,10 +5,13 @@
The JavaScript domain.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from docutils import nodes
from docutils.parsers.rst import Directive, directives
from sphinx import addnodes
from sphinx.domains import Domain, ObjType
from sphinx.locale import l_, _
@@ -38,57 +41,68 @@ class JSObject(ObjectDescription):
#: what is displayed right before the documentation entry
display_prefix = None # type: unicode
#: If ``allow_nesting`` is ``True``, the object prefixes will be accumulated
#: based on directive nesting
allow_nesting = False
def handle_signature(self, sig, signode):
# type: (unicode, addnodes.desc_signature) -> Tuple[unicode, unicode]
"""Breaks down construct signatures
Parses out prefix and argument list from construct definition. The
namespace and class will be determined by the nesting of domain
directives.
"""
sig = sig.strip()
if '(' in sig and sig[-1:] == ')':
prefix, arglist = sig.split('(', 1)
prefix = prefix.strip()
member, arglist = sig.split('(', 1)
member = member.strip()
arglist = arglist[:-1].strip()
else:
prefix = sig
member = sig
arglist = None
if '.' in prefix:
nameprefix, name = prefix.rsplit('.', 1)
else:
nameprefix = None
name = prefix
# If construct is nested, prefix the current prefix
prefix = self.env.ref_context.get('js:object', None)
mod_name = self.env.ref_context.get('js:module')
name = member
try:
member_prefix, member_name = member.rsplit('.', 1)
except ValueError:
member_name = name
member_prefix = ''
finally:
name = member_name
if prefix and member_prefix:
prefix = '.'.join([prefix, member_prefix])
elif prefix is None and member_prefix:
prefix = member_prefix
fullname = name
if prefix:
fullname = '.'.join([prefix, name])
objectname = self.env.ref_context.get('js:object')
if nameprefix:
if objectname:
# someone documenting the method of an attribute of the current
# object? shouldn't happen but who knows...
nameprefix = objectname + '.' + nameprefix
fullname = nameprefix + '.' + name
elif objectname:
fullname = objectname + '.' + name
else:
# just a function or constructor
objectname = ''
fullname = name
signode['object'] = objectname
signode['module'] = mod_name
signode['object'] = prefix
signode['fullname'] = fullname
if self.display_prefix:
signode += addnodes.desc_annotation(self.display_prefix,
self.display_prefix)
if nameprefix:
signode += addnodes.desc_addname(nameprefix + '.', nameprefix + '.')
if prefix:
signode += addnodes.desc_addname(prefix + '.', prefix + '.')
elif mod_name:
signode += addnodes.desc_addname(mod_name + '.', mod_name + '.')
signode += addnodes.desc_name(name, name)
if self.has_arguments:
if not arglist:
signode += addnodes.desc_parameterlist()
else:
_pseudo_parse_arglist(signode, arglist)
return fullname, nameprefix
return fullname, prefix
def add_target_and_index(self, name_obj, sig, signode):
# type: (Tuple[unicode, unicode], unicode, addnodes.desc_signature) -> None
objectname = self.options.get(
'object', self.env.ref_context.get('js:object'))
fullname = name_obj[0]
mod_name = self.env.ref_context.get('js:module')
fullname = (mod_name and mod_name + '.' or '') + name_obj[0]
if fullname not in self.state.document.ids:
signode['names'].append(fullname)
signode['ids'].append(fullname.replace('$', '_S_'))
@@ -103,7 +117,7 @@ class JSObject(ObjectDescription):
line=self.lineno)
objects[fullname] = self.env.docname, self.objtype
indextext = self.get_index_text(objectname, name_obj)
indextext = self.get_index_text(mod_name, name_obj)
if indextext:
self.indexnode['entries'].append(('single', indextext,
fullname.replace('$', '_S_'),
@@ -124,6 +138,63 @@ class JSObject(ObjectDescription):
return _('%s (%s attribute)') % (name, obj)
return ''
def before_content(self):
# type: () -> None
"""Handle object nesting before content
:py:class:`JSObject` represents JavaScript language constructs. For
constructs that are nestable, this method will build up a stack of the
nesting heirarchy so that it can be later de-nested correctly, in
:py:meth:`after_content`.
For constructs that aren't nestable, the stack is bypassed, and instead
only the most recent object is tracked. This object prefix name will be
removed with :py:meth:`after_content`.
The following keys are used in ``self.env.ref_context``:
js:objects
Stores the object prefix history. With each nested element, we
add the object prefix to this list. When we exit that object's
nesting level, :py:meth:`after_content` is triggered and the
prefix is removed from the end of the list.
js:object
Current object prefix. This should generally reflect the last
element in the prefix history
"""
prefix = None
if self.names:
(obj_name, obj_name_prefix) = self.names.pop()
prefix = obj_name_prefix.strip('.') if obj_name_prefix else None
if self.allow_nesting:
prefix = obj_name
if prefix:
self.env.ref_context['js:object'] = prefix
if self.allow_nesting:
objects = self.env.ref_context.setdefault('js:objects', [])
objects.append(prefix)
def after_content(self):
# type: () -> None
"""Handle object de-nesting after content
If this class is a nestable object, removing the last nested class prefix
ends further nesting in the object.
If this class is not a nestable object, the list of classes should not
be altered as we didn't affect the nesting levels in
:py:meth:`before_content`.
"""
objects = self.env.ref_context.setdefault('js:objects', [])
if self.allow_nesting:
try:
objects.pop()
except IndexError:
pass
self.env.ref_context['js:object'] = (objects[-1] if len(objects) > 0
else None)
class JSCallable(JSObject):
"""Description of a JavaScript function, method or constructor."""
@@ -146,6 +217,57 @@ class JSCallable(JSObject):
class JSConstructor(JSCallable):
"""Like a callable but with a different prefix."""
display_prefix = 'class '
allow_nesting = True
class JSModule(Directive):
"""
Directive to mark description of a new JavaScript module.
This directive specifies the module name that will be used by objects that
follow this directive.
Options
-------
noindex
If the ``noindex`` option is specified, no linkable elements will be
created, and the module won't be added to the global module index. This
is useful for splitting up the module definition across multiple
sections or files.
:param mod_name: Module name
"""
has_content = False
required_arguments = 1
optional_arguments = 0
final_argument_whitespace = False
option_spec = {
'noindex': directives.flag
}
def run(self):
# type: () -> List[nodes.Node]
env = self.state.document.settings.env
mod_name = self.arguments[0].strip()
env.ref_context['js:module'] = mod_name
noindex = 'noindex' in self.options
ret = []
if not noindex:
env.domaindata['js']['modules'][mod_name] = env.docname
# Make a duplicate entry in 'objects' to facilitate searching for
# the module in JavaScriptDomain.find_obj()
env.domaindata['js']['objects'][mod_name] = (env.docname, 'module')
targetnode = nodes.target('', '', ids=['module-' + mod_name],
ismod=True)
self.state.document.note_explicit_target(targetnode)
ret.append(targetnode)
indextext = _('%s (module)') % mod_name
inode = addnodes.index(entries=[('single', indextext,
'module-' + mod_name, '', None)])
ret.append(inode)
return ret
class JSXRefRole(XRefRole):
@@ -153,6 +275,7 @@ class JSXRefRole(XRefRole):
# type: (BuildEnvironment, nodes.Node, bool, unicode, unicode) -> Tuple[unicode, unicode] # NOQA
# basically what sphinx.domains.python.PyXRefRole does
refnode['js:object'] = env.ref_context.get('js:object')
refnode['js:module'] = env.ref_context.get('js:module')
if not has_explicit_title:
title = title.lstrip('.')
target = target.lstrip('~')
@@ -174,31 +297,41 @@ class JavaScriptDomain(Domain):
# if you add a new object type make sure to edit JSObject.get_index_string
object_types = {
'function': ObjType(l_('function'), 'func'),
'method': ObjType(l_('method'), 'meth'),
'class': ObjType(l_('class'), 'class'),
'data': ObjType(l_('data'), 'data'),
'attribute': ObjType(l_('attribute'), 'attr'),
'module': ObjType(l_('module'), 'mod'),
}
directives = {
'function': JSCallable,
'method': JSCallable,
'class': JSConstructor,
'data': JSObject,
'attribute': JSObject,
'module': JSModule,
}
roles = {
'func': JSXRefRole(fix_parens=True),
'meth': JSXRefRole(fix_parens=True),
'class': JSXRefRole(fix_parens=True),
'data': JSXRefRole(),
'attr': JSXRefRole(),
'mod': JSXRefRole(),
}
initial_data = {
'objects': {}, # fullname -> docname, objtype
'modules': {}, # mod_name -> docname
} # type: Dict[unicode, Dict[unicode, Tuple[unicode, unicode]]]
def clear_doc(self, docname):
# type: (unicode) -> None
for fullname, (fn, _l) in list(self.data['objects'].items()):
if fn == docname:
for fullname, (pkg_docname, _l) in list(self.data['objects'].items()):
if pkg_docname == docname:
del self.data['objects'][fullname]
for mod_name, pkg_docname in list(self.data['modules'].items()):
if pkg_docname == docname:
del self.data['modules'][mod_name]
def merge_domaindata(self, docnames, otherdata):
# type: (List[unicode], Dict) -> None
@@ -206,31 +339,42 @@ class JavaScriptDomain(Domain):
for fullname, (fn, objtype) in otherdata['objects'].items():
if fn in docnames:
self.data['objects'][fullname] = (fn, objtype)
for mod_name, pkg_docname in otherdata['modules'].items():
if pkg_docname in docnames:
self.data['modules'][mod_name] = pkg_docname
def find_obj(self, env, obj, name, typ, searchorder=0):
# type: (BuildEnvironment, unicode, unicode, unicode, int) -> Tuple[unicode, Tuple[unicode, unicode]] # NOQA
def find_obj(self, env, mod_name, prefix, name, typ, searchorder=0):
# type: (BuildEnvironment, unicode, unicode, unicode, unicode, int) -> Tuple[unicode, Tuple[unicode, unicode]] # NOQA
if name[-2:] == '()':
name = name[:-2]
objects = self.data['objects']
searches = []
if mod_name and prefix:
searches.append('.'.join([mod_name, prefix, name]))
if mod_name:
searches.append('.'.join([mod_name, name]))
if prefix:
searches.append('.'.join([prefix, name]))
searches.append(name)
if searchorder == 0:
searches.reverse()
newname = None
if searchorder == 1:
if obj and obj + '.' + name in objects:
newname = obj + '.' + name
else:
newname = name
else:
if name in objects:
newname = name
elif obj and obj + '.' + name in objects:
newname = obj + '.' + name
for search_name in searches:
if search_name in objects:
newname = search_name
return newname, objects.get(newname)
def resolve_xref(self, env, fromdocname, builder, typ, target, node,
contnode):
# type: (BuildEnvironment, unicode, Builder, unicode, unicode, nodes.Node, nodes.Node) -> nodes.Node # NOQA
objectname = node.get('js:object')
mod_name = node.get('js:module')
prefix = node.get('js:object')
searchorder = node.hasattr('refspecific') and 1 or 0
name, obj = self.find_obj(env, objectname, target, typ, searchorder)
name, obj = self.find_obj(env, mod_name, prefix, target, typ, searchorder)
if not obj:
return None
return make_refnode(builder, fromdocname, obj[0],
@@ -239,8 +383,9 @@ class JavaScriptDomain(Domain):
def resolve_any_xref(self, env, fromdocname, builder, target, node,
contnode):
# type: (BuildEnvironment, unicode, Builder, unicode, nodes.Node, nodes.Node) -> List[Tuple[unicode, nodes.Node]] # NOQA
objectname = node.get('js:object')
name, obj = self.find_obj(env, objectname, target, None, 1)
mod_name = node.get('js:module')
prefix = node.get('js:object')
name, obj = self.find_obj(env, mod_name, prefix, target, None, 1)
if not obj:
return []
return [('js:' + self.role_for_objtype(obj[1]),

5
sphinx/domains/python.py
View File

@@ -5,7 +5,7 @@
The Python domain.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -332,6 +332,7 @@ class PyObject(ObjectDescription):
only the most recent object is tracked. This object prefix name will be
removed with :py:meth:`after_content`.
"""
prefix = None
if self.names:
# fullname and name_prefix come from the `handle_signature` method.
# fullname represents the full object name that is constructed using
@@ -342,8 +343,6 @@ class PyObject(ObjectDescription):
prefix = fullname
elif name_prefix:
prefix = name_prefix.strip('.')
else:
prefix = None
if prefix:
self.env.ref_context['py:class'] = prefix
if self.allow_nesting:

2
sphinx/domains/rst.py
View File

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

4
sphinx/domains/std.py
View File

@@ -5,7 +5,7 @@
The standard domain.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -571,7 +571,7 @@ class StandardDomain(Domain):
if label in self.data['citations']:
path = env.doc2path(self.data['citations'][label][0])
logger.warning('duplicate citation %s, other instance in %s', label, path,
location=node)
location=node, type='ref', subtype='citation')
self.data['citations'][label] = (docname, node['ids'][0])
def note_labels(self, env, docname, document):

31
sphinx/environment/__init__.py
View File

@@ -5,7 +5,7 @@
Global creation environment.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -43,6 +43,7 @@ from sphinx.util.matching import compile_matchers
from sphinx.util.parallel import ParallelTasks, parallel_available, make_chunks
from sphinx.util.websupport import is_commentable
from sphinx.errors import SphinxError, ExtensionError
from sphinx.locale import _
from sphinx.transforms import SphinxTransformer
from sphinx.versioning import add_uids, merge_doctrees
from sphinx.deprecation import RemovedInSphinx17Warning, RemovedInSphinx20Warning
@@ -559,22 +560,20 @@ class BuildEnvironment(object):
# check if we should do parallel or serial read
par_ok = False
if parallel_available and len(docnames) > 5 and self.app.parallel > 1:
par_ok = True
for extname, md in self.app._extension_metadata.items():
ext_ok = md.get('parallel_read_safe')
if ext_ok:
continue
if ext_ok is None:
logger.warning('the %s extension does not declare if it '
'is safe for parallel reading, assuming it '
'isn\'t - please ask the extension author to '
'check and make it explicit', extname)
for ext in itervalues(self.app.extensions):
if ext.parallel_read_safe is None:
logger.warning(_('the %s extension does not declare if it is safe '
'for parallel reading, assuming it isn\'t - please '
'ask the extension author to check and make it '
'explicit'), ext.name)
logger.warning('doing serial read')
else:
logger.warning('the %s extension is not safe for parallel '
'reading, doing serial read', extname)
par_ok = False
break
break
elif ext.parallel_read_safe is False:
break
else:
# all extensions support parallel-read
par_ok = True
if par_ok:
self._read_parallel(docnames, self.app, nproc=self.app.parallel)
else:

2
sphinx/environment/adapters/__init__.py
View File

@@ -5,6 +5,6 @@
Sphinx environment adapters
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

6
sphinx/environment/adapters/indexentries.py
View File

@@ -5,7 +5,7 @@
Index entries adapters for sphinx.environment.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import re
@@ -13,10 +13,10 @@ import bisect
import unicodedata
from itertools import groupby
from six import text_type
from six import text_type, iteritems
from sphinx.locale import _
from sphinx.util import iteritems, split_into, logging
from sphinx.util import split_into, logging
if False:
# For type annotation

2
sphinx/environment/adapters/toctree.py
View File

@@ -5,7 +5,7 @@
Toctree adapter for sphinx.environment.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/__init__.py
View File

@@ -5,7 +5,7 @@
The data collector components for sphinx.environment.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/asset.py
View File

@@ -5,7 +5,7 @@
The image collector for sphinx.environment.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/dependencies.py
View File

@@ -5,7 +5,7 @@
The dependencies collector components for sphinx.environment.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/indexentries.py
View File

@@ -5,7 +5,7 @@
Index entries collector for sphinx.environment.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/metadata.py
View File

@@ -5,7 +5,7 @@
The metadata collector components for sphinx.environment.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/title.py
View File

@@ -5,7 +5,7 @@
The title collector components for sphinx.environment.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/environment/collectors/toctree.py
View File

@@ -5,7 +5,7 @@
Toctree collector for sphinx.environment.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

6
sphinx/events.py
View File

@@ -7,12 +7,12 @@
Gracefully adapted from the TextPress system by Armin.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function
from collections import defaultdict
from collections import OrderedDict, defaultdict
from six import itervalues
@@ -47,7 +47,7 @@ class EventManager(object):
def __init__(self):
# type: () -> None
self.events = core_events.copy()
self.listeners = defaultdict(dict) # type: Dict[unicode, Dict[int, Callable]]
self.listeners = defaultdict(OrderedDict) # type: Dict[unicode, Dict[int, Callable]]
self.next_listener_id = 0
def add(self, name):

2
sphinx/ext/__init__.py
View File

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

2
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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/autosectionlabel.py
View File

@@ -5,7 +5,7 @@
Allow reference sections by :ref: role using its title.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

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

@@ -14,7 +14,7 @@
generate:
sphinx-autogen -o source/generated source/*.rst
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function
@@ -34,6 +34,7 @@ from sphinx.ext.autosummary import import_by_name, get_documenter
from sphinx.jinja2glue import BuiltinTemplateLoader
from sphinx.util.osutil import ensuredir
from sphinx.util.inspect import safe_getattr
from sphinx.util.rst import escape as rst_escape
# Add documenters to AutoDirective registry
from sphinx.ext.autodoc import add_documenter, \
@@ -95,6 +96,12 @@ def _simple_warn(msg):
print('WARNING: ' + msg, file=sys.stderr)
def _underline(title, line='='):
if '\n' in title:
raise ValueError('Can only underline single lines')
return title + '\n' + line * len(title)
# -- Generating output ---------------------------------------------------------
def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
@@ -130,6 +137,11 @@ def generate_autosummary_docs(sources, output_dir=None, suffix='.rst',
template_dirs.insert(0, template_dir)
template_loader = FileSystemLoader(template_dirs) # type: ignore
template_env = SandboxedEnvironment(loader=template_loader)
template_env.filters['underline'] = _underline
# replace the builtin html filters
template_env.filters['escape'] = rst_escape
template_env.filters['e'] = rst_escape
# read
items = find_autosummary_in_files(sources)

3
sphinx/ext/autosummary/templates/autosummary/base.rst
View File

@@ -1,5 +1,4 @@
{{ fullname }}
{{ underline }}
{{ fullname | escape | underline}}
.. currentmodule:: {{ module }}

3
sphinx/ext/autosummary/templates/autosummary/class.rst
View File

@@ -1,5 +1,4 @@
{{ fullname }}
{{ underline }}
{{ fullname | escape | underline}}
.. currentmodule:: {{ module }}

3
sphinx/ext/autosummary/templates/autosummary/module.rst
View File

@@ -1,5 +1,4 @@
{{ fullname }}
{{ underline }}
{{ fullname | escape | underline}}
.. automodule:: {{ fullname }}

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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import absolute_import

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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/githubpages.py
View File

@@ -5,7 +5,7 @@
To publish HTML docs at GitHub Pages, create .nojekyll file.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/ext/imgmath.py
View File

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

2
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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

5
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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -372,4 +372,7 @@ def debug(argv):
if __name__ == '__main__':
import logging # type: ignore
logging.basicConfig()
debug(argv=sys.argv) # type: ignore

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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
@@ -74,7 +74,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://cdn.mathjax.org/mathjax/latest/MathJax.js?'
'https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

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

@@ -7,7 +7,7 @@
Classes for docstring parsing and formatting.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

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

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

2
sphinx/ext/pngmath.py
View File

@@ -6,7 +6,7 @@
Render math in HTML via dvipng. This extension has been deprecated; please
use sphinx.ext.imgmath instead.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

120
sphinx/extension.py Normal file
View File

@@ -0,0 +1,120 @@
# -*- coding: utf-8 -*-
"""
sphinx.extension
~~~~~~~~~~~~~~~~
Utilities for Sphinx extensions.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
import traceback
from six import iteritems
from sphinx.errors import ExtensionError, VersionRequirementError
from sphinx.locale import _
from sphinx.util import logging
if False:
# For type annotation
from typing import Any, Dict # NOQA
from sphinx.application import Sphinx # NOQA
logger = logging.getLogger(__name__)
# list of deprecated extensions. Keys are extension name.
# Values are Sphinx version that merge the extension.
EXTENSION_BLACKLIST = {
"sphinxjp.themecore": "1.2"
} # type: Dict[unicode, unicode]
class Extension(object):
def __init__(self, name, module, **kwargs):
self.name = name
self.module = module
self.metadata = kwargs
self.version = kwargs.pop('version', 'unknown version')
# The extension supports parallel read or not. The default value
# is ``None``. It means the extension does not tell the status.
# It will be warned on parallel reading.
self.parallel_read_safe = kwargs.pop('parallel_read_safe', None)
# The extension supports parallel write or not. The default value
# is ``True``. Sphinx writes parallelly documents even if
# the extension does not tell its status.
self.parallel_write_safe = kwargs.pop('parallel_read_safe', True)
def load_extension(app, extname):
# type: (Sphinx, unicode) -> None
"""Load a Sphinx extension."""
if extname in app.extensions: # alread loaded
return
if extname in EXTENSION_BLACKLIST:
logger.warning(_('the extension %r was already merged with Sphinx since '
'version %s; this extension is ignored.'),
extname, EXTENSION_BLACKLIST[extname])
return
# update loading context
app._setting_up_extension.append(extname)
try:
mod = __import__(extname, None, None, ['setup'])
except ImportError as err:
logger.verbose(_('Original exception:\n') + traceback.format_exc())
raise ExtensionError(_('Could not import extension %s') % extname, err)
if not hasattr(mod, 'setup'):
logger.warning(_('extension %r has no setup() function; is it really '
'a Sphinx extension module?'), extname)
metadata = {} # type: Dict[unicode, Any]
else:
try:
metadata = mod.setup(app)
except VersionRequirementError as err:
# add the extension name to the version required
raise VersionRequirementError(
_('The %s extension used by this project needs at least '
'Sphinx v%s; it therefore cannot be built with this '
'version.') % (extname, err)
)
if metadata is None:
metadata = {}
if extname == 'rst2pdf.pdfbuilder':
metadata['parallel_read_safe'] = True
elif not isinstance(metadata, dict):
logger.warning(_('extension %r returned an unsupported object from '
'its setup() function; it should return None or a '
'metadata dictionary'), extname)
app.extensions[extname] = Extension(extname, mod, **metadata)
app._setting_up_extension.pop()
def verify_required_extensions(app, requirements):
# type: (Sphinx, Dict[unicode, unicode]) -> None
"""Verify the required Sphinx extensions are loaded."""
if requirements is None:
return
for extname, reqversion in iteritems(requirements):
extension = app.extensions.get(extname)
if extension is None:
logger.warning(_('needs_extensions config value specifies a '
'version requirement for extension %s, but it is '
'not loaded'), extname)
continue
if extension.version == 'unknown version' or reqversion > extension.version:
raise VersionRequirementError(_('This project needs the extension %s at least in '
'version %s and therefore cannot be built with '
'the loaded version (%s).') %
(extname, reqversion, extension.version))

2
sphinx/highlighting.py
View File

@@ -5,7 +5,7 @@
Highlight code blocks using Pygments.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/io.py
View File

@@ -5,7 +5,7 @@
Input/Output files
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from docutils.io import FileInput

2
sphinx/jinja2glue.py
View File

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

2
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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function

2
sphinx/parsers.py
View File

@@ -5,7 +5,7 @@
A Base class for additional parsers.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx/pycode/__init__.py
View File

@@ -5,7 +5,7 @@
Utilities parsing and analyzing Python code.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 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-2016 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""
from __future__ import print_function

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