Merge branch 'stable'

This commit is contained in:
jfbu 2017-06-03 17:36:19 +02:00
commit d4f37925c0
16 changed files with 104 additions and 63 deletions

View File

@ -71,6 +71,10 @@ Features added
Bugs fixed
----------
* #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
* #3829: sphinx-quickstart template is incomplete regarding use of alabaster
* #3772: 'str object' has no attribute 'filename'
Testing
--------
@ -97,7 +101,6 @@ Bugs fixed
* #3770: Build fails when a "code-block" has the option emphasize-lines and the
number indicated is higher than the number of lines
* #3774: Incremental HTML building broken when using citations
* #3772: 'str object' has no attribute 'filename'
* #3763: got epubcheck validations error if epub_cover is set
* #3779: 'ImportError' in sphinx.ext.autodoc due to broken 'sys.meta_path'.
Thanks to Tatiana Tereshchenko.
@ -319,8 +322,8 @@ Deprecated
1.6b1
* ``sphinx.util.compat.Directive`` class is now deprecated. Please use
``docutils.parsers.rst.Directive`` instead.
* ``sphinx.util.compat.Directive`` class is now deprecated. Please use instead
``docutils.parsers.rst.Directive``
* ``sphinx.util.compat.docutils_version`` is now deprecated
* #2367: ``Sphinx.warn()``, ``Sphinx.info()`` and other logging methods are now
deprecated. Please use ``sphinx.util.logging`` (:ref:`logging-api`) instead.

View File

@ -205,8 +205,8 @@ The parts of messages in Sphinx that go into builds are translated into several
locales. The translations are kept as gettext ``.po`` files translated from the
master template ``sphinx/locale/sphinx.pot``.
Sphinx uses `Babel <http://babel.edgewall.org>`_ to extract messages and
maintain the catalog files. It is integrated in ``setup.py``:
Sphinx uses `Babel <http://babel.pocoo.org/en/latest/>`_ to extract messages
and maintain the catalog files. It is integrated in ``setup.py``:
* Use ``python setup.py extract_messages`` to update the ``.pot`` template.
* Use ``python setup.py update_catalog`` to update all existing language
@ -279,7 +279,7 @@ Debugging Tips
* JavaScript stemming algorithms in ``sphinx/search/*.py`` (except ``en.py``) are
generated by this
`modified snowballcode generator <https://github.com/shibukawa/snowball>`_.
Generated `JSX <http://jsx.github.io/>`_ files are
Generated `JSX <https://jsx.github.io/>`_ files are
in `this repository <https://github.com/shibukawa/snowball-stemmer.jsx>`_.
You can get the resulting JavaScript files using the following command::

View File

@ -96,7 +96,7 @@ is available under the following license:
SmartyPants_ license::
Copyright (c) 2003 John Gruber
(http://daringfireball.net/)
(https://daringfireball.net/projects/smartypants/)
All rights reserved.
Redistribution and use in source and binary forms, with or without
@ -196,7 +196,7 @@ The included JQuery JavaScript library is available under the MIT
license:
----------------------------------------------------------------------
Copyright (c) 2008 John Resig, http://jquery.com/
Copyright (c) 2008 John Resig, https://jquery.com/
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the

View File

@ -1,5 +1,5 @@
.. image:: https://img.shields.io/pypi/v/sphinx.svg
:target: http://pypi.python.org/pypi/sphinx
:target: https://pypi.python.org/pypi/Sphinx
.. image:: https://readthedocs.org/projects/sphinx/badge/
:target: http://www.sphinx-doc.org/
:alt: Documentation Status

View File

@ -1,7 +1,7 @@
# How setup this file
# http://babel.edgewall.org/wiki/Documentation/setup.html
# How to setup this file
# http://babel.pocoo.org/en/latest/installation.html
# this file description:
# http://babel.edgewall.org/wiki/Documentation/messages.html#extraction-method-mapping-and-configuration
# http://babel.pocoo.org/en/latest/messages.html
# Extraction from Python source files
[python: **.py]

View File

@ -84,7 +84,7 @@ The builder's "name" must be given to the **-b** command-line option of
.. autoattribute:: supported_image_types
.. _Qt help: http://doc.qt.io/qt-4.8/qthelp-framework.html
.. _Qt help: https://doc.qt.io/qt-4.8/qthelp-framework.html
.. module:: sphinx.builders.applehelp
.. class:: AppleHelpBuilder
@ -209,7 +209,7 @@ The builder's "name" must be given to the **-b** command-line option of
Note that a direct PDF builder using ReportLab is available in `rst2pdf
<https://github.com/rst2pdf/rst2pdf>`_ version 0.12 or greater. You need to add
``'rst2pdf.pdfbuilder'`` to your :confval:`extensions` to enable it, its name is
``pdf``. Refer to the `rst2pdf manual <http://ralsina.me/static/manual.pdf>`_
``pdf``. Refer to the `rst2pdf manual <https://ralsina.me/static/manual.pdf>`_
for details.
.. module:: sphinx.builders.text
@ -255,7 +255,7 @@ for details.
the terminal-based program :program:`info`. See :ref:`texinfo-faq` for more
details. The Texinfo format is the official documentation system used by the
GNU project. More information on Texinfo can be found at
`<http://www.gnu.org/software/texinfo/>`_.
`<https://www.gnu.org/software/texinfo/>`_.
.. autoattribute:: name

View File

@ -27,19 +27,27 @@ releases on PyPI, others you can install from a checkout.
This is the current list of contributed extensions in that repository:
- aafig: render embedded ASCII art as nice images using aafigure_.
- aafig: render embedded ASCII art as nice images using aafigure_
- actdiag: embed activity diagrams by using actdiag_
- adadomain: an extension for Ada support (Sphinx 1.0 needed)
- ansi: parse ANSI color sequences inside documents
- autorun: Execute code in a ``runblock`` directive.
- argdoc: automatically generate documentation for command-line arguments, descriptions, and help text
- astah: embed diagram by using astah
- autoanysrc: Gather reST documentation from any source files
- autorun: Execute code in a ``runblock`` directive
- blockdiag: embed block diagrams by using blockdiag_
- cacoo: embed diagram from Cacoo
- cf3domain: a domain for CFEngine 3 policies
- cheader: The missing c:header directive for Sphinx's built-in C domain
- cheeseshop: easily link to PyPI packages
- clearquest: create tables from ClearQuest_ queries.
- clearquest: create tables from ClearQuest_ queries
- cmakedomain_: a domain for CMake_
- coffeedomain: a domain for (auto)documenting CoffeeScript source code.
- context: a builder for ConTeXt.
- coffeedomain: a domain for (auto)documenting CoffeeScript source code
- context: a builder for ConTeXt
- disqus: embed Disqus comments in documents
- documentedlist: converts a Python list to a table in the generated documentation
- doxylink: Link to external Doxygen-generated HTML documentation
- domaintools_: A tool for easy domain creation.
- domaintools_: A tool for easy domain creation
- email: obfuscate email addresses
- erlangdomain: an extension for Erlang support (Sphinx 1.0 needed)
- exceltable: embed Excel spreadsheets into documents using exceltable_
@ -47,47 +55,49 @@ This is the current list of contributed extensions in that repository:
from your site content
- findanything_: an extension to add Sublime Text 2-like findanything panels
to your documentation to find pages, sections and index entries while typing
- gnuplot: produces images using gnuplot_ language.
- gnuplot: produces images using gnuplot_ language
- googleanalytics: track web visitor statistics by using `Google Analytics`_
- googlechart: embed charts by using `Google Chart`_
- googlemaps: embed maps by using `Google Maps`_
- httpdomain: a domain for documenting RESTful HTTP APIs.
- httpdomain: a domain for documenting RESTful HTTP APIs
- hyphenator: client-side hyphenation of HTML using hyphenator_
- imgur: embed Imgur images, albums, and metadata in documents
- inlinesyntaxhighlight_: inline syntax highlighting
- lassodomain: a domain for documenting Lasso_ source code
- libreoffice: an extension to include any drawing supported by LibreOffice (e.g. odg, vsd, ...).
- lilypond: an extension inserting music scripts from Lilypond_ in PNG format.
- libreoffice: an extension to include any drawing supported by LibreOffice (e.g. odg, vsd, ...)
- lilypond: an extension inserting music scripts from Lilypond_ in PNG format
- makedomain_: a domain for `GNU Make`_
- matlabdomain: document MATLAB_ code.
- mockautodoc: mock imports.
- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s.
- napoleon: supports `Google style`_ and `NumPy style`_ docstrings.
- matlabdomain: document MATLAB_ code
- mockautodoc: mock imports
- mscgen: embed mscgen-formatted MSC (Message Sequence Chart)s
- napoleon: supports `Google style`_ and `NumPy style`_ docstrings
- nicovideo: embed videos from nicovideo
- nwdiag: embed network diagrams by using nwdiag_
- omegat: support tools to collaborate with OmegaT_ (Sphinx 1.1 needed)
- osaka: convert standard Japanese doc to Osaka dialect (this is a joke extension)
- paverutils: an alternate integration of Sphinx with Paver_.
- paverutils: an alternate integration of Sphinx with Paver_
- phpdomain: an extension for PHP support
- plantuml: embed UML diagram by using PlantUML_
- py_directive: Execute python code in a ``py`` directive and return a math
node.
- rawfiles: copy raw files, like a CNAME.
node
- rawfiles: copy raw files, like a CNAME
- requirements: declare requirements wherever you need (e.g. in test
docstrings), mark statuses and collect them in a single list
- restbuilder: a builder for reST (reStructuredText) files.
- restbuilder: a builder for reST (reStructuredText) files
- rubydomain: an extension for Ruby support (Sphinx 1.0 needed)
- sadisplay: display SqlAlchemy model sadisplay_
- sdedit: an extension inserting sequence diagram by using Quick Sequence
Diagram Editor (sdedit_)
- seqdiag: embed sequence diagrams by using seqdiag_
- slide: embed presentation slides on slideshare_ and other sites.
- slide: embed presentation slides on slideshare_ and other sites
- swf_: embed flash files
- sword: an extension inserting Bible verses from Sword_.
- tikz: draw pictures with the `TikZ/PGF LaTeX package`_.
- sword: an extension inserting Bible verses from Sword_
- tikz: draw pictures with the `TikZ/PGF LaTeX package`_
- traclinks: create TracLinks_ to a Trac_ instance from within Sphinx
- versioning: Sphinx extension that allows building versioned docs for self-hosting
- whooshindex: whoosh indexer extension
- youtube: embed videos from YouTube_
- zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_.
- zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_
See the :ref:`extension tutorial <exttut>` on getting started with writing your

View File

@ -34,8 +34,8 @@ documentation wants to refer to e.g. C++ and Python classes. It also means that
extensions that support the documentation of whole new languages are much easier
to write.
This section describes what the domains that come with Sphinx provide. The
domain API is documented as well, in the section :ref:`domain-api`.
This section describes what the domains that are included with Sphinx provide.
The domain API is documented as well, in the section :ref:`domain-api`.
.. _basic-domain-markup:

View File

@ -4,7 +4,7 @@ Sphinx Extensions
=================
Since many projects will need special features in their documentation, Sphinx
allows to add "extensions" to the build process, each of which can modify almost
allows adding "extensions" to the build process, each of which can modify almost
any aspect of document processing.
This chapter describes the extensions bundled with Sphinx. For the API

View File

@ -140,7 +140,7 @@ The following list gives some hints for the creation of epub files:
are often cut at the right margin. The default Courier font (or variant) is
quite wide and you can only display up to 60 characters on a line. If you
replace it with a narrower font, you can get more characters on a line. You
may even use `FontForge <http://fontforge.github.io/>`_ and create
may even use `FontForge <https://fontforge.github.io/>`_ and create
narrow variants of some free font. In my case I get up to 70 characters on a
line.
@ -148,7 +148,7 @@ The following list gives some hints for the creation of epub files:
* Test the created epubs. You can use several alternatives. The ones I am aware
of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS),
and Bookworm_. For bookworm you can download the source from
and Bookworm_. For Bookworm, you can download the source from
https://code.google.com/archive/p/threepress and run your own local server.
* Large floating divs are not displayed properly.
@ -176,7 +176,7 @@ The following list gives some hints for the creation of epub files:
$ make epub
$ kindlegen _build/epub/yourdoc.epub
kindlegen commands doesn't accept documents that have section
The kindlegen command doesn't accept documents that have section
titles surrounding ``toctree`` directive:
.. code-block:: rst
@ -191,18 +191,18 @@ The following list gives some hints for the creation of epub files:
Section After Toc Tree
======================
kindlegen assumes all documents order in line, but resulting document
has complecated order for kindlegen::
kindlegen assumes all documents order in line, but the resulting document
has complicated order for kindlegen::
``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
If you got the following error, fix document structure::
If you get the following error, fix your document structure::
Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
Error(prcgen):E24001: The table of content could not be built.
.. _Epubcheck: https://github.com/IDPF/epubcheck
.. _Calibre: http://calibre-ebook.com/
.. _Calibre: https://calibre-ebook.com/
.. _FBreader: https://fbreader.org/
.. _Bookworm: http://www.oreilly.com/bookworm/index.html
.. _kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211
@ -239,7 +239,7 @@ The exact behavior of how Emacs displays references is dependent on the variable
both the ``*note:`` part and the ``target-id``. This is generally the best way
to view Sphinx-based documents since they often make frequent use of links and
do not take this limitation into account. However, changing this variable
affects how all Info documents are displayed and most due take this behavior
affects how all Info documents are displayed and most do take this behavior
into account.
If you want Emacs to display Info files produced by Sphinx using the value

View File

@ -57,7 +57,7 @@ in Python string literals to reach latex.) For example::
}
latex_show_urls = 'footnote'
.. the above was tested on Sphinx's own 1.5a2 documentation with good effect !
.. the above was tested on Sphinx's own 1.5a2 documentation with good effect!
.. highlight:: latex
@ -92,8 +92,8 @@ string of ``key=value`` instructions::
key1=value1,key2=value2, ...
- if a key is repeated, it is its last occurence which counts,
- spaces around the commas and equal signs are ignored.
- if a key is repeated, it is its last occurence which is used
- spaces around the commas and equal signs are ignored
If non-empty, it will be passed as argument to the ``\sphinxsetup`` command::
@ -148,7 +148,7 @@ Here are the currently available options together with their default values.
.. attention::
LaTeX requires for keys with Boolean values to use **lowercase** ``true`` or
LaTeX requires that keys with Boolean values use **lowercase** ``true`` or
``false``.
.. _latexsphinxsetuphmargin:
@ -215,8 +215,8 @@ Here are the currently available options together with their default values.
.. (comment) It is theoretically possible to customize this even
more and decide at which characters a line-break can occur and whether
before or after, but this is accessible currently only by re-defining some
macros with complicated LaTeX syntax from :file:`sphinx.sty`.
before or after, but this is accessible currently only by re-defining
some macros with complicated LaTeX syntax from :file:`sphinx.sty`.
``parsedliteralwraps``
default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's
@ -230,8 +230,7 @@ Here are the currently available options together with their default values.
potential break-points (additionally to those allowed by LaTeX at spaces
or for hyphenation) are currently inserted only after the characters
``. , ; ? ! /``. Due to TeX internals, white space in the line will be
stretched
(or shrinked) in order to accomodate the linebreak.
stretched (or shrunk) in order to accomodate the linebreak.
.. versionadded:: 1.5
set this option value to ``false`` to recover former behaviour.

View File

@ -10,7 +10,7 @@ Using setuptools integration
----------------------------
The Sphinx build can then be triggered from distutils, and some Sphinx
options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx own
options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx's own
configuration file.
For instance, from ``setup.py``::

View File

@ -119,10 +119,12 @@ These themes are:
* **alabaster** -- `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
(especially as used in his Requests project), which was itself originally based on
@mitsuhiko's theme used for Flask & related projects. You can get options information
at `Alabaster theme`_ page.
@mitsuhiko's theme used for Flask & related projects.
Check out at its `installation page`_ how to set up properly
:confval:`html_sidebars` for its use.
.. _Alabaster theme: https://pypi.python.org/pypi/alabaster
.. _installation page: http://alabaster.readthedocs.io/en/latest/installation.html
* **classic** -- This is the classic theme, which looks like `the Python 2
documentation <https://docs.python.org/2/>`_. It can be customized via

View File

@ -96,6 +96,18 @@ todo_include_todos = {{ ext_todo }}
#
html_theme = 'alabaster'
# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
html_sidebars = {
'**': [
'about.html',
'navigation.html',
# 'relations.html', # hidden by alabaster css anyway
'searchbox.html',
# 'donate.html',
]
}
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.

View File

@ -106,7 +106,11 @@
<link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
<link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
{%- for css in css_files %}
{%- if css|attr("rel") %}
<link rel="{{ css.rel }}" href="{{ pathto(css.filename, 1) }}" type="text/css"{% if css.title is not none %} title="{{ css.title }}"{% endif %} />
{%- else %}
<link href="{{ pathto(css, 1) }}" type="text/css" />
{%- endif %}
{%- endfor %}
{%- endmacro %}

View File

@ -143,12 +143,23 @@ def educateQuotes(text, language='en'):
def educate_tokens(text_tokens, attr='1', language='en'):
# type: (Iterable[Tuple[str, unicode]], unicode, unicode) -> Iterator
"""Return iterator that "educates" the items of `text_tokens`.
This is modified to intercept the ``attr='2'`` as it was used by the
Docutils 0.13.1 SmartQuotes transform in a hard coded way. Docutils 0.14
uses ``'qDe'``` and is configurable, and its choice is backported here
for use by Sphinx with earlier Docutils releases. Similarly ``'1'`` is
replaced by ``'qde'``.
Use ``attr='qDbe'``, resp. ``'qdbe'`` to recover Docutils effect of ``'2'``,
resp. ``'1'``.
refs: https://sourceforge.net/p/docutils/mailman/message/35869025/
"""
# Parse attributes:
# 0 : do nothing
# 1 : set all
# 2 : set all, using old school en- and em- dash shortcuts
# 1 : set all (but backticks)
# 2 : set all (but backticks), using old school en- and em- dash shortcuts
# 3 : set all, using inverted old school en and em- dash shortcuts
#
# q : quotes
@ -171,13 +182,13 @@ def educate_tokens(text_tokens, attr='1', language='en'):
pass
elif attr == "1": # Do everything, turn all options on.
do_quotes = True
do_backticks = 1
# do_backticks = 1
do_dashes = 1
do_ellipses = True
elif attr == "2":
# Do everything, turn all options on, use old school dash shorthand.
do_quotes = True
do_backticks = 1
# do_backticks = 1
do_dashes = 2
do_ellipses = True
elif attr == "3":