Merge remote-tracking branch 'upstream/master'

.appveyor.yml

@@ -5,21 +5,15 @@ environment:
     PYTHONWARNINGS: all
 
   matrix:
-    - PYTHON: 27
+    - PYTHON: 37
-      DOCUTILS: 0.12
+    - PYTHON: 37-x64
-      TEST_IGNORE: --ignore py35
-    - PYTHON: 27
-      DOCUTILS: 0.13.1
-      TEST_IGNORE: --ignore py35
-    - PYTHON: 36
-      DOCUTILS: 0.13.1
-    - PYTHON: 36-x64
-      DOCUTILS: 0.13.1
 
 install:
   - C:\Python%PYTHON%\python.exe -m pip install -U pip setuptools
-  - C:\Python%PYTHON%\python.exe -m pip install docutils==%DOCUTILS%
+  - C:\Python%PYTHON%\python.exe -m pip install .[test,websupport]
-  - C:\Python%PYTHON%\python.exe -m pip install -r test-reqs.txt
+
+cache:
+  - '%LOCALAPPDATA%\pip\Cache'
 
 # No automatic build, just run python tests
 build: off
@@ -39,10 +33,24 @@ test_script:
       if (-not $test_ignore) { $test_ignore = '' }
       $tests = $env:TEST
       if (-not $tests) { $tests = '' }
-      & "C:\Python$($env:PYTHON)\python.exe" run.py $test_ignore.Split(' ') --junitxml .junit.xml $tests.Split(' ')
+      & "C:\Python$($env:PYTHON)\python.exe" -m pytest $test_ignore.Split(' ') --junitxml .junit.xml $tests.Split(' ')
       Pop-Location
-      if ($LastExitCode -eq 1) { Write-Host "Test Failures Occurred, leaving for test result parsing" }
+      if ($LastExitCode -eq 1) { Write-Host "Test Failures Occurred, leaving for test result parsing"; exit $LastExitCode }
       elseif ($LastExitCode -ne 0) { Write-Host "Other Error Occurred, aborting"; exit $LastExitCode }
 
 after_test:
   - ps: (New-Object System.Net.WebClient).UploadFile("https://ci.appveyor.com/api/testresults/junit/$($env:APPVEYOR_JOB_ID)", (Resolve-Path (Join-Path tests .junit.xml)))
+
+after_build:
+  # Remove old or huge cache files to hopefully not exceed the 1GB cache limit.
+  #
+  # If the cache limit is reached, the cache will not be updated (of not even
+  # created in the first run). So this is a trade of between keeping the cache
+  # current and having a cache at all.
+  # NB: This is done only `on_success` since the cache in uploaded only on
+  # success anyway.
+  - C:\cygwin\bin\find "%LOCALAPPDATA%\pip" -type f -mtime +360 -delete
+  - C:\cygwin\bin\find "%LOCALAPPDATA%\pip" -type f -size +10M -delete
+  - C:\cygwin\bin\find "%LOCALAPPDATA%\pip" -empty -delete
+  # Show size of cache
+  - C:\cygwin\bin\du -hs "%LOCALAPPDATA%\pip\Cache"

.circleci/config.yml

@@ -6,4 +6,6 @@ jobs:
     working_directory: /sphinx
     steps:
       - checkout
-      - run: make test PYTHON=/python3.4/bin/python
+      - run: /python3.5/bin/pip install -U pip setuptools
+      - run: /python3.5/bin/pip install -U .[test,websupport]
+      - run: make test PYTHON=/python3.5/bin/python

.codecov.yml

@@ -0,0 +1,8 @@
+coverage:
+  status:
+    project:
+      default:
+        enabled: no
+    patch:
+      default:
+        enabled: no

.github/ISSUE_TEMPLATE.md

@@ -1,27 +0,0 @@
-Subject: <what happen when you do on which document project>
-
-### Problem
-- <Detail of problem>
-
-#### Procedure to reproduce the problem
-```
-<Paste your command-line here which cause the problem>
-```
-
-#### Error logs / results
-```
-<Paste your error log here>
-```
-- <public link of unexpected result if you have>
-
-#### Expected results
-<Describe what to actually do>
-
-### Reproducible project / your project
-- <link to your project, or attach zipped small project sample>
-
-### Environment info
-- OS: <Unix/Linux/Mac/Win/other with version>
-- Python version:
-- Sphinx version:
-- <Extra tools e.g.: Browser, tex or something else>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,46 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: '<what happen when you do on which document project>'
+labels: 'bug'
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+```
+<Paste your command-line here which cause the problem>
+
+$ git clone htps://github.com/.../some_project
+$ cd some_project
+$ pip install -r requirements.txt
+$ cd docs
+$ make html SPHINXOPTS="-D language=de"
+$ # open _build/html/index and see bla bla
+```
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Your project**
+Link to your sphinx project, or attach zipped small project sample.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Environment info**
+- OS: [e.g. Unix/Linux/Mac/Win/other with version]
+- Python version: [e.g. 3.7.1]
+- Sphinx version: [e.g. 1.8.2]
+- Sphinx extensions:  [e.g. sphinx.ext.autodoc, recommonmark]
+- Extra tools: [e.g. Browser, tex or something else]
+
+**Additional context**
+Add any other context about the problem here.
+
+- [e.g. URL or Ticket]
+

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: '<short description for the feature>'
+labels: 'enhancement'
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.
+
+- [e.g. URL or Ticket]
+

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,17 @@
+---
+name: Question
+about: For Q&A purpose, please use https://groups.google.com/forum/#!forum/sphinx-users
+title: For Q&A purpose, please use sphinx-users group
+labels: 'question'
+assignees: ''
+
+---
+
+# Important
+
+This is a list of issues for Sphinx, **not a forum**.
+If you'd like to post a question, please move to sphinx-users group.
+https://groups.google.com/forum/#!forum/sphinx-users
+
+Thanks,
+

.gitignore

@@ -5,12 +5,17 @@
 
 .dir-locals.el
 .cache/
+.idea
 .mypy_cache/
+.pytest_cache/
 .ropeproject/
 TAGS
 .tags
-.tox
+.tox/
-.venv
+.tx/
+.venv/
+.coverage
+htmlcov
 .DS_Store
 sphinx/pycode/Grammar*pickle
 distribute-*
@@ -20,6 +25,9 @@ build/
 dist/
 Sphinx.egg-info/
 doc/_build/
+doc/locale/
 tests/.coverage
 tests/build/
 utils/regression_test.js
+
+node_modules/

.travis.yml

@@ -1,48 +1,47 @@
 language: python
 sudo: false
-dist: trusty
+dist: xenial
-cache:
+cache: pip
-  directories:
+
-    - $HOME/.cache/pip
-python:
-  - "pypy-5.4.1"
-  - "3.6"
-  - "3.5"
-  - "3.4"
-  - "2.7"
-  - "nightly"
 env:
   global:
-    - TEST='-v --durations 25'
     - PYTHONFAULTHANDLER=x
-    - PYTHONWARNINGS=all
     - SKIP_LATEX_BUILD=1
-  matrix:
+    - IS_PYTHON=true
-    - DOCUTILS=0.12
+
-    - DOCUTILS=0.13.1
 matrix:
-  exclude:
+  include:
-    - python: "3.4"
+    - python: '3.5'
-      env: DOCUTILS=0.12
+      env:
-    - python: "3.5"
+        - TOXENV=du13
-      env: DOCUTILS=0.12
+    - python: '3.6'
-    - python: "3.6"
+      env:
-      env: DOCUTILS=0.12
+        - TOXENV=py36
-    - python: nightly
+        - PYTEST_ADDOPTS="--cov ./ --cov-append --cov-config setup.cfg"
-      env: DOCUTILS=0.12
+    - python: '3.7'
-    - python: "pypy-5.4.1"
+      env: TOXENV=py37
-      env: DOCUTILS=0.12
+    - python: 'nightly'
-addons:
+      env: TOXENV=py38
-  apt:
+    - python: '3.6'
-    packages:
+      env: TOXENV=docs
-      - graphviz
+    - python: '3.6'
-      - imagemagick
+      env: TOXENV=mypy
+    - python: '3.6'
+      env: TOXENV=flake8
+
+    - language: node_js
+      node_js:
+        - 10.7
+      env: IS_PYTHON=false
+      services: xvfb
+
 install:
-  - pip install -U pip setuptools
+  - if [ $IS_PYTHON = true ]; then pip install -U tox codecov; fi
-  - pip install docutils==$DOCUTILS
+  - if [ $IS_PYTHON = false ]; then npm install; fi
-  - pip install -r test-reqs.txt
+
-  - if [[ $TRAVIS_PYTHON_VERSION == '3.6' ]]; then python3.6 -m pip install mypy typed-ast; fi
 script:
-  - flake8
+  - if [ $IS_PYTHON = true ]; then tox -- -v; fi
-  - if [[ $TRAVIS_PYTHON_VERSION == '3.6' ]]; then make style-check type-check test-async; fi
+  - if [ $IS_PYTHON = false ]; then npm test; fi
-  - if [[ $TRAVIS_PYTHON_VERSION != '3.6' ]]; then make test; fi
+
+after_success:
+  - if [[ -e .coverage ]]; then codecov -e $TOXENV; fi

AUTHORS

@@ -14,10 +14,12 @@ Other co-maintainers:
 * Takeshi Komiya <@tk0miya>
 * Jean-François Burnol <@jfbu>
 * Yoshiki Shibukawa <@shibu_jp>
+* Timotheus Kampik - <@TimKam>
 
 Other contributors, listed alphabetically, are:
 
 * Alastair Houghton -- Apple Help builder
+* Alexander Todorov -- inheritance_diagram tests and improvements
 * Andi Albrecht -- agogo theme
 * Jakob Lykke Andersen -- Rewritten C++ domain
 * Henrique Bastos -- SVG support for graphviz extension
@@ -29,15 +31,20 @@ Other contributors, listed alphabetically, are:
 * Kevin Dunn -- MathJax extension
 * Josip Dzolonga -- coverage builder
 * Buck Evan -- dummy builder
+* Matthew Fernandez -- todo extension fix
 * Hernan Grecco -- search improvements
 * Horst Gutmann -- internationalization support
 * Martin Hans -- autodoc improvements
+* Zac Hatfield-Dodds -- doctest reporting improvements
 * Doug Hellmann -- graphviz improvements
-* Timotheus Kampik - JS theme & search enhancements
+* Tim Hoffmann -- theme improvements
+* Antti Kaihola -- doctest extension (skipif option)
 * Dave Kuhlman -- original LaTeX writer
 * Blaise Laflamme -- pyramid theme
+* Chris Lamb -- reproducibility fixes
 * Thomas Lamb -- linkcheck builder
 * Łukasz Langa -- partial support for autodoc
+* Martin Larralde -- additional napoleon admonitions
 * Ian Lee -- quickstart improvements
 * Robert Lehmann -- gettext builder (GSOC project)
 * Dan MacKinlay -- metadata fixes
@@ -45,10 +52,12 @@ Other contributors, listed alphabetically, are:
 * Will Maier -- directory HTML builder
 * Jacob Mason -- websupport library (GSOC project)
 * Glenn Matthews -- python domain signature improvements
+* Kurt McKee -- documentation updates
 * Roland Meister -- epub builder
 * Ezio Melotti -- collapsible sidebar JavaScript
 * Bruce Mitchener -- Minor epub improvement
 * Daniel Neuhäuser -- JavaScript domain, Python 3 support (GSOC)
+* Julien Palard -- Colspan and rowspan in text builder
 * Christopher Perkins -- autosummary integration
 * Benjamin Peterson -- unittests
 * \T. Powers -- HTML output improvements
@@ -57,18 +66,22 @@ Other contributors, listed alphabetically, are:
 * Stefan Seefeld -- toctree improvements
 * Gregory Szorc -- performance improvements
 * Taku Shimizu -- epub3 builder
-* Antonio Valentino -- qthelp builder
+* Antonio Valentino -- qthelp builder, docstring inheritance
 * Filip Vavera -- napoleon todo directive
 * Pauli Virtanen -- autodoc improvements, autosummary extension
+* Eric N. Vander Weele -- autodoc improvements
 * Stefan van der Walt -- autosummary extension
 * Thomas Waldmann -- apidoc module fixes
 * John Waltman -- Texinfo builder
 * Barry Warsaw -- setup command improvements
 * Sebastian Wiesner -- image handling, distutils support
 * Michael Wilson -- Intersphinx HTTP basic auth support
+* Matthew Woodcraft -- text output improvements
 * Joel Wurtz -- cellspanning support in LaTeX
 * Hong Xu -- svg support in imgmath extension and various bug fixes
 * Stephen Finucane -- setup command improvements and documentation
+* Daniel Pizetta -- inheritance diagram improvements
+* KINEBUCHI Tomohiko -- typing Sphinx as well as docutils
 
 Many thanks for all contributions!
 

CONTRIBUTING.rst

@@ -33,10 +33,10 @@ Bug Reports and Feature Requests
 
 If you have encountered a problem with Sphinx or have an idea for a new
 feature, please submit it to the `issue tracker`_ on GitHub or discuss it
-on the sphinx-dev mailing list.
+on the `sphinx-dev`_ mailing list.
 
 For bug reports, please include the output produced during the build process
-and also the log file Sphinx creates after it encounters an un-handled
+and also the log file Sphinx creates after it encounters an unhandled
 exception.  The location of this file should be shown towards the end of the
 error message.
 
@@ -45,6 +45,7 @@ issue.  If possible, try to create a minimal project that produces the error
 and post that instead.
 
 .. _`issue tracker`: https://github.com/sphinx-doc/sphinx/issues
+.. _`sphinx-dev`: mailto:sphinx-dev@googlegroups.com
 
 
 Contributing to Sphinx
@@ -58,10 +59,10 @@ of the core developers before it is merged into the main repository.
 #. Check for open issues or open a fresh issue to start a discussion around a
    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.
+   free to email the *sphinx-dev* mailing list.
 #. Fork `the repository`_ on GitHub to start making your changes to the
-   **master** branch for next major version, or **stable** branch for next
+   ``master`` branch for next MAJOR version, or ``X.Y`` branch for next
-   minor version.
+   MINOR version (see `Branch Model`_).
 #. Write a test which shows that the bug was fixed or that the feature works
    as expected.
 #. Send a pull request and bug the maintainer until it gets merged and
@@ -90,18 +91,28 @@ These are the basic steps needed to start developing on Sphinx.
 
 #. Checkout the appropriate branch.
 
-   For changes that should be included in the next minor release (namely bug
+   Sphinx adopts Semantic Versioning 2.0.0 (refs: https://semver.org/ ).
-   fixes), use the ``stable`` branch. ::
 
-       git checkout stable
+   For changes that preserves backwards-compatibility of API and features,
+   they should be included in the next MINOR release, use the ``X.Y`` branch.
+   ::
 
-   For new features or other substantial changes that should wait until the
+       git checkout X.Y
-   next major release, use the ``master`` branch.
 
-#. Optional: setup a virtual environment. ::
+   For incompatible or other substantial changes that should wait until the
+   next MAJOR release, use the ``master`` branch.
 
-       virtualenv ~/sphinxenv
+   For urgent release, a new PATCH branch must be branched from the newest
-       . ~/sphinxenv/bin/activate
+   release tag (see `Branch Model`_ for detail).
+
+#. Setup a virtual environment.
+
+   This is not necessary for unit testing, thanks to ``tox``, but it is
+   necessary if you wish to run ``sphinx-build`` locally or run unit tests
+   without the help of ``tox``. ::
+
+       virtualenv ~/.venv
+       . ~/.venv/bin/activate
        pip install -e .
 
 #. Create a new working branch.  Choose any name you like. ::
@@ -112,40 +123,59 @@ These are the basic steps needed to start developing on Sphinx.
 
    For tips on working with the code, see the `Coding Guide`_.
 
-#. Test, test, test.  Possible steps:
+#. Test, test, test.
 
-   * Run the unit tests::
+   Testing is best done through ``tox``, which provides a number of targets and
+   allows testing against multiple different Python environments:
 
-       pip install -r test-reqs.txt
+   * To list all possible targets::
-       make test
 
-   * Again, it's useful to turn on deprecation warnings on so they're shown in
+         tox -av
-     the test output::
 
-       PYTHONWARNINGS=all make test
+   * To run unit tests for a specific Python version, such as 3.6::
 
-   * Build the documentation and check the output for different builders::
+         tox -e py36
 
-       cd doc
+   * To run unit tests for a specific Python version and turn on deprecation
-       make clean html latexpdf
+     warnings on so they're shown in the test output::
 
-   * Run code style checks and type checks (type checks require mypy)::
+         PYTHONWARNINGS=all tox -e py36
 
-       make style-check
+   * To run code style and type checks::
-       make type-check
 
-   * Run the unit tests under different Python environments using
+         tox -e mypy
-     :program:`tox`::
+         tox -e flake8
 
-       pip install tox
+   * Arguments to ``pytest`` can be passed via ``tox``, e.g. in order to run a
-       tox -v
+     particular test::
 
-   * Add a new unit test in the ``tests`` directory if you can.
+       tox -e py36 tests/test_module.py::test_new_feature
+
+   * To build the documentation::
+
+         tox -e docs
+
+   * To build the documentation in multiple formats::
+
+         tox -e docs -- -b html,latexpdf
+
+   * To run JavaScript tests with `Karma <https://karma-runner.github.io>`_,
+     execute the following commands (requires `Node.js <https://nodejs.org>`_)::
+
+      npm install
+      npm run test
+
+   You can also test by installing dependencies in your local environment. ::
+
+       pip install .[test]
+
+   New unit tests should be included in the ``tests`` directory where
+   necessary:
 
    * For bug fixes, first add a test that fails without your changes and passes
      after they are applied.
 
-   * Tests that need a sphinx-build run should be integrated in one of the
+   * Tests that need a ``sphinx-build`` run should be integrated in one of the
      existing test modules if possible.  New tests that to ``@with_app`` and
      then ``build_all`` for a few assertions are not good since *the test suite
      should not take more than a minute to run*.
@@ -169,7 +199,7 @@ These are the basic steps needed to start developing on Sphinx.
        git push origin feature-xyz
 
 #. Submit a pull request from your branch to the respective branch (``master``
-   or ``stable``) on ``sphinx-doc/sphinx`` using the GitHub interface.
+   or ``X.Y``).
 
 #. Wait for a core developer to review your changes.
 
@@ -247,10 +277,7 @@ Coding Guide
   generated output.
 
 * When adding a new configuration variable, be sure to document it and update
-  :file:`sphinx/quickstart.py` if it's important enough.
+  :file:`sphinx/cmd/quickstart.py` if it's important enough.
-
-* Use the included :program:`utils/check_sources.py` script to check for
-  common formatting issues (trailing whitespace, lengthy lines, etc).
 
 * Add appropriate unit tests.
 
@@ -262,7 +289,7 @@ Debugging Tips
   code by running the command ``make clean`` or using the
   :option:`sphinx-build -E` option.
 
-* Use the :option:`sphinx-build -P` option to run Pdb on exceptions.
+* Use the :option:`sphinx-build -P` option to run ``pdb`` on exceptions.
 
 * Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable
   representation of the document structure.
@@ -283,8 +310,40 @@ Debugging Tips
   in `this repository <https://github.com/shibukawa/snowball-stemmer.jsx>`_.
   You can get the resulting JavaScript files using the following command::
 
-     $ npm install
+     npm install
-     $ node_modules/.bin/grunt build # -> dest/*.global.js
+     node_modules/.bin/grunt build # -> dest/*.global.js
+
+
+Branch Model
+------------
+
+Sphinx project uses following branches for developing that conforms to Semantic
+Versioning 2.0.0 (refs: https://semver.org/ ).
+
+``master``
+    Development for MAJOR version.
+    All changes including incompatible behaviors and public API updates are
+    allowed.
+
+``X.Y``
+    Where ``X.Y`` is the ``MAJOR.MINOR`` release.  Used to maintain current
+    MINOR release. All changes are allowed if the change preserves
+    backwards-compatibility of API and features.
+
+    Only the most recent ``MAJOR.MINOR`` branch is currently retained. When a
+    new MAJOR version is released, the old ``MAJOR.MINOR`` branch will be
+    deleted and replaced by an equivalent tag.
+
+``X.Y.Z``
+    Where ``X.Y.Z`` is the ``MAJOR.MINOR.PATCH`` release.  Only
+    backwards-compatible bug fixes are allowed. In Sphinx project, PATCH
+    version is used for urgent bug fix.
+
+    ``MAJOR.MINOR.PATCH`` branch will be branched from the ``v`` prefixed
+    release tag (ex. make 2.3.1 that branched from v2.3.0) when a urgent
+    release is needed. When new PATCH version is released, the branch will be
+    deleted and replaced by an equivalent tag (ex. v2.3.1).
+
 
 Deprecating a feature
 ---------------------
@@ -299,37 +358,39 @@ There are a couple reasons that code in Sphinx might be deprecated:
   no longer needs to support the older version of Python that doesn't include
   the library, the library will be deprecated in Sphinx.
 
-As the :ref:`deprecation-policy` describes,
+As the :ref:`deprecation-policy` describes, the first release of Sphinx that
-the first release of Sphinx that deprecates a feature (``A.B``) should raise a
+deprecates a feature (``A.B``) should raise a ``RemovedInSphinxXXWarning``
-``RemovedInSphinxXXWarning`` (where XX is the Sphinx version where the feature
+(where ``XX`` is the Sphinx version where the feature will be removed) when the
-will be removed) when the deprecated feature is invoked. Assuming we have good
+deprecated feature is invoked. Assuming we have good test coverage, these
-test coverage, these warnings are converted to errors when running the test
+warnings are converted to errors when running the test suite with warnings
-suite with warnings enabled: ``python -Wall tests/run.py``. Thus, when adding
+enabled::
-a ``RemovedInSphinxXXWarning`` you need to eliminate or silence any warnings
+
-generated when running the tests.
+    pytest -Wall
+
+Thus, when adding a ``RemovedInSphinxXXWarning`` you need to eliminate or
+silence any warnings generated when running the tests.
 
 .. _deprecation-policy:
 
 Deprecation policy
 ------------------
 
-A feature release may deprecate certain features from previous releases. If a
+MAJOR and MINOR releases may deprecate certain features from previous
-feature is deprecated in feature release 1.A, it will continue to work in all
+releases. If a feature is deprecated in a release A.x, it will continue to
-1.A.x versions (for all versions of x) but raise warnings. Deprecated features
+work in all A.x.x versions (for all versions of x). It will continue to work
-will be removed in the first 1.B release, or 1.B.1 for features deprecated in
+in all B.x.x versions but raise deprecation warnings. Deprecated features
-the last 1.A.x feature release to ensure deprecations are done over at least 2
+will be removed at the C.0.0. It means the deprecated feature will work during
-feature releases.
+2 MAJOR releases at least.
 
 So, for example, if we decided to start the deprecation of a function in
-Sphinx 1.4:
+Sphinx 2.x:
 
-* Sphinx 1.4.x will contain a backwards-compatible replica of the function
+* Sphinx 2.x will contain a backwards-compatible replica of the function
-  which will raise a ``RemovedInSphinx16Warning``.
+  which will raise a ``RemovedInSphinx40Warning``.
 
-* Sphinx 1.5 (the version that follows 1.4) will still contain the
+* Sphinx 3.x will still contain the backwards-compatible replica.
-  backwards-compatible replica.
 
-* Sphinx 1.6 will remove the feature outright.
+* Sphinx 4.0 will remove the feature outright.
 
 The warnings are displayed by default. You can turn off display of these
 warnings with:
@@ -362,3 +423,6 @@ and other ``test_*.py`` files under ``tests`` directory.
 
 .. versionadded:: 1.6
    ``sphinx.testing`` as a experimental.
+
+.. versionadded:: 1.8
+   Sphinx also runs JavaScript tests.

EXAMPLES

@@ -12,338 +12,398 @@ interesting examples.
 Documentation using the alabaster theme
 ---------------------------------------
 
-* Alabaster: https://alabaster.readthedocs.io/
+* `Alabaster <https://alabaster.readthedocs.io/>`__
-* Blinker: https://pythonhosted.org/blinker/
+* `Blinker <https://pythonhosted.org/blinker/>`__
-* Calibre: https://manual.calibre-ebook.com/
+* `Calibre <https://manual.calibre-ebook.com/>`__
-* Click: http://click.pocoo.org/ (customized)
+* `Click <http://click.pocoo.org/>`__ (customized)
-* coala: https://docs.coala.io/ (customized)
+* `coala <https://docs.coala.io/>`__ (customized)
-* CodePy: https://documen.tician.de/codepy/
+* `CodePy <https://documen.tician.de/codepy/>`__
-* Fabric: http://docs.fabfile.org/
+* `Fabric <https://docs.fabfile.org/>`__
-* Fityk: http://fityk.nieto.pl/
+* `Fityk <https://fityk.nieto.pl/>`__
-* Flask: http://flask.pocoo.org/docs/
+* `Flask <http://flask.pocoo.org/docs/>`__
-* Flask-OpenID: https://pythonhosted.org/Flask-OpenID/
+* `Flask-OpenID <https://pythonhosted.org/Flask-OpenID/>`__
-* Invoke: http://docs.pyinvoke.org/
+* `Invoke <https://docs.pyinvoke.org/>`__
-* Jinja: http://jinja.pocoo.org/docs/
+* `Jinja <http://jinja.pocoo.org/docs/>`__
-* Lino: http://www.lino-framework.org/ (customized)
+* `Lino <http://www.lino-framework.org/>`__ (customized)
-* MDAnalysis: http://www.mdanalysis.org/docs/ (customized)
+* `marbl <https://getmarbl.readthedocs.io/>`__
-* MeshPy: https://documen.tician.de/meshpy/
+* `MDAnalysis <https://www.mdanalysis.org/docs/>`__ (customized)
-* PyCUDA: https://documen.tician.de/pycuda/
+* `MeshPy <https://documen.tician.de/meshpy/>`__
-* PyOpenCL: https://documen.tician.de/pyopencl/
+* `Molecule <https://molecule.readthedocs.io/>`__
-* PyLangAcq: http://pylangacq.org/
+* `PyCUDA <https://documen.tician.de/pycuda/>`__
-* pytest: https://docs.pytest.org/ (customized)
+* `PyOpenCL <https://documen.tician.de/pyopencl/>`__
-* python-apt: https://apt.alioth.debian.org/python-apt-doc/
+* `PyLangAcq <http://pylangacq.org/>`__
-* PyVisfile: https://documen.tician.de/pyvisfile/
+* `pytest <https://docs.pytest.org/>`__ (customized)
-* Tablib: http://docs.python-tablib.org/
+* `python-apt <https://apt.alioth.debian.org/python-apt-doc/>`__
-* Werkzeug: http://werkzeug.pocoo.org/docs/ (customized)
+* `PyVisfile <https://documen.tician.de/pyvisfile/>`__
+* `Requests <http://www.python-requests.org/>`__
+* `searx <https://asciimoo.github.io/searx/>`__
+* `Spyder <https://docs.spyder-ide.org/>`__ (customized)
+* `Tablib <http://docs.python-tablib.org/>`__
+* `urllib3 <https://urllib3.readthedocs.io/>`__ (customized)
+* `Werkzeug <http://werkzeug.pocoo.org/docs/>`__ (customized)
 
 Documentation using the classic theme
 -------------------------------------
 
-* Advanced Generic Widgets: http://xoomer.virgilio.it/infinity77/AGW_Docs/ (customized)
+* `Advanced Generic Widgets <http://xoomer.virgilio.it/infinity77/AGW_Docs/>`__ (customized)
-* Apache CouchDB: http://docs.couchdb.org/ (customized)
+* `Apache CouchDB <http://docs.couchdb.org/>`__ (customized)
-* APSW: https://rogerbinns.github.io/apsw/
+* `APSW <https://rogerbinns.github.io/apsw/>`__
-* Arb: http://arblib.org/
+* `Arb <http://arblib.org/>`__
-* Bazaar: http://doc.bazaar.canonical.com/ (customized)
+* `Bazaar <http://doc.bazaar.canonical.com/>`__ (customized)
-* Blender: https://docs.blender.org/api/current/
+* `Beautiful Soup <https://www.crummy.com/software/BeautifulSoup/bs4/doc/>`__
-* Buildbot: https://docs.buildbot.net/latest/
+* `Blender <https://docs.blender.org/api/current/>`__
-* CMake: https://cmake.org/documentation/ (customized)
+* `Bugzilla <https://bugzilla.readthedocs.io/>`__
-* Chaco: http://docs.enthought.com/chaco/ (customized)
+* `Buildbot <https://docs.buildbot.net/latest/>`__
-* Cormoran: http://cormoran.nhopkg.org/docs/
+* `CMake <https://cmake.org/documentation/>`__ (customized)
-* DEAP: https://deap.readthedocs.io/ (customized)
+* `Chaco <https://docs.enthought.com/chaco/>`__ (customized)
-* Director: https://pythonhosted.org/director/
+* `CORE <https://downloads.pf.itd.nrl.navy.mil/docs/core/core-html/>`__
-* EZ-Draw: https://pageperso.lif.univ-mrs.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html (customized)
+* `CORE Python modules <https://downloads.pf.itd.nrl.navy.mil/docs/core/core-python-html/>`__
-* F2py: http://f2py.sourceforge.net/docs/
+* `Cormoran <http://cormoran.nhopkg.org/docs/>`__
-* Generic Mapping Tools (GMT): http://gmt.soest.hawaii.edu/doc/latest/ (customized)
+* `DEAP <https://deap.readthedocs.io/>`__ (customized)
-* Genomedata: https://noble.gs.washington.edu/proj/genomedata/doc/1.3.3/
+* `Director <https://pythonhosted.org/director/>`__
-* GetFEM++: http://getfem.org/ (customized)
+* `EZ-Draw <https://pageperso.lif.univ-mrs.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html>`__ (customized)
-* Glasgow Haskell Compiler: https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/ (customized)
+* `F2py <http://f2py.sourceforge.net/docs/>`__
-* Grok: http://grok.zope.org/doc/current/ (customized)
+* `Generic Mapping Tools (GMT) <https://gmt.soest.hawaii.edu/doc/latest/>`__ (customized)
-* GROMACS: http://manual.gromacs.org/documentation/
+* `Genomedata <https://noble.gs.washington.edu/proj/genomedata/doc/1.3.3/>`__
-* GSL Shell: http://www.nongnu.org/gsl-shell/
+* `GetFEM++ <http://getfem.org/>`__ (customized)
-* Hands-on Python Tutorial: http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
+* `Glasgow Haskell Compiler <https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/>`__ (customized)
-* Kaa: http://api.freevo.org/kaa-base/ (customized)
+* `Grok <http://grok.zope.org/doc/current/>`__ (customized)
-* Leo: http://leoeditor.com/
+* `GROMACS <http://manual.gromacs.org/documentation/>`__
-* LEPL: http://www.acooke.org/lepl/ (customized)
+* `GSL Shell <https://www.nongnu.org/gsl-shell/>`__
-* Mayavi: http://docs.enthought.com/mayavi/mayavi/ (customized)
+* `Hands-on Python Tutorial <https://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/>`__
-* mpmath: http://mpmath.org/doc/current/
+* `Kaa <https://api.freevo.org/kaa-base/>`__ (customized)
-* OpenCV: http://docs.opencv.org/ (customized)
+* `Leo <https://leoeditor.com/>`__
-* OpenEXR: http://excamera.com/articles/26/doc/index.html
+* `LEPL <http://www.acooke.org/lepl/>`__ (customized)
-* OpenGDA: http://www.opengda.org/gdadoc/html/
+* `Mayavi <https://docs.enthought.com/mayavi/mayavi/>`__ (customized)
-* Peach^3: https://peach3.nl/doc/latest/userdoc/ (customized)
+* `MediaGoblin <https://mediagoblin.readthedocs.io/>`__ (customized)
-* Plone: https://docs.plone.org/ (customized)
+* `mpmath <http://mpmath.org/doc/current/>`__
-* PyEMD: https://pyemd.readthedocs.io/
+* `OpenCV <https://docs.opencv.org/>`__ (customized)
-* Pyevolve: http://pyevolve.sourceforge.net/
+* `OpenEXR <http://excamera.com/articles/26/doc/index.html>`__
-* Pygame: https://www.pygame.org/docs/ (customized)
+* `OpenGDA <http://www.opengda.org/gdadoc/html/>`__
-* PyMQI: https://pythonhosted.org/pymqi/
+* `Peach^3 <https://peach3.nl/doc/latest/userdoc/>`__ (customized)
-* Python 2: https://docs.python.org/2/
+* `Plone <https://docs.plone.org/>`__ (customized)
-* Python 3: https://docs.python.org/3/ (customized)
+* `PyEMD <https://pyemd.readthedocs.io/>`__
-* Python Packaging Authority: https://www.pypa.io/ (customized)
+* `Pyevolve <http://pyevolve.sourceforge.net/>`__
-* Ring programming language: http://ring-lang.sourceforge.net/doc/ (customized)
+* `Pygame <https://www.pygame.org/docs/>`__ (customized)
-* SageMath: https://doc.sagemath.org/ (customized)
+* `PyMQI <https://pythonhosted.org/pymqi/>`__
-* Segway: http://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html
+* `PyQt4 <http://pyqt.sourceforge.net/Docs/PyQt4/>`__ (customized)
-* simuPOP: http://simupop.sourceforge.net/manual_release/build/userGuide.html (customized)
+* `PyQt5 <http://pyqt.sourceforge.net/Docs/PyQt5/>`__ (customized)
-* Sprox: http://sprox.org/ (customized)
+* `Python 2 <https://docs.python.org/2/>`__
-* SymPy: http://docs.sympy.org/
+* `Python 3 <https://docs.python.org/3/>`__ (customized)
-* TurboGears: https://turbogears.readthedocs.org/ (customized)
+* `Python Packaging Authority <https://www.pypa.io/>`__ (customized)
-* tvtk: http://docs.enthought.com/mayavi/tvtk/
+* `Ring programming language <http://ring-lang.sourceforge.net/doc/>`__ (customized)
-* Varnish: https://www.varnish-cache.org/docs/ (customized, alabaster for index)
+* `SageMath <https://doc.sagemath.org/>`__ (customized)
-* Waf: https://waf.io/apidocs/
+* `Segway <https://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html>`__
-* wxPython Phoenix: https://wxpython.org/Phoenix/docs/html/main.html (customized)
+* `simuPOP <http://simupop.sourceforge.net/manual_release/build/userGuide.html>`__ (customized)
-* z3c: http://www.ibiblio.org/paulcarduner/z3ctutorial/
+* `Sprox <http://sprox.org/>`__ (customized)
-* zc.async: https://pythonhosted.org/zc.async/ (customized)
+* `SymPy <https://docs.sympy.org/>`__
-* Zope: https://docs.zope.org/zope2/ (customized)
+* `TurboGears <https://turbogears.readthedocs.io/>`__ (customized)
+* `tvtk <https://docs.enthought.com/mayavi/tvtk/>`__
+* `Varnish <https://www.varnish-cache.org/docs/>`__ (customized, alabaster for index)
+* `Waf <https://waf.io/apidocs/>`__
+* `wxPython Phoenix <https://wxpython.org/Phoenix/docs/html/main.html>`__ (customized)
+* `Yum <http://yum.baseurl.org/api/yum/>`__
+* `z3c <https://www.ibiblio.org/paulcarduner/z3ctutorial/>`__
+* `zc.async <https://pythonhosted.org/zc.async/>`__ (customized)
+* `Zope <https://docs.zope.org/zope2/>`__ (customized)
 
 Documentation using the sphinxdoc theme
 ---------------------------------------
 
-* cartopy: http://scitools.org.uk/cartopy/docs/latest/
+* `cartopy <https://scitools.org.uk/cartopy/docs/latest/>`__
-* Matplotlib: https://matplotlib.org/
+* `Jython <http://www.jython.org/docs/>`__
-* MDAnalysis Tutorial: http://www.mdanalysis.org/MDAnalysisTutorial/
+* `Matplotlib <https://matplotlib.org/>`__
-* NetworkX: https://networkx.github.io/
+* `MDAnalysis Tutorial <https://www.mdanalysis.org/MDAnalysisTutorial/>`__
-* PyCantonese: http://pycantonese.org/
+* `NetworkX <https://networkx.github.io/>`__
-* Pyre: http://docs.danse.us/pyre/sphinx/
+* `PyCantonese <http://pycantonese.org/>`__
-* pySPACE: https://pyspace.github.io/pyspace/
+* `Pyre <http://docs.danse.us/pyre/sphinx/>`__
-* Pysparse: http://pysparse.sourceforge.net/
+* `pySPACE <https://pyspace.github.io/pyspace/>`__
-* PyTango:
+* `Pysparse <http://pysparse.sourceforge.net/>`__
-  http://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango/latest/
+* `PyTango <https://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango/latest/>`__
-* Python Wild Magic: https://vmlaker.github.io/pythonwildmagic/ (customized)
+* `Python Wild Magic <https://vmlaker.github.io/pythonwildmagic/>`__ (customized)
-* Reteisi: http://www.reteisi.org/contents.html (customized)
+* `Reteisi <http://www.reteisi.org/contents.html>`__ (customized)
-* Sqlkit: http://sqlkit.argolinux.org/ (customized)
+* `Sqlkit <http://sqlkit.argolinux.org/>`__ (customized)
-* Turbulenz: http://docs.turbulenz.com/
+* `Turbulenz <http://docs.turbulenz.com/>`__
 
 Documentation using the nature theme
 ------------------------------------
 
-* Alembic: http://alembic.zzzcomputing.com/
+* `Alembic <http://alembic.zzzcomputing.com/>`__
-* Cython: http://docs.cython.org/
+* `Cython <http://docs.cython.org/>`__
-* jsFiddle: http://doc.jsfiddle.net/
+* `easybuild <https://easybuild.readthedocs.io/>`__
-* libLAS: https://www.liblas.org/ (customized)
+* `jsFiddle <http://doc.jsfiddle.net/>`__
-* MapServer: http://mapserver.org/ (customized)
+* `libLAS <https://www.liblas.org/>`__ (customized)
-* Setuptools: https://setuptools.readthedocs.io/
+* `Lmod <https://lmod.readthedocs.io/>`__
-* Spring Python: https://docs.spring.io/spring-python/1.2.x/sphinx/html/
+* `MapServer <https://mapserver.org/>`__ (customized)
-* Sylli: http://sylli.sourceforge.net/
+* `Pandas <https://pandas.pydata.org/pandas-docs/stable/>`__
+* `pyglet <https://pyglet.readthedocs.io/>`__ (customized)
+* `Setuptools <https://setuptools.readthedocs.io/>`__
+* `Spring Python <https://docs.spring.io/spring-python/1.2.x/sphinx/html/>`__
+* `StatsModels <https://www.statsmodels.org/>`__ (customized)
+* `Sylli <http://sylli.sourceforge.net/>`__
 
 Documentation using another builtin theme
 -----------------------------------------
 
-* Breathe: https://breathe.readthedocs.io/ (haiku)
+* `Breathe <https://breathe.readthedocs.io/>`__ (haiku)
-* MPipe: https://vmlaker.github.io/mpipe/ (sphinx13)
+* `MPipe <https://vmlaker.github.io/mpipe/>`__ (sphinx13)
-* Programmieren mit PyGTK und Glade (German):
+* `NLTK <https://www.nltk.org/>`__ (agogo)
-  http://www.florian-diesch.de/doc/python-und-glade/online/ (agogo, customized)
+* `Programmieren mit PyGTK und Glade (German) <https://www.florian-diesch.de/doc/python-und-glade/online/>`__ (agogo, customized)
-* PyPubSub: https://pypubsub.readthedocs.io/ (bizstyle)
+* `PyPubSub <https://pypubsub.readthedocs.io/>`__ (bizstyle)
-* Pylons: http://docs.pylonsproject.org/projects/pylons-webframework/ (pyramid)
+* `Pylons <https://docs.pylonsproject.org/projects/pylons-webframework/>`__ (pyramid)
-* Pyramid web framework:
+* `Pyramid web framework <https://docs.pylonsproject.org/projects/pyramid/>`__ (pyramid)
-  https://docs.pylonsproject.org/projects/pyramid/ (pyramid)
+* `Sphinx <http://www.sphinx-doc.org/>`__ (sphinx13) :-)
-* Sphinx: http://www.sphinx-doc.org/ (sphinx13) :-)
+* `Valence <https://docs.valence.desire2learn.com/>`__ (haiku, customized)
-* Valence: http://docs.valence.desire2learn.com/ (haiku, customized)
 
 Documentation using sphinx_rtd_theme
 ------------------------------------
 
-* Annotator: http://docs.annotatorjs.org/
+* `Annotator <http://docs.annotatorjs.org/>`__
-* ANNOVAR: http://annovar.openbioinformatics.org/
+* `Ansible <https://docs.ansible.com/>`__ (customized)
-* Ansible: https://docs.ansible.com/ (customized)
+* `Arcade <http://arcade.academy/>`__
-* ASE: https://wiki.fysik.dtu.dk/ase/
+* `aria2 <https://aria2.github.io/manual/en/html/>`__
-* Autofac: http://docs.autofac.org/
+* `ASE <https://wiki.fysik.dtu.dk/ase/>`__
-* BigchainDB: https://docs.bigchaindb.com/
+* `Autofac <http://docs.autofac.org/>`__
-* Certbot: https://letsencrypt.readthedocs.io/
+* `BigchainDB <https://docs.bigchaindb.com/>`__
-* CherryPy: http://docs.cherrypy.org/
+* `Blocks <https://blocks.readthedocs.io/>`__
-* Chainer: https://docs.chainer.org/
+* `bootstrap-datepicker <https://bootstrap-datepicker.readthedocs.io/>`__
-* CodeIgniter: https://www.codeigniter.com/user_guide/
+* `Certbot <https://letsencrypt.readthedocs.io/>`__
-* Corda: https://docs.corda.net/
+* `Chainer <https://docs.chainer.org/>`__ (customized)
-* Dask: https://dask.pydata.org/
+* `CherryPy <https://docs.cherrypy.org/>`__
-* Dataiku DSS: https://doc.dataiku.com/
+* `cloud-init <https://cloudinit.readthedocs.io/>`__
-* Drush: http://www.drush.org/
+* `CodeIgniter <https://www.codeigniter.com/user_guide/>`__
-* edX: http://docs.edx.org/
+* `Conda <https://conda.io/docs/>`__
-* Electrum: http://docs.electrum.org/
+* `Corda <https://docs.corda.net/>`__
-* Elemental: http://libelemental.org/documentation/dev/
+* `Dask <https://dask.pydata.org/>`__
-* ESWP3: https://eswp3.readthedocs.io/
+* `Databricks <https://docs.databricks.com/>`__ (customized)
-* Ethereum Homestead: http://www.ethdocs.org/
+* `Dataiku DSS <https://doc.dataiku.com/>`__
-* Flake8: http://flake8.pycqa.org/
+* `DNF <https://dnf.readthedocs.io/>`__
-* GeoNode: http://docs.geonode.org/
+* `edX <https://docs.edx.org/>`__
-* Godot: https://godot.readthedocs.io/
+* `Electrum <http://docs.electrum.org/>`__
-* Graylog: http://docs.graylog.org/
+* `Elemental <http://libelemental.org/documentation/dev/>`__
-* GPAW: https://wiki.fysik.dtu.dk/gpaw/ (customized)
+* `ESWP3 <https://eswp3.readthedocs.io/>`__
-* HDF5 for Python (h5py): http://docs.h5py.org/
+* `Ethereum Homestead <http://www.ethdocs.org/>`__
-* Hyperledger Fabric: https://hyperledger-fabric.readthedocs.io/
+* `Fidimag <https://fidimag.readthedocs.io/>`__
-* Hyperledger Sawtooth: https://intelledger.github.io/
+* `Flake8 <http://flake8.pycqa.org/>`__
-* IdentityServer: http://docs.identityserver.io/
+* `FluidDyn <https://fluiddyn.readthedocs.io/>`__
-* Idris: http://docs.idris-lang.org/
+* `Fluidsim <https://fluidsim.readthedocs.io/>`__
-* javasphinx: https://bronto-javasphinx.readthedocs.io/
+* `GeoNode <http://docs.geonode.org/>`__
-* Kalabox: http://docs.kalabox.io/
+* `Godot <https://godot.readthedocs.io/>`__
-* Linguistica: https://linguistica-uchicago.github.io/lxa5/
+* `Graylog <http://docs.graylog.org/>`__
-* MathJax: https://docs.mathjax.org/
+* `GPAW <https://wiki.fysik.dtu.dk/gpaw/>`__ (customized)
-* MICrobial Community Analysis (micca): http://micca.org/docs/latest/
+* `HDF5 for Python (h5py) <http://docs.h5py.org/>`__
-* MicroPython: https://docs.micropython.org/
+* `Hyperledger Fabric <https://hyperledger-fabric.readthedocs.io/>`__
-* Mink: http://mink.behat.org/
+* `Hyperledger Sawtooth <https://intelledger.github.io/>`__
-* Mockery: http://docs.mockery.io/
+* `IdentityServer <http://docs.identityserver.io/>`__
-* MoinMoin: https://moin-20.readthedocs.io/
+* `Idris <http://docs.idris-lang.org/>`__
-* Mopidy: https://docs.mopidy.com/
+* `javasphinx <https://bronto-javasphinx.readthedocs.io/>`__
-* MyHDL: http://docs.myhdl.org/
+* `Julia <https://julia.readthedocs.io/>`__
-* Nextflow: https://www.nextflow.io/docs/latest/index.html
+* `Jupyter Notebook <https://jupyter-notebook.readthedocs.io/>`__
-* NICOS: https://forge.frm2.tum.de/nicos/doc/nicos-master/ (customized)
+* `Lasagne <https://lasagne.readthedocs.io/>`__
-* Pelican: http://docs.getpelican.com/
+* `latexindent.pl <https://latexindentpl.readthedocs.io/>`__
-* Pillow: https://pillow.readthedocs.io/
+* `Linguistica <https://linguistica-uchicago.github.io/lxa5/>`__
-* pip: https://pip.pypa.io/
+* `Linux kernel <https://www.kernel.org/doc/html/latest/index.html>`__
-* Paver: https://paver.readthedocs.io/
+* `MathJax <https://docs.mathjax.org/>`__
-* peewee: http://docs.peewee-orm.com/
+* `MDTraj <http://mdtraj.org/latest/>`__ (customized)
-* Phinx: http://docs.phinx.org/
+* `MICrobial Community Analysis (micca) <http://micca.org/docs/latest/>`__
-* phpMyAdmin: https://docs.phpmyadmin.net/
+* `MicroPython <https://docs.micropython.org/>`__
-* Pweave: http://mpastell.com/pweave/
+* `Minds <https://www.minds.org/docs/>`__ (customized)
-* python-sqlparse: https://sqlparse.readthedocs.io/
+* `Mink <http://mink.behat.org/>`__
-* Read The Docs: https://docs.readthedocs.io/
+* `Mockery <http://docs.mockery.io/>`__
-* Free your information from their silos (French):
+* `mod_wsgi <https://modwsgi.readthedocs.io/>`__
-  http://redaction-technique.org/ (customized)
+* `MoinMoin <https://moin-20.readthedocs.io/>`__
-* Releases Sphinx extension: https://releases.readthedocs.io/
+* `Mopidy <https://docs.mopidy.com/>`__
-* Qtile: http://docs.qtile.org/
+* `MyHDL <http://docs.myhdl.org/>`__
-* Quex: http://quex.sourceforge.net/doc/html/main.html
+* `Nextflow <https://www.nextflow.io/docs/latest/index.html>`__
-* Satchmo: http://docs.satchmoproject.com/
+* `NICOS <https://forge.frm2.tum.de/nicos/doc/nicos-master/>`__ (customized)
-* Scapy: https://scapy.readthedocs.io/
+* `Pelican <http://docs.getpelican.com/>`__
-* SimPy: http://simpy.readthedocs.io/
+* `picamera <https://picamera.readthedocs.io/>`__
-* SlamData: http://docs.slamdata.com/
+* `Pillow <https://pillow.readthedocs.io/>`__
-* Sonos Controller (SoCo): http://docs.python-soco.com/
+* `pip <https://pip.pypa.io/>`__
-* Sphinx AutoAPI: https://sphinx-autoapi.readthedocs.io/
+* `Paver <https://paver.readthedocs.io/>`__
-* sphinx-argparse: https://sphinx-argparse.readthedocs.io/
+* `peewee <http://docs.peewee-orm.com/>`__
-* Sphinx-Gallery: https://sphinx-gallery.readthedocs.io/ (customized)
+* `Phinx <http://docs.phinx.org/>`__
-* StarUML: http://docs.staruml.io/
+* `phpMyAdmin <https://docs.phpmyadmin.net/>`__
-* Sublime Text Unofficial Documentation: http://docs.sublimetext.info/
+* `PROS <https://pros.cs.purdue.edu/v5/>`__ (customized)
-* SunPy: http://docs.sunpy.org/
+* `Pweave <http://mpastell.com/pweave/>`__
-* Sylius: http://docs.sylius.org/
+* `PyPy <http://doc.pypy.org/>`__
-* Tango Controls: https://tango-controls.readthedocs.io/ (customized)
+* `python-sqlparse <https://sqlparse.readthedocs.io/>`__
-* Topshelf: http://docs.topshelf-project.com/
+* `PyVISA <https://pyvisa.readthedocs.io/>`__
-* ThreatConnect: https://docs.threatconnect.com/
+* `Read The Docs <https://docs.readthedocs.io/>`__
-* Tuleap: https://tuleap.net/doc/en/
+* `Free your information from their silos (French) <http://redaction-technique.org/>`__ (customized)
-* TYPO3: https://docs.typo3.org/ (customized)
+* `Releases Sphinx extension <https://releases.readthedocs.io/>`__
-* Wagtail: http://docs.wagtail.io/
+* `Qtile <http://docs.qtile.org/>`__
-* Web Application Attack and Audit Framework (w3af): http://docs.w3af.org/
+* `Quex <http://quex.sourceforge.net/doc/html/main.html>`__
-* Weblate: https://docs.weblate.org/
+* `Satchmo <http://docs.satchmoproject.com/>`__
+* `Scapy <https://scapy.readthedocs.io/>`__
+* `SimPy <https://simpy.readthedocs.io/>`__
+* `six <https://six.readthedocs.io/>`__
+* `SlamData <https://newdocs.slamdata.com>`__
+* `Solidity <https://solidity.readthedocs.io/>`__
+* `Sonos Controller (SoCo) <http://docs.python-soco.com/>`__
+* `Sphinx AutoAPI <https://sphinx-autoapi.readthedocs.io/>`__
+* `sphinx-argparse <https://sphinx-argparse.readthedocs.io/>`__
+* `Sphinx-Gallery <https://sphinx-gallery.readthedocs.io/>`__ (customized)
+* `SpotBugs <https://spotbugs.readthedocs.io/>`__
+* `StarUML <https://docs.staruml.io/>`__
+* `Sublime Text Unofficial Documentation <http://docs.sublimetext.info/>`__
+* `SunPy <https://docs.sunpy.org/>`__
+* `Sylius <http://docs.sylius.org/>`__
+* `Tango Controls <https://tango-controls.readthedocs.io/>`__ (customized)
+* `Topshelf <http://docs.topshelf-project.com/>`__
+* `Theano <http://www.deeplearning.net/software/theano/>`__
+* `ThreatConnect <https://docs.threatconnect.com/>`__
+* `Tuleap <https://tuleap.net/doc/en/>`__
+* `TYPO3 <https://docs.typo3.org/>`__ (customized)
+* `uWSGI <https://uwsgi-docs.readthedocs.io/>`__
+* `virtualenv <https://virtualenv.readthedocs.io/>`__
+* `Wagtail <https://docs.wagtail.io/>`__
+* `Web Application Attack and Audit Framework (w3af) <http://docs.w3af.org/>`__
+* `Weblate <https://docs.weblate.org/>`__
+* `x265 <https://x265.readthedocs.io/>`__
+* `ZeroNet <https://zeronet.readthedocs.io/>`__
 
 Documentation using sphinx_bootstrap_theme
 ------------------------------------------
 
-* Bootstrap Theme: https://ryan-roemer.github.io/sphinx-bootstrap-theme/
+* `Bootstrap Theme <https://ryan-roemer.github.io/sphinx-bootstrap-theme/>`__
-* C/C++ Software Development with Eclipse: http://eclipsebook.in/
+* `C/C++ Software Development with Eclipse <https://eclipsebook.in/>`__
-* Dataverse: http://guides.dataverse.org/
+* `Dataverse <http://guides.dataverse.org/>`__
-* e-cidadania: http://e-cidadania.readthedocs.org/
+* `e-cidadania <https://e-cidadania.readthedocs.io/>`__
-* Hangfire: http://docs.hangfire.io/
+* `Hangfire <http://docs.hangfire.io/>`__
-* Hedge: https://documen.tician.de/hedge/
+* `Hedge <https://documen.tician.de/hedge/>`__
-* ObsPy: https://docs.obspy.org/
+* `ObsPy <https://docs.obspy.org/>`__
-* Open Dylan: https://opendylan.org/documentation/
+* `Open Dylan <https://opendylan.org/documentation/>`__
-* Pootle: http://docs.translatehouse.org/projects/pootle/
+* `Pootle <http://docs.translatehouse.org/projects/pootle/>`__
-* PyUblas: https://documen.tician.de/pyublas/
+* `PyUblas <https://documen.tician.de/pyublas/>`__
+* `seaborn <https://seaborn.pydata.org/>`__
 
 Documentation using a custom theme or integrated in a website
 -------------------------------------------------------------
 
-* Apache Cassandra: https://cassandra.apache.org/doc/
+* `Apache Cassandra <https://cassandra.apache.org/doc/>`__
-* Astropy: http://docs.astropy.org/
+* `Astropy <http://docs.astropy.org/>`__
-* CakePHP: https://book.cakephp.org/
+* `Bokeh <https://bokeh.pydata.org/>`__
-* CasperJS: http://docs.casperjs.org/
+* `Boto 3 <https://boto3.readthedocs.io/>`__
-* Ceph: http://docs.ceph.com/docs/master/
+* `CakePHP <https://book.cakephp.org/>`__
-* Chef: https://docs.chef.io/
+* `CasperJS <http://docs.casperjs.org/>`__
-* CKAN: http://docs.ckan.org/
+* `Ceph <http://docs.ceph.com/docs/master/>`__
-* Confluent Platform: http://docs.confluent.io/
+* `Chef <https://docs.chef.io/>`__
-* Django: https://docs.djangoproject.com/
+* `CKAN <https://docs.ckan.org/>`__
-* Doctrine: http://docs.doctrine-project.org/
+* `Confluent Platform <https://docs.confluent.io/>`__
-* Enterprise Toolkit for Acrobat products:
+* `Django <https://docs.djangoproject.com/>`__
-  https://www.adobe.com/devnet-docs/acrobatetk/
+* `Doctrine <https://www.doctrine-project.org/>`__
-* Gameduino: http://excamera.com/sphinx/gameduino/
+* `Enterprise Toolkit for Acrobat products <https://www.adobe.com/devnet-docs/acrobatetk/>`__
-* GeoServer: http://docs.geoserver.org/
+* `Gameduino <http://excamera.com/sphinx/gameduino/>`__
-* gevent: http://www.gevent.org/
+* `gensim <https://radimrehurek.com/gensim/>`__
-* Guzzle: http://docs.guzzlephp.org/en/stable/
+* `GeoServer <http://docs.geoserver.org/>`__
-* H2O.ai: http://docs.h2o.ai/
+* `gevent <http://www.gevent.org/>`__
-* Istihza (Turkish Python documentation project): https://belgeler.yazbel.com/python-istihza/
+* `GHC - Glasgow Haskell Compiler <https://downloads.haskell.org/~ghc/master/users-guide/>`__
-* Kombu: http://docs.kombu.me/
+* `Guzzle <http://docs.guzzlephp.org/>`__
-* Lasso: http://lassoguide.com/
+* `H2O.ai <http://docs.h2o.ai/>`__
-* Mako: http://docs.makotemplates.org/
+* `Istihza (Turkish Python documentation project) <https://belgeler.yazbel.com/python-istihza/>`__
-* MirrorBrain: http://mirrorbrain.org/docs/
+* `Kombu <http://docs.kombu.me/>`__
-* MongoDB: https://docs.mongodb.com/
+* `Lasso <http://lassoguide.com/>`__
-* Music21: http://web.mit.edu/music21/doc/
+* `Mako <http://docs.makotemplates.org/>`__
-* nose: https://nose.readthedocs.io/
+* `MirrorBrain <http://mirrorbrain.org/docs/>`__
-* ns-3: https://www.nsnam.org/documentation/
+* `MongoDB <https://docs.mongodb.com/>`__
-* NumPy: https://docs.scipy.org/doc/numpy/reference/
+* `Music21 <https://web.mit.edu/music21/doc/>`__
-* ObjectListView: http://objectlistview.sourceforge.net/python/
+* `MyHDL <http://docs.myhdl.org/>`__
-* OpenERP: https://doc.odoo.com/
+* `nose <https://nose.readthedocs.io/>`__
-* OpenCV: http://docs.opencv.org/
+* `ns-3 <https://www.nsnam.org/documentation/>`__
-* OpenLayers: http://docs.openlayers.org/
+* `NumPy <https://docs.scipy.org/doc/numpy/reference/>`__
-* Open vSwitch: http://docs.openvswitch.org/
+* `ObjectListView <http://objectlistview.sourceforge.net/python/>`__
-* PlatformIO: http://docs.platformio.org/
+* `OpenERP <https://doc.odoo.com/>`__
-* PyEphem: http://rhodesmill.org/pyephem/
+* `OpenCV <https://docs.opencv.org/>`__
-* Pygments: http://pygments.org/docs/
+* `OpenLayers <http://docs.openlayers.org/>`__
-* Plone User Manual (German): https://www.hasecke.com/plone-benutzerhandbuch/4.0/
+* `OpenTURNS <https://openturns.github.io/openturns/master/>`__
-* PSI4: http://www.psicode.org/psi4manual/master/index.html
+* `Open vSwitch <http://docs.openvswitch.org/>`__
-* PyMOTW: https://pymotw.com/2/
+* `PlatformIO <https://docs.platformio.org/>`__
-* python-aspectlib: https://python-aspectlib.readthedocs.io/
+* `PyEphem <http://rhodesmill.org/pyephem/>`__
-  (`sphinx_py3doc_enhanced_theme <https://pypi.python.org/pypi/sphinx_py3doc_enhanced_theme>`__)
+* `Pygments <http://pygments.org/docs/>`__
-* QGIS: https://qgis.org/en/docs/index.html
+* `Plone User Manual (German) <https://www.hasecke.com/plone-benutzerhandbuch/4.0/>`__
-* qooxdoo: http://www.qooxdoo.org/current/
+* `PSI4 <http://www.psicode.org/psi4manual/master/index.html>`__
-* Roundup: http://www.roundup-tracker.org/
+* `PyMOTW <https://pymotw.com/2/>`__
-* SaltStack: https://docs.saltstack.com/
+* `python-aspectlib <https://python-aspectlib.readthedocs.io/>`__ (`sphinx_py3doc_enhanced_theme <https://pypi.org/project/sphinx_py3doc_enhanced_theme/>`__)
-* scikit-learn: http://scikit-learn.org/stable/
+* `QGIS <https://qgis.org/en/docs/index.html>`__
-* SciPy: https://docs.scipy.org/doc/scipy/refrence/
+* `qooxdoo <https://www.qooxdoo.org/current/>`__
-* Scrapy: https://doc.scrapy.org/
+* `Roundup <http://www.roundup-tracker.org/>`__
-* Seaborn: https://seaborn.pydata.org/
+* `SaltStack <https://docs.saltstack.com/>`__
-* Selenium: http://docs.seleniumhq.org/docs/
+* `scikit-learn <http://scikit-learn.org/stable/>`__
-* Self: http://www.selflanguage.org/
+* `SciPy <https://docs.scipy.org/doc/scipy/refrence/>`__
-* Substance D: https://docs.pylonsproject.org/projects/substanced/
+* `Scrapy <https://doc.scrapy.org/>`__
-* Sulu: http://docs.sulu.io/
+* `Seaborn <https://seaborn.pydata.org/>`__
-* SQLAlchemy: https://docs.sqlalchemy.org/
+* `Selenium <https://docs.seleniumhq.org/docs/>`__
-* tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
+* `Self <http://www.selflanguage.org/>`__
-* Ubuntu Packaging Guide: http://packaging.ubuntu.com/html/
+* `Substance D <https://docs.pylonsproject.org/projects/substanced/>`__
-* WebFaction: https://docs.webfaction.com/
+* `Sulu <http://docs.sulu.io/>`__
-* WTForms: https://wtforms.readthedocs.io/
+* `SQLAlchemy <https://docs.sqlalchemy.org/>`__
+* `tinyTiM <http://tinytim.sourceforge.net/docs/2.0/>`__
+* `Twisted <https://twistedmatrix.com/documents/current/>`__
+* `Ubuntu Packaging Guide <http://packaging.ubuntu.com/html/>`__
+* `WebFaction <https://docs.webfaction.com/>`__
+* `WTForms <https://wtforms.readthedocs.io/>`__
 
 Homepages and other non-documentation sites
 -------------------------------------------
 
-* Arizona State University PHY494/PHY598/CHM598 Simulation approaches to Bio-
+* `Arizona State University PHY494/PHY598/CHM598 Simulation approaches to Bio-and Nanophysics <https://becksteinlab.physics.asu.edu/pages/courses/2013/SimBioNano/>`__ (classic)
-  and Nanophysics:
+* `Benoit Boissinot <https://bboissin.appspot.com/>`__ (classic, customized)
-  https://becksteinlab.physics.asu.edu/pages/courses/2013/SimBioNano/ (classic)
+* `Computer Networks, Parallelization, and Simulation Laboratory (CNPSLab) <https://lab.miletic.net/>`__ (sphinx_rtd_theme)
-* Benoit Boissinot: https://bboissin.appspot.com/ (classic, customized)
+* `Deep Learning Tutorials <http://www.deeplearning.net/tutorial/>`__ (sphinxdoc)
-* Computer Networks, Parallelization, and Simulation Laboratory (CNPSLab):
+* `Eric Holscher <http://ericholscher.com/>`__ (alabaster)
-  https://lab.miletic.net/ (sphinx_rtd_theme)
+* `Lei Ma's Statistical Mechanics lecture notes <http://statisticalphysics.openmetric.org/>`__ (sphinx_bootstrap_theme)
-* Loyola University Chicago COMP 339-439 Distributed Systems course:
+* `Loyola University Chicago COMP 339-439 Distributed Systems course <https://books.cs.luc.edu/distributedsystems/>`__ (sphinx_bootstrap_theme)
-  http://books.cs.luc.edu/distributedsystems/ (sphinx_bootstrap_theme)
+* `Pylearn2 <http://www.deeplearning.net/software/pylearn2/>`__ (sphinxdoc, customized)
-* The Wine Cellar Book: https://www.thewinecellarbook.com/doc/en/ (sphinxdoc)
+* `PyXLL <https://www.pyxll.com/>`__ (sphinx_bootstrap_theme, customized)
-* Thomas Cokelaer's Python, Sphinx and reStructuredText tutorials:
+* `SciPy Cookbook <https://scipy-cookbook.readthedocs.io/>`__ (sphinx_rtd_theme)
-  http://thomas-cokelaer.info/tutorials/ (standard)
+* `The Wine Cellar Book <https://www.thewinecellarbook.com/doc/en/>`__ (sphinxdoc)
-* UC Berkeley ME233 Advanced Control Systems II course:
+* `Thomas Cokelaer's Python, Sphinx and reStructuredText tutorials <https://thomas-cokelaer.info/tutorials/>`__ (standard)
-  https://berkeley-me233.github.io/ (sphinxdoc)
+* `UC Berkeley ME233 Advanced Control Systems II course <https://berkeley-me233.github.io/>`__ (sphinxdoc)
+* `Željko Svedružić's Biomolecular Structure and Function Laboratory (BioSFLab) <https://www.svedruziclab.com/>`__ (sphinx_bootstrap_theme)
 
 Books produced using Sphinx
 ---------------------------
 
-* "Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski":
+* `"The Art of Community" (Japanese translation) <https://www.oreilly.co.jp/books/9784873114958/>`__
-  https://literatur.hasecke.com/post/die-wahrheit-des-sehens-dekalog-kieslowski/
+* `"Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski" <https://literatur.hasecke.com/post/die-wahrheit-des-sehens-dekalog-kieslowski/>`__
-* "Expert Python Programming":
+* `"Expert Python Programming" <https://www.packtpub.com/application-development/expert-python-programming>`__
-  https://www.packtpub.com/application-development/expert-python-programming
+* `"Expert Python Programming" (Japanese translation) <https://www.amazon.co.jp/dp/4048686291/>`__
-* "Expert Python Programming" (Japanese translation):
+* `"Expert Python Programming 2nd Edition" (Japanese translation) <https://www.amazon.co.jp/dp/4048930613/>`__
-  https://www.amazon.co.jp/dp/4048686291/
+* `"The Hitchhiker's Guide to Python" <https://docs.python-guide.org/>`__
-* "LassoGuide": http://www.lassosoft.com/Lasso-Documentation
+* `"LassoGuide" <http://www.lassosoft.com/Lasso-Documentation>`__
-* "Learning Sphinx" (in Japanese):
+* `"Learning Sphinx" (in Japanese) <https://www.oreilly.co.jp/books/9784873116488/>`__
-  https://www.oreilly.co.jp/books/9784873116488/
+* `"Learning System Programming with Go (Japanese)" <https://www.lambdanote.com/products/go>`__
-* "Mercurial: the definitive guide (Second edition)":
+* `"Mercurial: the definitive guide (Second edition)" <https://book.mercurial-scm.org/>`__
-  https://book.mercurial-scm.org/
+* `"Mithril -- The fastest clientside MVC (Japanese)" <https://www.oreilly.co.jp/books/9784873117447/>`__
-* "Pioneers and Prominent Men of Utah": http://pioneers.rstebbing.com/
+* `"Pioneers and Prominent Men of Utah" <http://pioneers.rstebbing.com/>`__
-* "Pomodoro Technique Illustrated" (Japanese translation):
+* `"Pomodoro Technique Illustrated" (Japanese translation) <https://www.amazon.co.jp/dp/4048689525/>`__
-  https://www.amazon.co.jp/dp/4048689525/
+* `"Python Professional Programming" (in Japanese) <http://www.amazon.co.jp/dp/4798032948/>`__
-* "Python Professional Programming" (in Japanese):
+* `"Python Professional Programming 2nd Edition" (in Japanese) <https://www.amazon.co.jp/dp/479804315X/>`__
-  https://www.amazon.co.jp/dp/4798032948/
+* `"Python Professional Programming 3rd Edition" (in Japanese) <https://www.amazon.co.jp/dp/4798053821/>`__
-* "The ``repoze.bfg`` Web Application Framework":
+* `"Real World HTTP -- Learning The Internet and Web Technology via its history and code (Japanese)" <https://www.oreilly.co.jp/books/9784873118048/>`__
-  https://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379
+* `"Redmine Primer 5th Edition (in Japanese)" <https://www.shuwasystem.co.jp/products/7980html/4825.html>`__
-* "Simple and Steady Way of Learning for Software Engineering" (in Japanese):
+* `"The repoze.bfg Web Application Framework" <https://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379>`__
-  https://www.amazon.co.jp/dp/477414259X/
+* `"The Self-Taught Programmer" (Japanese translation) <https://www.amazon.co.jp/dp/4822292274/>`__
-* "Software-Dokumentation mit Sphinx": https://www.amazon.de/dp/1497448689/
+* `"Simple and Steady Way of Learning for Software Engineering" (in Japanese) <https://www.amazon.co.jp/dp/477414259X/>`__
-* "Theoretical Physics Reference": http://www.theoretical-physics.net/
+* `"Software-Dokumentation mit Sphinx" <https://www.amazon.de/dp/1497448689/>`__
-* "The Varnish Book":
+* `"Theoretical Physics Reference" <https://www.theoretical-physics.net/>`__
-  https://info.varnish-software.com/the-varnish-book
+* `"The Varnish Book" <https://info.varnish-software.com/the-varnish-book>`__
 
 Theses produced using Sphinx
 ----------------------------
 
-* "A Web-Based System for Comparative Analysis of OpenStreetMap Data by the Use
+* `"A Web-Based System for Comparative Analysis of OpenStreetMap Data by the Use
-  of CouchDB":
+  of CouchDB" <https://www.yumpu.com/et/document/view/11722645/masterthesis-markusmayr-0542042>`__
-  https://www.yumpu.com/et/document/view/11722645/masterthesis-markusmayr-0542042
+* `"Content Conditioning and Distribution for Dynamic Virtual Worlds" <https://www.cs.princeton.edu/research/techreps/TR-941-12>`__
-* "Content Conditioning and Distribution for Dynamic Virtual Worlds":
+* `"The Sphinx Thesis Resource" <https://jterrace.github.io/sphinxtr/>`__
-  https://www.cs.princeton.edu/research/techreps/TR-941-12
+
-* "The Sphinx Thesis Resource": https://jterrace.github.io/sphinxtr/
+Projects integrating Sphinx functionality
+-----------------------------------------
+
+* `Read the Docs <https://readthedocs.org/>`__, a software-as-a-service documentation hosting platform, uses
+  Sphinx to automatically build documentation updates that are pushed to GitHub.
+
+* `Spyder <https://docs.spyder-ide.org/help.html>`__, the Scientific Python Development Environment, uses Sphinx in its
+  help pane to render rich documentation for functions, classes and methods
+  automatically or on-demand.

LICENSE

@@ -1,7 +1,7 @@
 License for Sphinx
 ==================
 
-Copyright (c) 2007-2017 by the Sphinx team (see AUTHORS file).
+Copyright (c) 2007-2019 by the Sphinx team (see AUTHORS file).
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -31,64 +31,6 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 Licenses for incorporated software
 ==================================
 
-The pgen2 package, included in this distribution under the name
-sphinx.pycode.pgen2, is available in the Python 2.6 distribution under
-the PSF license agreement for Python:
-
-----------------------------------------------------------------------
-Copyright © 2001-2008 Python Software Foundation; All Rights Reserved.
-
-PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
---------------------------------------------
-
-1. This LICENSE AGREEMENT is between the Python Software Foundation
-   ("PSF"), and the Individual or Organization ("Licensee") accessing
-   and otherwise using Python 2.6 software in source or binary form
-   and its associated documentation.
-
-2. Subject to the terms and conditions of this License Agreement, PSF
-   hereby grants Licensee a nonexclusive, royalty-free, world-wide
-   license to reproduce, analyze, test, perform and/or display
-   publicly, prepare derivative works, distribute, and otherwise use
-   Python 2.6 alone or in any derivative version, provided, however,
-   that PSF's License Agreement and PSF's notice of copyright, i.e.,
-   "Copyright © 2001-2008 Python Software Foundation; All Rights
-   Reserved" are retained in Python 2.6 alone or in any derivative
-   version prepared by Licensee.
-
-3. In the event Licensee prepares a derivative work that is based on
-   or incorporates Python 2.6 or any part thereof, and wants to make
-   the derivative work available to others as provided herein, then
-   Licensee hereby agrees to include in any such work a brief summary
-   of the changes made to Python 2.6.
-
-4. PSF is making Python 2.6 available to Licensee on an "AS IS" basis.
-   PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY
-   WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY
-   REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY
-   PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.6 WILL NOT INFRINGE
-   ANY THIRD PARTY RIGHTS.
-
-5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
-   2.6 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS
-   AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON
-   2.6, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY
-   THEREOF.
-
-6. This License Agreement will automatically terminate upon a material
-   breach of its terms and conditions.
-
-7. Nothing in this License Agreement shall be deemed to create any
-   relationship of agency, partnership, or joint venture between PSF
-   and Licensee.  This License Agreement does not grant permission to
-   use PSF trademarks or trade name in a trademark sense to endorse or
-   promote products or services of Licensee, or any third party.
-
-8. By copying, installing or otherwise using Python 2.6, Licensee
-   agrees to be bound by the terms and conditions of this License
-   Agreement.
-----------------------------------------------------------------------
-
 The included smartypants module, included as sphinx.util.smartypants,
 is available under the following license:
 
@@ -162,36 +104,6 @@ smartypants.py license::
     such damage.
 ----------------------------------------------------------------------
 
-The ElementTree package, included in this distribution in
-test/etree13, is available under the following license:
-
-----------------------------------------------------------------------
-The ElementTree toolkit is
-
-Copyright (c) 1999-2007 by Fredrik Lundh
-
-By obtaining, using, and/or copying this software and/or its
-associated documentation, you agree that you have read, understood,
-and will comply with the following terms and conditions:
-
-Permission to use, copy, modify, and distribute this software and its
-associated documentation for any purpose and without fee is hereby
-granted, provided that the above copyright notice appears in all
-copies, and that both that copyright notice and this permission notice
-appear in supporting documentation, and that the name of Secret Labs
-AB or the author not be used in advertising or publicity pertaining to
-distribution of the software without specific, written prior
-permission.
-
-SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO
-THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANT- ABILITY
-AND FITNESS.  IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE
-FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
-OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-----------------------------------------------------------------------
-
 The included JQuery JavaScript library is available under the MIT
 license:
 

MANIFEST.in

@@ -12,20 +12,18 @@ include sphinx-autogen.py
 include sphinx-build.py
 include sphinx-quickstart.py
 include sphinx-apidoc.py
-include test-reqs.txt
 include tox.ini
 include sphinx/locale/.tx/config
 
 recursive-include sphinx/templates *
 recursive-include sphinx/texinputs *
+recursive-include sphinx/texinputs_win *
 recursive-include sphinx/themes *
-recursive-include sphinx/pycode/pgen2 *.c *.pyx
 recursive-include sphinx/locale *.js *.pot *.po *.mo
 recursive-include sphinx/search/non-minified-js *.js
 recursive-include sphinx/ext/autosummary/templates *
 recursive-include tests *
 recursive-include utils *
-include sphinx/pycode/Grammar-py*
 
 recursive-include doc *
 prune doc/_build

Makefile

@@ -1,67 +1,33 @@
-PYTHON ?= python
+PYTHON ?= python3
-
-.PHONY: all style-check type-check clean clean-pyc clean-patchfiles clean-backupfiles \
-        clean-generated pylint reindent test covertest build
-
-DONT_CHECK = -i .ropeproject \
-             -i .tox \
-             -i build \
-             -i dist \
-             -i doc/_build \
-             -i sphinx/pycode/pgen2 \
-             -i sphinx/search/da.py \
-             -i sphinx/search/de.py \
-             -i sphinx/search/en.py \
-             -i sphinx/search/es.py \
-             -i sphinx/search/fi.py \
-             -i sphinx/search/fr.py \
-             -i sphinx/search/hu.py \
-             -i sphinx/search/it.py \
-             -i sphinx/search/ja.py \
-             -i sphinx/search/nl.py \
-             -i sphinx/search/no.py \
-             -i sphinx/search/pt.py \
-             -i sphinx/search/ro.py \
-             -i sphinx/search/ru.py \
-             -i sphinx/search/sv.py \
-             -i sphinx/search/tr.py \
-             -i sphinx/style/jquery.js \
-             -i sphinx/util/smartypants.py \
-             -i tests/build \
-             -i tests/path.py \
-             -i tests/roots/test-directive-code/target.py \
-             -i tests/roots/test-warnings/undecodable.rst \
-             -i tests/test_autodoc_py35.py \
-             -i tests/typing_test_data.py \
-             -i utils/convert.py
 
+.PHONY: all
 all: clean-pyc clean-backupfiles style-check type-check test
 
-style-check:
+.PHONY: clean
-	@PYTHONWARNINGS=all $(PYTHON) utils/check_sources.py $(DONT_CHECK) .
-
-type-check:
-	mypy sphinx/
-
 clean: clean-pyc clean-pycache clean-patchfiles clean-backupfiles clean-generated clean-testfiles clean-buildfiles clean-mypyfiles
 
+.PHONY: clean-pyc
 clean-pyc:
 	find . -name '*.pyc' -exec rm -f {} +
 	find . -name '*.pyo' -exec rm -f {} +
 
+.PHONY: clean-pycache
 clean-pycache:
 	find . -name __pycache__ -exec rm -rf {} +
 
+.PHONY: clean-patchfiles
 clean-patchfiles:
 	find . -name '*.orig' -exec rm -f {} +
 	find . -name '*.rej' -exec rm -f {} +
 
+.PHONY: clean-backupfiles
 clean-backupfiles:
 	find . -name '*~' -exec rm -f {} +
 	find . -name '*.bak' -exec rm -f {} +
 	find . -name '*.swp' -exec rm -f {} +
 	find . -name '*.swo' -exec rm -f {} +
 
+.PHONY: clean-generated
 clean-generated:
 	find . -name '.DS_Store' -exec rm -f {} +
 	rm -rf Sphinx.egg-info/
@@ -70,32 +36,48 @@ clean-generated:
 	rm -f utils/*3.py*
 	rm -f utils/regression_test.js
 
+.PHONY: clean-testfiles
 clean-testfiles:
 	rm -rf tests/.coverage
 	rm -rf tests/build
 	rm -rf .tox/
 	rm -rf .cache/
 
+.PHONY: clean-buildfiles
 clean-buildfiles:
 	rm -rf build
 
+.PHONY: clean-mypyfiles
 clean-mypyfiles:
 	rm -rf .mypy_cache/
 
+.PHONY: style-check
+style-check:
+	@flake8
+
+.PHONY: type-check
+type-check:
+	mypy sphinx
+
+.PHONY: pylint
 pylint:
 	@pylint --rcfile utils/pylintrc sphinx
 
-reindent:
+.PHONY: test
-	@$(PYTHON) utils/reindent.py -r -n .
-
 test:
-	@cd tests; $(PYTHON) run.py --ignore py35 -v $(TEST)
+	@$(PYTHON) -m pytest -v $(TEST)
-
-test-async:
-	@cd tests; $(PYTHON) run.py -v $(TEST)
 
+.PHONY: covertest
 covertest:
-	@cd tests; $(PYTHON) run.py -v --cov=sphinx --junitxml=.junit.xml $(TEST)
+	@$(PYTHON) -m pytest -v --cov=sphinx --junitxml=.junit.xml $(TEST)
 
+.PHONY: build
 build:
 	@$(PYTHON) setup.py build
+
+.PHONY: docs
+docs:
+ifndef target
+	$(info You need to give a provide a target variable, e.g. `make docs target=html`.)
+endif
+	$(MAKE) -C doc $(target)

README.rst

@@ -1,45 +1,115 @@
+========
+ Sphinx
+========
+
 .. image:: https://img.shields.io/pypi/v/sphinx.svg
-   :target: https://pypi.python.org/pypi/Sphinx
+   :target: https://pypi.org/project/Sphinx/
-.. image:: https://readthedocs.org/projects/sphinx/badge/
+   :alt: Package on PyPI
+
+.. image:: https://readthedocs.org/projects/sphinx/badge/?version=master
    :target: http://www.sphinx-doc.org/
    :alt: Documentation Status
+
 .. image:: https://travis-ci.org/sphinx-doc/sphinx.svg?branch=master
    :target: https://travis-ci.org/sphinx-doc/sphinx
+   :alt: Build Status (Travis CI)
 
-=================
+.. image:: https://ci.appveyor.com/api/projects/status/github/sphinx-doc/sphinx?branch=master&svg=true
-README for Sphinx
+   :target: https://ci.appveyor.com/project/sphinxdoc/sphinx
-=================
+   :alt: Build Status (AppVeyor)
 
-This is the Sphinx documentation generator, see http://www.sphinx-doc.org/.
+.. image:: https://circleci.com/gh/sphinx-doc/sphinx.svg?style=shield
+   :target: https://circleci.com/gh/sphinx-doc/sphinx
+   :alt: Build Status (CircleCI)
 
+.. image:: https://codecov.io/gh/sphinx-doc/sphinx/branch/master/graph/badge.svg
+   :target: https://codecov.io/gh/sphinx-doc/sphinx
+   :alt: Code Coverage Status (Codecov)
 
-Installing
+Sphinx is a tool that makes it easy to create intelligent and beautiful
-==========
+documentation for Python projects (or other documents consisting of multiple
+reStructuredText sources), written by Georg Brandl.  It was originally created
+for the new Python documentation, and has excellent facilities for Python
+project documentation, but C/C++ is supported as well, and more languages are
+planned.
 
-Install from PyPI to use stable version::
+Sphinx uses reStructuredText as its markup language, and many of its strengths
+come from the power and straightforwardness of reStructuredText and its parsing
+and translating suite, the Docutils.
+
+Among its features are the following:
+
+* Output formats: HTML (including derivative formats such as HTML Help, Epub
+  and Qt Help), plain text, manual pages and LaTeX or direct PDF output
+  using rst2pdf
+* Extensive cross-references: semantic markup and automatic links
+  for functions, classes, glossary terms and similar pieces of information
+* Hierarchical structure: easy definition of a document tree, with automatic
+  links to siblings, parents and children
+* Automatic indices: general index as well as a module index
+* Code handling: automatic highlighting using the Pygments highlighter
+* Flexible HTML output using the Jinja 2 templating engine
+* Various extensions are available, e.g. for automatic testing of snippets
+  and inclusion of appropriately formatted docstrings
+* Setuptools integration
+
+For more information, refer to the `the documentation`__.
+
+.. __: http://www.sphinx-doc.org/
+
+Installation
+============
+
+Sphinx is published on `PyPI`__ and can be installed from there::
 
    pip install -U sphinx
 
-Install from PyPI to use beta version::
+We also publish beta releases::
 
    pip install -U --pre sphinx
 
-Install from newest dev version in stable branch::
+If you wish to install `Sphinx` for development purposes, refer to `the
+contributors guide`__.
 
-   pip install git+https://github.com/sphinx-doc/sphinx@stable
+__ https://pypi.org/project/Sphinx/
+__ http://www.sphinx-doc.org/en/master/devguide.html
 
-Install from newest dev version in master branch::
+Documentation
+=============
 
-   pip install git+https://github.com/sphinx-doc/sphinx
+Documentation is available from `sphinx-doc.org`__.
 
-Install from cloned source::
+__ http://www.sphinx-doc.org/
 
-   pip install .
+Get in touch
+============
 
-Install from cloned source as editable::
+- Report bugs, suggest features or view the source code `on GitHub`_.
+- For less well defined questions or ideas, use the `mailing list`_.
 
-   pip install -e .
+.. _on GitHub: https://github.com/sphinx-doc/sphinx
+.. _mailing list: https://groups.google.com/forum/#!forum/sphinx-users
 
+Testing
+=======
+
+Continuous testing is provided by `Travis`__ (for unit tests and style checks
+on Linux), `AppVeyor`__ (for unit tests on Windows), and `CircleCI`__ (for
+large processes like TeX compilation).
+
+For information on running tests locally, refer to `the contributors guide`__.
+
+__ https://travis-ci.org/sphinx-doc/sphinx
+__ https://ci.appveyor.com/project/sphinxdoc/sphinx
+__ https://circleci.com/gh/sphinx-doc/sphinx
+__ http://www.sphinx-doc.org/en/master/devguide.html
+
+Contributing
+============
+
+Refer to `the contributors guide`__.
+
+__ http://www.sphinx-doc.org/en/master/devguide.html
 
 Release signatures
 ==================
@@ -48,37 +118,3 @@ Releases are signed with following keys:
 
 * `498D6B9E <https://pgp.mit.edu/pks/lookup?op=vindex&search=0x102C2C17498D6B9E>`_
 * `5EBA0E07 <https://pgp.mit.edu/pks/lookup?op=vindex&search=0x1425F8CE5EBA0E07>`_
-
-Reading the docs
-================
-
-You can read them online at <http://www.sphinx-doc.org/>.
-
-Or, after installing::
-
-   cd doc
-   make html
-
-Then, direct your browser to ``_build/html/index.html``.
-
-Testing
-=======
-
-To run the tests with the interpreter available as ``python``, use::
-
-    make test
-
-If you want to use a different interpreter, e.g. ``python3``, use::
-
-    PYTHON=python3 make test
-
-Continuous testing runs on travis: https://travis-ci.org/sphinx-doc/sphinx
-
-
-Contributing
-============
-
-See `CONTRIBUTING.rst`__
-
-.. __: CONTRIBUTING.rst
-

doc/Makefile

@@ -1,9 +1,10 @@
 # Makefile for Sphinx documentation
 #
+PYTHON ?= python3
 
 # You can set these variables from the command line.
 SPHINXOPTS   =
-SPHINXBUILD  = python ../sphinx-build.py
+SPHINXBUILD  = $(PYTHON) ../sphinx/cmd/build.py
 SPHINXPROJ   = sphinx
 SOURCEDIR    = .
 BUILDDIR     = _build

doc/_static/conf.py.txt

@@ -1,5 +1,3 @@
-# -*- coding: utf-8 -*-
-#
 # test documentation build configuration file, created by
 # sphinx-quickstart on Sun Jun 26 00:00:43 2016.
 #

doc/_templates/index.html

@@ -49,7 +49,7 @@
   <table class="contentstable">
     <tr>
       <td>
-        <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/>
+        <p class="biglink"><a class="biglink" href="{{ pathto("usage/quickstart") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/>
            <span class="linkdescr">{%trans%}overview of basic tasks{%endtrans%}</span></p>
       </td><td>
         {%- if hasdoc('search') %}<p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
@@ -73,11 +73,8 @@
   </table>
 
   <p>{%trans%}
-    You can also download PDF/EPUB versions of the Sphinx documentation:
+    You can also download PDF/EPUB versions of the Sphinx documentation
-    a <a href="http://readthedocs.org/projects/sphinx/downloads/pdf/stable/">PDF version</a> generated from
+    from pop up menu on lower right corner.{%endtrans%}
-    the LaTeX Sphinx produces, and
-    a <a href="http://readthedocs.org/projects/sphinx/downloads/epub/stable/">EPUB version</a>.
-   {%endtrans%}
   </p>
 
   <h2>{%trans%}Examples{%endtrans%}</h2>
@@ -98,7 +95,7 @@
   <p>{%trans%}There is a <a href="http://docs.sphinx-users.jp/">Japanese translation</a>
     of this documentation, thanks to the Japanese Sphinx user group.{%endtrans%}</p>
   <p>{%trans%}A Japanese book about Sphinx has been published by O'Reilly:
-    <a href="http://www.oreilly.co.jp/books/9784873116488/">Sphinxをはじめよう /
+    <a href="https://www.oreilly.co.jp/books/9784873116488/">Sphinxをはじめよう /
       Learning Sphinx</a>.{%endtrans%}</p>
   <!-- <p><img src="{{ pathto("_static/bookcover.png", 1) }}"/></p> -->
 
@@ -106,7 +103,7 @@
   <h2>{%trans%}Hosting{%endtrans%}</h2>
 
   <p>{%trans%}Need a place to host your Sphinx docs?
-    <a href="http://readthedocs.org">readthedocs.org</a> hosts a lot of Sphinx docs
+    <a href="https://readthedocs.org/">readthedocs.org</a> hosts a lot of Sphinx docs
     already, and integrates well with projects' source control.  It also features a
     powerful built-in search that exceeds the possibilities of Sphinx' JavaScript-based
     offline search.{%endtrans%}</p>

doc/_templates/indexsidebar.html

@@ -1,31 +1,23 @@
-<p class="logo">A <a href="http://pocoo.org/">
+<p class="logo">A <a href="https://www.pocoo.org/">
   <img src="{{ pathto("_static/pocoo.png", 1) }}" alt="Pocoo" /></a>
   {%trans%}project{%endtrans%}</p>
 
 <h3>Download</h3>
-{% if version.endswith('+') %}
+<p class="download">{%trans%}Current version: <a href="https://pypi.org/project/Sphinx/" alt="PyPI"><img src="https://img.shields.io/pypi/v/sphinx.svg"></a>{%endtrans%}</p>
-<p>{%trans%}This documentation is for version <b><a href="changes.html">{{ version }}</a></b>, which is
+<p>{%trans%}Install Sphinx with:{%endtrans%}</p>
-  not released yet.{%endtrans%}</p>
-<p>{%trans%}You can use it from the
-  <a href="https://github.com/sphinx-doc/sphinx/">Git repo</a> or look for
-  released versions in the <a href="https://pypi.python.org/pypi/Sphinx">Python
-    Package Index</a>.{%endtrans%}</p>
-{% else %}
-<p>{%trans%}Current version: <b><a href="changes.html">{{ version }}</a></b>{%endtrans%}</p>
-<p>{%trans%}Get Sphinx from the <a href="https://pypi.python.org/pypi/Sphinx">Python Package
-Index</a>, or install it with:{%endtrans%}</p>
 <pre>pip install -U Sphinx</pre>
-{% endif %}
 
 <h3>{%trans%}Questions? Suggestions?{%endtrans%}</h3>
 
-<p>{%trans%}Join the <a href="http://groups.google.com/group/sphinx-users">sphinx-users</a> mailing list on Google Groups:{%endtrans%}</p>
+<p>{%trans%}Join the <a href="https://groups.google.com/group/sphinx-users">sphinx-users</a> mailing list on Google Groups:{%endtrans%}</p>
-<form action="http://groups.google.com/group/sphinx-users/boxsubscribe"
+<div class="subscribeformwrapper">
-      style="padding-left: 0.5em">
+<form action="https://groups.google.com/group/sphinx-users/boxsubscribe"
-  <input type="text" name="email" value="your@email" style="font-size: 90%; width: 120px"
+      class="subscribeform">
-         onfocus="$(this).val('');"/>
+  <input type="text" name="email" value="your@email"
-  <input type="submit" name="sub" value="Subscribe" style="font-size: 90%; width: 70px"/>
+         onfocus="$(this).val('');" />
+  <input type="submit" name="sub" value="Subscribe" />
 </form>
+</div>
 <p>{%trans%}or come to the <tt>#sphinx-doc</tt> channel on FreeNode.{%endtrans%}</p>
 <p>{%trans%}You can also open an issue at the
   <a href="https://github.com/sphinx-doc/sphinx/issues">tracker</a>.{%endtrans%}</p>

doc/_themes/sphinx13/layout.html

@@ -4,7 +4,7 @@
 
     Sphinx layout template for the sphinxdoc theme.
 
-    :copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 #}
 {%- extends "basic/layout.html" %}
@@ -13,8 +13,13 @@
 {% block sidebar1 %}{{ sidebar() }}{% endblock %}
 {% block sidebar2 %}{% endblock %}
 
+{% block linktags %}
+{{ super() }}
+    <link rel="canonical" href="http://www.sphinx-doc.org/en/master/{{ pagename }}{{ file_suffix }}" />
+{% endblock %}
+
 {% block extrahead %}
-    <link href='http://fonts.googleapis.com/css?family=Open+Sans:300,400,700'
+    <link href='https://fonts.googleapis.com/css?family=Open+Sans:300,400,700'
           rel='stylesheet' type='text/css' />
 {{ super() }}
 {%- if not embedded %}
@@ -65,7 +70,7 @@
 <div class="pageheader">
   <ul>
     <li><a href="{{ pathto('index') }}">Home</a></li>
-    <li><a href="{{ pathto('install') }}">Get it</a></li>
+    <li><a href="{{ pathto('usage/installation') }}">Get it</a></li>
     <li><a href="{{ pathto('contents') }}">Docs</a></li>
     <li><a href="{{ pathto('develop') }}">Extend/Develop</a></li>
   </ul>

doc/_themes/sphinx13/static/sphinx13.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- sphinx13 theme.
  *
- * :copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -140,11 +140,41 @@ div.sphinxsidebar .logo img {
     vertical-align: middle;
 }
 
+div.sphinxsidebar .download a img {
+    vertical-align: middle;
+}
+
+div.subscribeformwrapper {
+    display: block;
+    overflow: auto;
+    margin-bottom: 1.2em;
+}
+
 div.sphinxsidebar input {
     border: 1px solid #aaa;
     font-family: 'Open Sans', 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva',
                  'Verdana', sans-serif;
-    font-size: 1em;
+}
+
+div.sphinxsidebar .subscribeform {
+    margin-top: 0;
+}
+
+div.sphinxsidebar .subscribeform input {
+    border: 1px solid #aaa;
+    font-size: 0.9em;
+    float: left;
+    padding: 0.25em 0.5em;
+    box-sizing: border-box;
+}
+
+div.sphinxsidebar .subscribeform input[type="text"] {
+    width: 60%;
+}
+
+div.sphinxsidebar .subscribeform input[type="submit"] {
+    width: 40%;
+    border-left: none;
 }
 
 div.sphinxsidebar h3 {
@@ -276,12 +306,16 @@ cite, code, tt {
     letter-spacing: -0.02em;
 }
 
+table.deprecated code.literal {
+    word-break: break-all;
+}
+
 tt {
     background-color: #f2f2f2;
     border: 1px solid #ddd;
     border-radius: 2px;
     color: #333;
-    padding: 1px;
+    padding: 1px 0.2em;
 }
 
 tt.descname, tt.descclassname, tt.xref {

doc/conf.py

@@ -1,8 +1,7 @@
-# -*- coding: utf-8 -*-
-#
 # Sphinx documentation build configuration file
 
 import re
+
 import sphinx
 
 
@@ -15,7 +14,7 @@ templates_path = ['_templates']
 exclude_patterns = ['_build']
 
 project = 'Sphinx'
-copyright = '2007-2017, Georg Brandl and the Sphinx team'
+copyright = '2007-2019, Georg Brandl and the Sphinx team'
 version = sphinx.__display_version__
 release = version
 show_authors = True
@@ -38,11 +37,12 @@ epub_uid = 'web-site'
 epub_scheme = 'url'
 epub_identifier = epub_publisher
 epub_pre_files = [('index.xhtml', 'Welcome')]
-epub_post_files = [('install.xhtml', 'Installing Sphinx'),
+epub_post_files = [('usage/installation.xhtml', 'Installing Sphinx'),
                    ('develop.xhtml', 'Sphinx development')]
 epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
                       '_static/jquery.js', '_static/searchtools.js',
                       '_static/underscore.js', '_static/basic.css',
+                      '_static/language_data.js',
                       'search.html', '_static/websupport.js']
 epub_fix_images = False
 epub_max_image_width = 0
@@ -55,8 +55,21 @@ latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
                     'Georg Brandl', 'manual', 1)]
 latex_logo = '_static/sphinx.png'
 latex_elements = {
-    'fontpkg': '\\usepackage{palatino}',
+    'fontenc': r'\usepackage[LGR,X2,T1]{fontenc}',
+    'fontpkg': r'''
+\usepackage[sc]{mathpazo}
+\usepackage[scaled]{helvet}
+\usepackage{courier}
+\substitutefont{LGR}{\rmdefault}{cmr}
+\substitutefont{LGR}{\sfdefault}{cmss}
+\substitutefont{LGR}{\ttdefault}{cmtt}
+\substitutefont{X2}{\rmdefault}{cmr}
+\substitutefont{X2}{\sfdefault}{cmss}
+\substitutefont{X2}{\ttdefault}{cmtt}
+''',
     'passoptionstopackages': '\\PassOptionsToPackage{svgnames}{xcolor}',
+    'preamble': '\\DeclareUnicodeCharacter{229E}{\\ensuremath{\\boxplus}}',
+    'fvset': '\\fvset{fontsize=auto}',
     # fix missing index entry due to RTD doing only once pdflatex after makeindex
     'printindex': r'''
 \IfFileExists{\jobname.ind}
@@ -65,6 +78,7 @@ latex_elements = {
 ''',
 }
 latex_show_urls = 'footnote'
+latex_use_xindy = True
 
 autodoc_member_order = 'groupwise'
 todo_include_todos = True
@@ -96,7 +110,7 @@ texinfo_documents = [
 
 # We're not using intersphinx right now, but if we did, this would be part of
 # the mapping:
-intersphinx_mapping = {'python': ('https://docs.python.org/2/', None)}
+intersphinx_mapping = {'python': ('https://docs.python.org/3/', None)}
 
 # Sphinx document translation with sphinx gettext feature uses these settings:
 locale_dirs = ['locale/']
@@ -136,3 +150,10 @@ def setup(app):
                          names=['param'], can_collapse=True)
     app.add_object_type('event', 'event', 'pair: %s; event', parse_event,
                         doc_field_types=[fdesc])
+
+    # workaround for RTD
+    from sphinx.util import logging
+    logger = logging.getLogger(__name__)
+    app.info = lambda *args, **kwargs: logger.info(*args, **kwargs)
+    app.warn = lambda *args, **kwargs: logger.warning(*args, **kwargs)
+    app.debug = lambda *args, **kwargs: logger.debug(*args, **kwargs)

doc/contents.rst

@@ -8,22 +8,25 @@ Sphinx documentation contents
    :maxdepth: 2
 
    intro
-   tutorial
+
+   usage/installation
+   usage/quickstart
+   usage/restructuredtext/index
+   usage/markdown
+   usage/configuration
+   usage/builders/index
+   usage/extensions/index
+   usage/theming
+   usage/advanced/intl
+   usage/advanced/setuptools
+   usage/advanced/websupport/index
+
    man/index
-   rest
-   markup/index
-   domains
-   builders
-   config
-   intl
    theming
-   setuptools
    templating
    latex
-   markdown
-   extensions
    extdev/index
-   websupport
+   development/tutorials/index
 
    faq
    glossary
@@ -33,6 +36,7 @@ Sphinx documentation contents
    authors
 
 
+
 Indices and tables
 ==================
 

doc/develop.rst

@@ -12,7 +12,7 @@ Sphinx is a maintained by a group of volunteers.  We value every contribution!
 * The mailing list for development is at `Google Groups
   <https://groups.google.com/forum/#!forum/sphinx-dev>`_.
 * There is also the #sphinx-doc IRC channel on `freenode
-  <http://freenode.net/>`_.
+  <https://freenode.net/>`_.
 
 For more about our development process and methods, see the :doc:`devguide`.
 
@@ -100,46 +100,46 @@ This is the current list of contributed extensions in that repository:
 - zopeext: provide an ``autointerface`` directive for using `Zope interfaces`_
 
 
-See the :ref:`extension tutorial <exttut>` on getting started with writing your
+See the :doc:`extension tutorials <../development/tutorials/index>` on getting started with writing your
 own extensions.
 
 
 .. _aafigure: https://launchpad.net/aafigure
 .. _gnuplot: http://www.gnuplot.info/
-.. _paver: http://paver.github.io/paver/
+.. _paver: https://paver.readthedocs.io/en/latest/
-.. _Sword: http://www.crosswire.org/sword/
+.. _Sword: https://www.crosswire.org/sword/
 .. _Lilypond: http://lilypond.org/
 .. _sdedit: http://sdedit.sourceforge.net/
-.. _Trac: http://trac.edgewall.org
+.. _Trac: https://trac.edgewall.org/
-.. _TracLinks: http://trac.edgewall.org/wiki/TracLinks
+.. _TracLinks: https://trac.edgewall.org/wiki/TracLinks
-.. _OmegaT: http://www.omegat.org/
+.. _OmegaT: https://omegat.org/
 .. _PlantUML: http://plantuml.com/
-.. _PyEnchant: http://www.rfk.id.au/software/pyenchant/
+.. _PyEnchant: https://pythonhosted.org/pyenchant/
 .. _sadisplay: https://bitbucket.org/estin/sadisplay/wiki/Home
 .. _blockdiag: http://blockdiag.com/en/
 .. _seqdiag: http://blockdiag.com/en/
 .. _actdiag: http://blockdiag.com/en/
 .. _nwdiag: http://blockdiag.com/en/
-.. _Google Analytics: http://www.google.com/analytics/
+.. _Google Analytics: https://www.google.com/analytics/
 .. _Google Chart: https://developers.google.com/chart/
 .. _Google Maps: https://www.google.com/maps
 .. _Google style: https://google.github.io/styleguide/pyguide.html
 .. _NumPy style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
 .. _hyphenator: https://github.com/mnater/hyphenator
-.. _exceltable: http://pythonhosted.org/sphinxcontrib-exceltable/
+.. _exceltable: https://pythonhosted.org/sphinxcontrib-exceltable/
-.. _YouTube: http://www.youtube.com/
+.. _YouTube: https://www.youtube.com/
-.. _ClearQuest: http://www-03.ibm.com/software/products/en/clearquest
+.. _ClearQuest: https://www.ibm.com/us-en/marketplace/rational-clearquest
-.. _Zope interfaces: http://docs.zope.org/zope.interface/README.html
+.. _Zope interfaces: https://zopeinterface.readthedocs.io/en/latest/README.html
-.. _slideshare: http://www.slideshare.net/
+.. _slideshare: https://www.slideshare.net/
 .. _TikZ/PGF LaTeX package: https://sourceforge.net/projects/pgf/
-.. _MATLAB: http://www.mathworks.com/products/matlab/
+.. _MATLAB: https://www.mathworks.com/products/matlab.html
 .. _swf: https://bitbucket.org/klorenz/sphinxcontrib-swf
 .. _findanything: https://bitbucket.org/klorenz/sphinxcontrib-findanything
 .. _cmakedomain: https://bitbucket.org/klorenz/sphinxcontrib-cmakedomain
-.. _GNU Make: http://www.gnu.org/software/make/
+.. _GNU Make: https://www.gnu.org/software/make/
 .. _makedomain: https://bitbucket.org/klorenz/sphinxcontrib-makedomain
-.. _inlinesyntaxhighlight: http://sphinxcontrib-inlinesyntaxhighlight.readthedocs.org
+.. _inlinesyntaxhighlight: https://sphinxcontrib-inlinesyntaxhighlight.readthedocs.io/
 .. _CMake: https://cmake.org
 .. _domaintools: https://bitbucket.org/klorenz/sphinxcontrib-domaintools
-.. _restbuilder: https://pypi.python.org/pypi/sphinxcontrib-restbuilder
+.. _restbuilder: https://pypi.org/project/sphinxcontrib-restbuilder/
 .. _Lasso: http://www.lassosoft.com/

doc/development/tutorials/helloworld.rst

@@ -0,0 +1,162 @@
+Developing a "Hello world" directive
+====================================
+
+The objective of this tutorial is to create a very basic extension that adds a new
+directive that outputs a paragraph containing `hello world`.
+
+Only basic information is provided in this tutorial. For more information,
+refer to the :doc:`other tutorials <index>` that go into more
+details.
+
+.. warning:: For this extension, you will need some basic understanding of docutils_
+   and Python.
+
+Creating a new extension file
+-----------------------------
+
+Your extension file could be in any folder of your project. In our case,
+let's do the following:
+
+#. Create an :file:`_ext` folder in :file:`source`.
+#. Create a new Python file in the :file:`_ext` folder called
+   :file:`helloworld.py`.
+
+   Here is an example of the folder structure you might obtain:
+
+   .. code-block:: text
+
+         └── source
+             ├── _ext
+             │   └── helloworld.py
+             ├── _static
+             ├── _themes
+             ├── conf.py
+             ├── somefolder
+             ├── somefile.rst
+             └── someotherfile.rst
+
+Writing the extension
+---------------------
+
+Open :file:`helloworld.py` and paste the following code in it:
+
+.. code-block:: python
+
+   from docutils import nodes
+   from docutils.parsers.rst import Directive
+
+
+   class HelloWorld(Directive):
+       def run(self):
+           paragraph_node = nodes.paragraph(text='Hello World!')
+           return [paragraph_node]
+
+
+   def setup(app):
+       app.add_directive("helloworld", HelloWorld)
+
+
+Some essential things are happening in this example, and you will see them
+in all directives:
+
+.. rubric:: Directive declaration
+
+Our new directive is declared in the ``HelloWorld`` class, it extends
+docutils_' ``Directive`` class. All extensions that create directives
+should extend this class.
+
+.. rubric:: ``run`` method
+
+This method is a requirement and it is part of every directive. It contains
+the main logic of the directive and it returns a list of docutils nodes to
+be processed by Sphinx.
+
+.. seealso::
+
+   :doc:`todo`
+
+.. rubric:: docutils nodes
+
+The ``run`` method returns a list of nodes. Nodes are docutils' way of
+representing the content of a document. There are many types of nodes
+available: text, paragraph, reference, table, etc.
+
+.. seealso::
+
+   `The docutils documentation on nodes <docutils nodes>`_
+
+The ``nodes.paragraph`` class creates a new paragraph node. A paragraph
+node typically contains some text that we can set during instantiation using
+the ``text`` parameter.
+
+.. rubric:: ``setup`` function
+
+This function is a requirement. We use it to plug our new directive into
+Sphinx.
+The simplest thing you can do it call the ``app.add_directive`` method.
+
+.. note::
+
+   The first argument is the name of the directive itself as used in an rST file.
+
+   In our case, we would use ``helloworld``:
+
+   .. code-block:: rst
+
+      Some intro text here...
+
+      .. helloworld::
+
+      Some more text here...
+
+
+Updating the conf.py file
+-------------------------
+
+The extension file has to be declared in your :file:`conf.py` file to make
+Sphinx aware of it:
+
+#. Open :file:`conf.py`. It is in the :file:`source` folder by default.
+#. Add ``sys.path.append(os.path.abspath("./_ext"))`` before
+   the ``extensions`` variable declaration (if it exists).
+#. Update or create the ``extensions`` list and add the
+   extension file name to the list:
+
+   .. code-block:: python
+
+      extensions.append('helloworld')
+
+You can now use the extension.
+
+.. admonition:: Example
+
+   .. code-block:: rst
+
+      Some intro text here...
+
+      .. helloworld::
+
+      Some more text here...
+
+   The sample above would generate:
+
+   .. code-block:: text
+
+      Some intro text here...
+
+      Hello World!
+
+      Some more text here...
+
+This is the very basic principle of an extension that creates a new directive.
+
+For a more advanced example, refer to :doc:`todo`.
+
+Further reading
+---------------
+
+You can create your own nodes if needed, refer to the
+:doc:`todo` for more information.
+
+.. _docutils: http://docutils.sourceforge.net/
+.. _`docutils nodes`: http://docutils.sourceforge.net/docs/ref/doctree.html

doc/development/tutorials/index.rst

@@ -0,0 +1,11 @@
+Extension tutorials
+===================
+
+Refer to the following tutorials to get started with extension development.
+
+.. toctree::
+   :caption: Directive tutorials
+   :maxdepth: 1
+
+   helloworld
+   todo

doc/development/tutorials/todo.rst

@@ -1,7 +1,5 @@
-.. _exttut:
+Developing a "TODO" extension
-
+=============================
-Tutorial: Writing a simple extension
-====================================
 
 This section is intended as a walkthrough for the creation of custom extensions.
 It covers the basics of writing and activating an extension, as well as
@@ -12,112 +10,12 @@ include todo entries in the documentation, and to collect these in a central
 place.  (A similar "todo" extension is distributed with Sphinx.)
 
 
-Important objects
------------------
-
-There are several key objects whose API you will use while writing an
-extension.  These are:
-
-**Application**
-   The application object (usually called ``app``) is an instance of
-   :class:`.Sphinx`.  It controls most high-level functionality, such as the
-   setup of extensions, event dispatching and producing output (logging).
-
-   If you have the environment object, the application is available as
-   ``env.app``.
-
-**Environment**
-   The build environment object (usually called ``env``) is an instance of
-   :class:`.BuildEnvironment`.  It is responsible for parsing the source
-   documents, stores all metadata about the document collection and is
-   serialized to disk after each build.
-
-   Its API provides methods to do with access to metadata, resolving references,
-   etc.  It can also be used by extensions to cache information that should
-   persist for incremental rebuilds.
-
-   If you have the application or builder object, the environment is available
-   as ``app.env`` or ``builder.env``.
-
-**Builder**
-   The builder object (usually called ``builder``) is an instance of a specific
-   subclass of :class:`.Builder`.  Each builder class knows how to convert the
-   parsed documents into an output format, or otherwise process them (e.g. check
-   external links).
-
-   If you have the application object, the builder is available as
-   ``app.builder``.
-
-**Config**
-   The config object (usually called ``config``) provides the values of
-   configuration values set in :file:`conf.py` as attributes.  It is an instance
-   of :class:`.Config`.
-
-   The config is available as ``app.config`` or ``env.config``.
-
-
-Build Phases
-------------
-
-One thing that is vital in order to understand extension mechanisms is the way
-in which a Sphinx project is built: this works in several phases.
-
-**Phase 0: Initialization**
-
-   In this phase, almost nothing of interest to us happens.  The source
-   directory is searched for source files, and extensions are initialized.
-   Should a stored build environment exist, it is loaded, otherwise a new one is
-   created.
-
-**Phase 1: Reading**
-
-   In Phase 1, all source files (and on subsequent builds, those that are new or
-   changed) are read and parsed.  This is the phase where directives and roles
-   are encountered by docutils, and the corresponding code is executed.  The
-   output of this phase is a *doctree* for each source file; that is a tree of
-   docutils nodes.  For document elements that aren't fully known until all
-   existing files are read, temporary nodes are created.
-
-   There are nodes provided by docutils, which are documented `in the docutils
-   documentation <http://docutils.sourceforge.net/docs/ref/doctree.html>`__.
-   Additional nodes are provided by Sphinx and :ref:`documented here <nodes>`.
-
-   During reading, the build environment is updated with all meta- and cross
-   reference data of the read documents, such as labels, the names of headings,
-   described Python objects and index entries.  This will later be used to
-   replace the temporary nodes.
-
-   The parsed doctrees are stored on the disk, because it is not possible to
-   hold all of them in memory.
-
-**Phase 2: Consistency checks**
-
-   Some checking is done to ensure no surprises in the built documents.
-
-**Phase 3: Resolving**
-
-   Now that the metadata and cross-reference data of all existing documents is
-   known, all temporary nodes are replaced by nodes that can be converted into
-   output using components called tranform.  For example, links are created for
-   object references that exist, and simple literal nodes are created for those
-   that don't.
-
-**Phase 4: Writing**
-
-   This phase converts the resolved doctrees to the desired output format, such
-   as HTML or LaTeX.  This happens via a so-called docutils writer that visits
-   the individual nodes of each doctree and produces some output in the process.
-
-.. note::
-
-   Some builders deviate from this general build plan, for example, the builder
-   that checks external links does not need anything more than the parsed
-   doctrees and therefore does not have phases 2--4.
-
-
 Extension Design
 ----------------
 
+.. note:: To understand the design this extension, refer to
+   :ref:`important-objects` and :ref:`build-phases`.
+
 We want the extension to add the following to Sphinx:
 
 * A "todo" directive, containing some content that is marked with "TODO", and
@@ -174,12 +72,13 @@ the individual calls do is the following:
 
   If the third argument was ``'html'``, HTML documents would be full rebuild if the
   config value changed its value.  This is needed for config values that
-  influence reading (build phase 1).
+  influence reading (build :ref:`phase 1 <build-phases>`).
 
 * :meth:`~Sphinx.add_node` adds a new *node class* to the build system.  It also
   can specify visitor functions for each supported output format.  These visitor
-  functions are needed when the new nodes stay until phase 4 -- since the
+  functions are needed when the new nodes stay until :ref:`phase 4 <build-phases>`
-  ``todolist`` node is always replaced in phase 3, it doesn't need any.
+  -- since the ``todolist`` node is always replaced in :ref:`phase 3 <build-phases>`,
+  it doesn't need any.
 
   We need to create the two node classes ``todo`` and ``todolist`` later.
 
@@ -276,7 +175,7 @@ The ``todo`` directive function looks like this::
            return [targetnode, todo_node]
 
 Several important things are covered here. First, as you can see, you can refer
-to the build environment instance using ``self.state.document.settings.env``.
+to the :ref:`build environment instance <important-objects>` using ``self.state.document.settings.env``.
 
 Then, to act as a link target (from the todolist), the todo directive needs to
 return a target node in addition to the todo node.  The target ID (in HTML, this
@@ -340,7 +239,8 @@ Here we clear out all todos whose docname matches the given one from the
 added again during parsing.
 
 The other handler belongs to the :event:`doctree-resolved` event.  This event is
-emitted at the end of phase 3 and allows custom resolving to be done::
+emitted at the end of :ref:`phase 3 <build-phases>` and allows custom resolving
+to be done::
 
    def process_todo_nodes(app, doctree, fromdocname):
        if not app.config.todo_include_todos:

doc/ext/builtins.rst

@@ -1,25 +0,0 @@
-Builtin Sphinx extensions
--------------------------
-
-These extensions are built in and can be activated by respective entries in the
-:confval:`extensions` configuration value:
-
-.. toctree::
-
-   autodoc
-   autosectionlabel
-   autosummary
-   coverage
-   doctest
-   extlinks
-   githubpages
-   graphviz
-   ifconfig
-   imgconverter
-   inheritance
-   intersphinx
-   linkcode
-   math
-   napoleon
-   todo
-   viewcode

doc/ext/thirdparty.rst

@@ -1,35 +0,0 @@
-Third-party extensions
-----------------------
-
-You can find several extensions contributed by users in the `Sphinx Contrib`_
-repository.  It is open for anyone who wants to maintain an extension
-publicly; just send a short message asking for write permissions.
-
-There are also several extensions hosted elsewhere.  The `Sphinx extension
-survey <http://sphinxext-survey.readthedocs.org/en/latest/>`__ contains a
-comprehensive list.
-
-If you write an extension that you think others will find useful or you think
-should be included as a part of Sphinx, please write to the project mailing
-list (`join here <https://groups.google.com/forum/#!forum/sphinx-dev>`_).
-
-.. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib
-
-
-Where to put your own extensions?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Extensions local to a project should be put within the project's directory
-structure.  Set Python's module search path, ``sys.path``, accordingly so that
-Sphinx can find them.
-E.g., if your extension ``foo.py`` lies in the ``exts`` subdirectory of the
-project root, put into :file:`conf.py`::
-
-   import sys, os
-
-   sys.path.append(os.path.abspath('exts'))
-
-   extensions = ['foo']
-
-You can also install extensions anywhere else on ``sys.path``, e.g. in the
-``site-packages`` directory.

doc/ext/viewcode.rst

@@ -1,64 +0,0 @@
-:mod:`sphinx.ext.viewcode` -- Add links to highlighted source code
-==================================================================
-
-.. module:: sphinx.ext.viewcode
-   :synopsis: Add links to a highlighted version of the source code.
-.. moduleauthor:: Georg Brandl
-
-.. versionadded:: 1.0
-
-
-This extension looks at your Python object descriptions (``.. class::``,
-``.. function::`` etc.) and tries to find the source files where the objects are
-contained.  When found, a separate HTML page will be output for each module with
-a highlighted version of the source code, and a link will be added to all object
-descriptions that leads to the source code of the described object.  A link back
-from the source to the description will also be inserted.
-
-This extension works only on HTML related builders like ``html``,
-``applehelp``, ``devhelp``, ``htmlhelp``, ``qthelp`` and so on except
-``singlehtml``. By default ``epub`` builder doesn't
-support this extension (see :confval:`viewcode_enable_epub`).
-
-There is an additional config value:
-
-.. confval:: viewcode_import
-
-   If this is ``True``, viewcode extension will follow alias objects that
-   imported from another module such as functions, classes and attributes.
-   As side effects, this option
-   else they produce nothing.  The default is ``True``.
-
-   .. warning::
-
-      :confval:`viewcode_import` **imports** the modules to be followed real
-      location.  If any modules have side effects on import, these will be
-      executed by ``viewcode`` when ``sphinx-build`` is run.
-
-      If you document scripts (as opposed to library modules), make sure their
-      main routine is protected by a ``if __name__ == '__main__'`` condition.
-
-   .. versionadded:: 1.3
-
-.. confval:: viewcode_enable_epub
-
-   If this is ``True``, viewcode extension is also enabled even if you use
-   epub builders. This extension generates pages outside toctree, but this
-   is not preferred as epub format.
-
-   Until 1.4.x, this extension is always enabled. If you want to generate
-   epub as same as 1.4.x, you should set ``True``, but epub format checker's
-   score becomes worse.
-
-   The default is ``False``.
-
-   .. versionadded:: 1.5
-
-   .. warning::
-
-      Not all epub readers support pages generated by viewcode extension.
-      These readers ignore links to pages are not under toctree.
-
-      Some reader's rendering result are corrupted and
-      `epubcheck <https://github.com/IDPF/epubcheck>`_'s score
-      becomes worse even if the reader supports.

doc/extdev/appapi.rst

@@ -7,9 +7,9 @@ Application API
    :synopsis: Application class and extensibility interface.
 
 
-Each Sphinx extension is a Python module with at least a :func:`setup` function.
+Each Sphinx extension is a Python module with at least a :func:`setup`
-This function is called at initialization time with one argument, the
+function.  This function is called at initialization time with one argument,
-application object representing the Sphinx process.
+the application object representing the Sphinx process.
 
 .. class:: Sphinx
 
@@ -23,387 +23,81 @@ These methods are usually called in an extension's ``setup()`` function.
 Examples of using the Sphinx extension API can be seen in the :mod:`sphinx.ext`
 package.
 
-.. method:: Sphinx.setup_extension(name)
+.. currentmodule:: sphinx.application
 
-   Load the extension given by the module *name*.  Use this if your extension
+.. automethod:: Sphinx.setup_extension(name)
-   needs the features provided by another extension.
 
-.. method:: Sphinx.add_builder(builder)
+.. automethod:: Sphinx.require_sphinx(version)
 
-   Register a new builder.  *builder* must be a class that inherits from
+.. automethod:: Sphinx.connect(event, callback)
-   :class:`~sphinx.builders.Builder`.
 
-.. method:: Sphinx.add_config_value(name, default, rebuild)
+.. automethod:: Sphinx.disconnect(listener_id)
 
-   Register a configuration value.  This is necessary for Sphinx to recognize
+.. automethod:: Sphinx.add_builder(builder)
-   new values and set default values accordingly.  The *name* should be prefixed
-   with the extension name, to avoid clashes.  The *default* value can be any
-   Python object.  The string value *rebuild* must be one of those values:
 
-   * ``'env'`` if a change in the setting only takes effect when a document is
+.. automethod:: Sphinx.add_config_value(name, default, rebuild)
-     parsed -- this means that the whole environment must be rebuilt.
-   * ``'html'`` if a change in the setting needs a full rebuild of HTML
-     documents.
-   * ``''`` if a change in the setting will not need any special rebuild.
 
-   .. versionchanged:: 0.4
+.. automethod:: Sphinx.add_event(name)
-      If the *default* value is a callable, it will be called with the config
-      object as its argument in order to get the default value.  This can be
-      used to implement config values whose default depends on other values.
 
-   .. versionchanged:: 0.6
+.. automethod:: Sphinx.set_translator(name, translator_class)
-      Changed *rebuild* from a simple boolean (equivalent to ``''`` or
-      ``'env'``) to a string.  However, booleans are still accepted and
-      converted internally.
 
-.. method:: Sphinx.add_domain(domain)
+.. automethod:: Sphinx.add_node(node, \*\*kwds)
 
-   Make the given *domain* (which must be a class; more precisely, a subclass of
+.. automethod:: Sphinx.add_enumerable_node(node, figtype, title_getter=None, \*\*kwds)
-   :class:`~sphinx.domains.Domain`) known to Sphinx.
 
-   .. versionadded:: 1.0
+.. method:: Sphinx.add_directive(name, func, content, arguments, \*\*options)
+.. automethod:: Sphinx.add_directive(name, directiveclass)
 
-.. method:: Sphinx.override_domain(domain)
+.. automethod:: Sphinx.add_role(name, role)
 
-   Make the given *domain* class known to Sphinx, assuming that there is already
+.. automethod:: Sphinx.add_generic_role(name, nodeclass)
-   a domain with its ``.name``.  The new domain must be a subclass of the
-   existing one.
 
-   .. versionadded:: 1.0
+.. automethod:: Sphinx.add_domain(domain)
 
-.. method:: Sphinx.add_index_to_domain(domain, index)
+.. automethod:: Sphinx.override_domain(domain)
 
-   Add a custom *index* class to the domain named *domain*.  *index* must be a
+.. method:: Sphinx.add_directive_to_domain(domain, name, func, content, arguments, \*\*options)
-   subclass of :class:`~sphinx.domains.Index`.
+.. automethod:: Sphinx.add_directive_to_domain(domain, name, directiveclass)
 
-   .. versionadded:: 1.0
+.. automethod:: Sphinx.add_role_to_domain(domain, name, role)
 
-.. method:: Sphinx.add_event(name)
+.. automethod:: Sphinx.add_index_to_domain(domain, index)
 
-   Register an event called *name*.  This is needed to be able to emit it.
+.. automethod:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='', doc_field_types=[])
 
-.. method:: Sphinx.set_translator(name, translator_class)
+.. automethod:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')
 
-   Register or override a Docutils translator class. This is used to register
+.. automethod:: Sphinx.add_transform(transform)
-   a custom output translator or to replace a builtin translator.
-   This allows extensions to use custom translator and define custom
-   nodes for the translator (see :meth:`add_node`).
 
-   .. versionadded:: 1.3
+.. automethod:: Sphinx.add_post_transform(transform)
 
-.. method:: Sphinx.add_node(node, **kwds)
+.. automethod:: Sphinx.add_js_file(filename, **kwargs)
 
-   Register a Docutils node class.  This is necessary for Docutils internals.
+.. automethod:: Sphinx.add_css_file(filename, **kwargs)
-   It may also be used in the future to validate nodes in the parsed documents.
 
-   Node visitor functions for the Sphinx HTML, LaTeX, text and manpage writers
+.. automethod:: Sphinx.add_latex_package(packagename, options=None)
-   can be given as keyword arguments: the keyword should be one or more of
-   ``'html'``, ``'latex'``, ``'text'``, ``'man'``, ``'texinfo'`` or any other
-   supported translators, the value a 2-tuple of ``(visit, depart)`` methods.
-   ``depart`` can be ``None`` if the ``visit`` function raises
-   :exc:`docutils.nodes.SkipNode`.  Example:
 
-   .. code-block:: python
+.. automethod:: Sphinx.add_lexer(alias, lexer)
 
-      class math(docutils.nodes.Element): pass
+.. automethod:: Sphinx.add_autodocumenter(cls)
 
-      def visit_math_html(self, node):
+.. automethod:: Sphinx.add_autodoc_attrgetter(type, getter)
-          self.body.append(self.starttag(node, 'math'))
-      def depart_math_html(self, node):
-          self.body.append('</math>')
 
-      app.add_node(math, html=(visit_math_html, depart_math_html))
+.. automethod:: Sphinx.add_search_language(cls)
 
-   Obviously, translators for which you don't specify visitor methods will choke
+.. automethod:: Sphinx.add_source_suffix(suffix, filetype)
-   on the node when encountered in a document to translate.
 
-   .. versionchanged:: 0.5
+.. automethod:: Sphinx.add_source_parser(parser)
-      Added the support for keyword arguments giving visit functions.
 
-.. method:: Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds)
+.. automethod:: Sphinx.add_env_collector(collector)
 
-   Register a Docutils node class as a numfig target.  Sphinx numbers the node
+.. automethod:: Sphinx.add_html_theme(name, theme_path)
-   automatically. And then the users can refer it using :rst:role:`numref`.
 
-   *figtype* is a type of enumerable nodes.  Each figtypes have individual
+.. automethod:: Sphinx.add_html_math_renderer(name, inline_renderers, block_renderers)
-   numbering sequences.  As a system figtypes, ``figure``, ``table`` and
-   ``code-block`` are defined.  It is able to add custom nodes to these
-   default figtypes.  It is also able to define new custom figtype if new
-   figtype is given.
 
-   *title_getter* is a getter function to obtain the title of node.  It takes
+.. automethod:: Sphinx.add_message_catalog(catalog, locale_dir)
-   an instance of the enumerable node, and it must return its title as string.
-   The title is used to the default title of references for :rst:role:`ref`.
-   By default, Sphinx searches ``docutils.nodes.caption`` or
-   ``docutils.nodes.title`` from the node as a title.
-
-   Other keyword arguments are used for node visitor functions. See the
-   :meth:`Sphinx.add_node` for details.
-
-   .. versionadded:: 1.4
-
-.. method:: Sphinx.add_directive(name, func, content, arguments, **options)
-            Sphinx.add_directive(name, directiveclass)
-
-   Register a Docutils directive.  *name* must be the prospective directive
-   name.  There are two possible ways to write a directive:
-
-   * In the docutils 0.4 style, *obj* is the directive function.  *content*,
-     *arguments* and *options* are set as attributes on the function and
-     determine whether the directive has content, arguments and options,
-     respectively.  **This style is deprecated.**
-
-   * In the docutils 0.5 style, *directiveclass* is the directive class.  It
-     must already have attributes named *has_content*, *required_arguments*,
-     *optional_arguments*, *final_argument_whitespace* and *option_spec* that
-     correspond to the options for the function way.  See `the Docutils docs
-     <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_ for
-     details.
-
-     The directive class must inherit from the class
-     ``docutils.parsers.rst.Directive``.
-
-   For example, the (already existing) :rst:dir:`literalinclude` directive would
-   be added like this:
-
-   .. code-block:: python
-
-      from docutils.parsers.rst import directives
-      add_directive('literalinclude', literalinclude_directive,
-                    content = 0, arguments = (1, 0, 0),
-                    linenos = directives.flag,
-                    language = directives.unchanged,
-                    encoding = directives.encoding)
-
-   .. versionchanged:: 0.6
-      Docutils 0.5-style directive classes are now supported.
-
-.. method:: Sphinx.add_directive_to_domain(domain, name, func, content, arguments, **options)
-            Sphinx.add_directive_to_domain(domain, name, directiveclass)
-
-   Like :meth:`add_directive`, but the directive is added to the domain named
-   *domain*.
-
-   .. versionadded:: 1.0
-
-.. method:: Sphinx.add_role(name, role)
-
-   Register a Docutils role.  *name* must be the role name that occurs in the
-   source, *role* the role function (see the `Docutils documentation
-   <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ on details).
-
-.. method:: Sphinx.add_role_to_domain(domain, name, role)
-
-   Like :meth:`add_role`, but the role is added to the domain named *domain*.
-
-   .. versionadded:: 1.0
-
-.. method:: Sphinx.add_generic_role(name, nodeclass)
-
-   Register a Docutils role that does nothing but wrap its contents in the
-   node given by *nodeclass*.
-
-   .. versionadded:: 0.6
-
-.. method:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, \
-                                   ref_nodeclass=None, objname='', doc_field_types=[])
-
-   This method is a very convenient way to add a new :term:`object` type that
-   can be cross-referenced.  It will do this:
-
-   * Create a new directive (called *directivename*) for documenting an object.
-     It will automatically add index entries if *indextemplate* is nonempty; if
-     given, it must contain exactly one instance of ``%s``.  See the example
-     below for how the template will be interpreted.
-   * Create a new role (called *rolename*) to cross-reference to these
-     object descriptions.
-   * If you provide *parse_node*, it must be a function that takes a string and
-     a docutils node, and it must populate the node with children parsed from
-     the string.  It must then return the name of the item to be used in
-     cross-referencing and index entries.  See the :file:`conf.py` file in the
-     source for this documentation for an example.
-   * The *objname* (if not given, will default to *directivename*) names the
-     type of object.  It is used when listing objects, e.g. in search results.
-
-   For example, if you have this call in a custom Sphinx extension::
-
-      app.add_object_type('directive', 'dir', 'pair: %s; directive')
-
-   you can use this markup in your documents::
-
-      .. rst:directive:: function
-
-         Document a function.
-
-      <...>
-
-      See also the :rst:dir:`function` directive.
-
-   For the directive, an index entry will be generated as if you had prepended ::
-
-      .. index:: pair: function; directive
-
-   The reference node will be of class ``literal`` (so it will be rendered in a
-   proportional font, as appropriate for code) unless you give the
-   *ref_nodeclass* argument, which must be a docutils node class.  Most useful
-   are ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also
-   use ``docutils.nodes.generated`` if you want no further text decoration.  If
-   the text should be treated as literal (e.g. no smart quote replacement), but
-   not have typewriter styling, use ``sphinx.addnodes.literal_emphasis`` or
-   ``sphinx.addnodes.literal_strong``.
-
-   For the role content, you have the same syntactical possibilities as for
-   standard Sphinx roles (see :ref:`xref-syntax`).
-
-   This method is also available under the deprecated alias
-   ``add_description_unit``.
-
-.. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')
-
-   This method is very similar to :meth:`add_object_type` except that the
-   directive it generates must be empty, and will produce no output.
-
-   That means that you can add semantic targets to your sources, and refer to
-   them using custom roles instead of generic ones (like :rst:role:`ref`).
-   Example call::
-
-      app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)
-
-   Example usage::
-
-      .. topic:: application API
-
-      The application API
-      -------------------
-
-      <...>
-
-      See also :topic:`this section <application API>`.
-
-   (Of course, the element following the ``topic`` directive needn't be a
-   section.)
-
-.. method:: Sphinx.add_transform(transform)
-
-   Add the standard docutils :class:`Transform` subclass *transform* to the list
-   of transforms that are applied after Sphinx parses a reST document.
-
-.. method:: Sphinx.add_post_transform(transform)
-
-   Add the standard docutils :class:`Transform` subclass *transform* to the list
-   of transforms that are applied before Sphinx writes a document.
-
-.. method:: Sphinx.add_javascript(filename)
-
-   Add *filename* to the list of JavaScript files that the default HTML template
-   will include.  The filename must be relative to the HTML static path, see
-   :confval:`the docs for the config value <html_static_path>`.  A full URI with
-   scheme, like ``http://example.org/foo.js``, is also supported.
-
-   .. versionadded:: 0.5
-
-.. method:: Sphinx.add_stylesheet(filename, alternate=None, title=None)
-
-   Add *filename* to the list of CSS files that the default HTML template will
-   include.  Like for :meth:`add_javascript`, the filename must be relative to
-   the HTML static path, or a full URI with scheme.
-
-   .. versionadded:: 1.0
-
-   .. versionchanged:: 1.6
-      Optional ``alternate`` and/or ``title`` attributes can be supplied with
-      the *alternate* (of boolean type) and *title* (a string) arguments. The
-      default is no title and *alternate* = ``False`` (see `this explanation
-      <https://developer.mozilla.org/en-US/docs/Web/CSS/Alternative_style_sheets>`_).
-
-.. method:: Sphinx.add_latex_package(packagename, options=None)
-
-   Add *packagename* to the list of packages that LaTeX source code will include.
-   If you provide *options*, it will be taken to `\usepackage` declaration.
-
-   .. code-block:: python
-
-      app.add_latex_package('mypackage')             # => \usepackage{mypackage}
-      app.add_latex_package('mypackage', 'foo,bar')  # => \usepackage[foo,bar]{mypackage}
-
-   .. versionadded:: 1.3
-
-.. method:: Sphinx.add_lexer(alias, lexer)
-
-   Use *lexer*, which must be an instance of a Pygments lexer class, to
-   highlight code blocks with the given language *alias*.
-
-   .. versionadded:: 0.6
-
-.. method:: Sphinx.add_autodocumenter(cls)
-
-   Add *cls* as a new documenter class for the :mod:`sphinx.ext.autodoc`
-   extension.  It must be a subclass of :class:`sphinx.ext.autodoc.Documenter`.
-   This allows to auto-document new types of objects.  See the source of the
-   autodoc module for examples on how to subclass :class:`Documenter`.
-
-   .. XXX add real docs for Documenter and subclassing
-
-   .. versionadded:: 0.6
-
-.. method:: Sphinx.add_autodoc_attrgetter(type, getter)
-
-   Add *getter*, which must be a function with an interface compatible to the
-   :func:`getattr` builtin, as the autodoc attribute getter for objects that are
-   instances of *type*.  All cases where autodoc needs to get an attribute of a
-   type are then handled by this function instead of :func:`getattr`.
-
-   .. versionadded:: 0.6
-
-.. method:: Sphinx.add_search_language(cls)
-
-   Add *cls*, which must be a subclass of :class:`sphinx.search.SearchLanguage`,
-   as a support language for building the HTML full-text search index.  The
-   class must have a *lang* attribute that indicates the language it should be
-   used for.  See :confval:`html_search_language`.
-
-   .. versionadded:: 1.1
-
-.. method:: Sphinx.add_source_parser(suffix, parser)
-
-   Register a parser class for specified *suffix*.
-
-   .. versionadded:: 1.4
-
-.. method:: Sphinx.add_html_theme(name, theme_path)
-
-   Register a HTML Theme.  The *name* is a name of theme, and *path* is a
-   full path to the theme (refs: :ref:`distribute-your-theme`).
-
-   .. versionadded:: 1.6
-
-.. method:: Sphinx.add_env_collector(collector)
-
-   Register an environment collector class (refs: :ref:`collector-api`)
-
-   .. versionadded:: 1.6
-
-.. method:: Sphinx.require_sphinx(version)
-
-   Compare *version* (which must be a ``major.minor`` version string,
-   e.g. ``'1.1'``) with the version of the running Sphinx, and abort the build
-   when it is too old.
-
-   .. versionadded:: 1.0
-
-.. method:: Sphinx.connect(event, callback)
-
-   Register *callback* to be called when *event* is emitted.  For details on
-   available core events and the arguments of callback functions, please see
-   :ref:`events`.
-
-   The method returns a "listener ID" that can be used as an argument to
-   :meth:`disconnect`.
-
-.. method:: Sphinx.disconnect(listener_id)
-
-   Unregister callback *listener_id*.
 
+.. automethod:: Sphinx.is_parallel_allowed(typ)
 
 .. exception:: ExtensionError
 
@@ -414,44 +108,37 @@ package.
 Emitting events
 ---------------
 
-.. method:: Sphinx.emit(event, *arguments)
+.. class:: Sphinx
 
-   Emit *event* and pass *arguments* to the callback functions.  Return the
+   .. automethod:: emit(event, \*arguments)
-   return values of all callbacks as a list.  Do not emit core Sphinx events
-   in extensions!
 
-.. method:: Sphinx.emit_firstresult(event, *arguments)
+   .. automethod:: emit_firstresult(event, \*arguments)
-
-   Emit *event* and pass *arguments* to the callback functions.  Return the
-   result of the first callback that doesn't return ``None``.
-
-   .. versionadded:: 0.5
 
 
-Producing messages / logging
+Sphinx runtime information
-----------------------------
+--------------------------
 
-The application object also provides support for emitting leveled messages.
+The application object also provides runtime information as attributes.
 
-.. note::
+.. attribute:: Sphinx.project
 
-   There is no "error" call: in Sphinx, errors are defined as things that stop
+   Target project.  See :class:`.Project`.
-   the build; just raise an exception (:exc:`sphinx.errors.SphinxError` or a
-   custom subclass) to do that.
 
-.. deprecated:: 1.6
+.. attribute:: Sphinx.srcdir
 
-   Please use :ref:`logging-api` instead.
+   Source directory.
 
-.. automethod:: Sphinx.warn
+.. attribute:: Sphinx.confdir
 
-.. automethod:: Sphinx.info
+   Directory containing ``conf.py``.
 
-.. automethod:: Sphinx.verbose
+.. attribute:: Sphinx.doctreedir
 
-.. automethod:: Sphinx.debug
+   Directory for storing pickled doctrees.
 
-.. automethod:: Sphinx.debug2
+.. attribute:: Sphinx.outdir
+
+   Directory for storing built document.
 
 
 .. _events:
@@ -478,6 +165,12 @@ handlers to the events.  Example:
    Emitted when the builder object has been created.  It is available as
    ``app.builder``.
 
+.. event:: config-inited (app, config)
+
+   Emitted when the config object has been initialized.
+
+   .. versionadded:: 1.8
+
 .. event:: env-get-outdated (app, env, added, changed, removed)
 
    Emitted when the environment determines which source files have changed and
@@ -556,7 +249,7 @@ handlers to the events.  Example:
    Here is the place to replace custom nodes that don't have visitor methods in
    the writers, so that they don't cause errors when the writers encounter them.
 
-.. event:: env-merge-info (env, docnames, other)
+.. event:: env-merge-info (app, env, docnames, other)
 
    This event is only emitted when parallel reading of documents is enabled.  It
    is emitted once for every subprocess that has read some documents.
@@ -590,9 +283,9 @@ handlers to the events.  Example:
    .. versionchanged:: 1.3
       The handlers' return value is now used.
 
-.. event:: env-check-consistency (env)
+.. event:: env-check-consistency (app, env)
 
-   Emmited when Consistency checks phase.  You can check consistency of
+   Emitted when Consistency checks phase.  You can check consistency of
    metadata for whole of documents.
 
    .. versionadded:: 1.6
@@ -652,28 +345,15 @@ Checking the Sphinx version
 
 Use this to adapt your extension to API changes in Sphinx.
 
-.. data:: version_info
+.. autodata:: version_info
-
-   A tuple of five elements; for Sphinx version 1.2.1 beta 3 this would be
-   ``(1, 2, 1, 'beta', 3)``.
-
-   .. versionadded:: 1.2
-      Before version 1.2, check the string ``sphinx.__version__``.
 
 
 The Config object
 -----------------
 
-.. module:: sphinx.config
+.. currentmodule:: sphinx.config
 
-.. class:: Config
+.. autoclass:: Config
-
-   The config object makes the values of all config values available as
-   attributes.
-
-   It is available as the ``config`` attribute on the application and
-   environment objects.  For example, to get the value of :confval:`language`,
-   use either ``app.config.language`` or ``env.config.language``.
 
 
 .. _template-bridge:
@@ -694,38 +374,12 @@ Exceptions
 
 .. module:: sphinx.errors
 
-.. exception:: SphinxError
+.. autoexception:: SphinxError
 
-   This is the base class for "nice" exceptions.  When such an exception is
+.. autoexception:: ConfigError
-   raised, Sphinx will abort the build and present the exception category and
-   message to the user.
 
-   Extensions are encouraged to derive from this exception for their custom
+.. autoexception:: ExtensionError
-   errors.
 
-   Exceptions *not* derived from :exc:`SphinxError` are treated as unexpected
+.. autoexception:: ThemeError
-   and shown to the user with a part of the traceback (and the full traceback
-   saved in a temporary file).
 
-   .. attribute:: category
+.. autoexception:: VersionRequirementError
-
-      Description of the exception "category", used in converting the exception
-      to a string ("category: message").  Should be set accordingly in
-      subclasses.
-
-.. exception:: ConfigError
-
-   Used for erroneous values or nonsensical combinations of configuration
-   values.
-
-.. exception:: ExtensionError
-
-   Used for errors in setting up extensions.
-
-.. exception:: ThemeError
-
-   Used for errors to do with themes.
-
-.. exception:: VersionRequirementError
-
-   Raised when the docs require a higher Sphinx version than the current one.

doc/extdev/builderapi.rst

@@ -15,7 +15,11 @@ Builder API
 
    .. autoattribute:: name
    .. autoattribute:: format
+   .. autoattribute:: epilog
    .. autoattribute:: supported_image_types
+   .. autoattribute:: supported_remote_images
+   .. autoattribute:: supported_data_uri_images
+   .. autoattribute:: default_translator_class
 
    These methods are predefined and will be called from the application:
 

doc/extdev/envapi.rst

@@ -15,14 +15,14 @@ Build environment API
 
       Reference to the :class:`.Config` object.
 
+   .. attribute:: project
+
+      Target project.  See :class:`.Project`.
+
    .. attribute:: srcdir
 
       Source directory.
 
-   .. attribute:: confdir
-
-      Directory containing ``conf.py``.
-
    .. attribute:: doctreedir
 
       Directory for storing pickled doctrees.
@@ -43,10 +43,6 @@ Build environment API
 
    **Utility methods**
 
-   .. automethod:: warn
-
-   .. automethod:: warn_node
-
    .. automethod:: doc2path
 
    .. automethod:: relfn2path

doc/extdev/i18n.rst

@@ -0,0 +1,17 @@
+.. _i18n-api:
+
+i18n API
+========
+
+.. currentmodule:: sphinx.locale
+
+.. autofunction:: init
+
+.. autofunction:: init_console
+
+.. autofunction:: get_translation
+
+.. autofunction:: _
+
+.. autofunction:: __
+

doc/extdev/index.rst

@@ -52,6 +52,117 @@ Note that it is still necessary to register the builder using
 
 .. _entry points: https://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins
 
+.. _important-objects:
+
+Important objects
+-----------------
+
+There are several key objects whose API you will use while writing an
+extension. These are:
+
+**Application**
+   The application object (usually called ``app``) is an instance of
+   :class:`.Sphinx`.  It controls most high-level functionality, such as the
+   setup of extensions, event dispatching and producing output (logging).
+
+   If you have the environment object, the application is available as
+   ``env.app``.
+
+**Environment**
+   The build environment object (usually called ``env``) is an instance of
+   :class:`.BuildEnvironment`.  It is responsible for parsing the source
+   documents, stores all metadata about the document collection and is
+   serialized to disk after each build.
+
+   Its API provides methods to do with access to metadata, resolving references,
+   etc.  It can also be used by extensions to cache information that should
+   persist for incremental rebuilds.
+
+   If you have the application or builder object, the environment is available
+   as ``app.env`` or ``builder.env``.
+
+**Builder**
+   The builder object (usually called ``builder``) is an instance of a specific
+   subclass of :class:`.Builder`.  Each builder class knows how to convert the
+   parsed documents into an output format, or otherwise process them (e.g. check
+   external links).
+
+   If you have the application object, the builder is available as
+   ``app.builder``.
+
+**Config**
+   The config object (usually called ``config``) provides the values of
+   configuration values set in :file:`conf.py` as attributes.  It is an instance
+   of :class:`.Config`.
+
+   The config is available as ``app.config`` or ``env.config``.
+
+To see an example of use of these objects, refer to :doc:`../development/tutorials/index`.
+
+.. _build-phases:
+
+Build Phases
+------------
+
+One thing that is vital in order to understand extension mechanisms is the way
+in which a Sphinx project is built: this works in several phases.
+
+**Phase 0: Initialization**
+
+   In this phase, almost nothing of interest to us happens.  The source
+   directory is searched for source files, and extensions are initialized.
+   Should a stored build environment exist, it is loaded, otherwise a new one is
+   created.
+
+**Phase 1: Reading**
+
+   In Phase 1, all source files (and on subsequent builds, those that are new or
+   changed) are read and parsed.  This is the phase where directives and roles
+   are encountered by docutils, and the corresponding code is executed.  The
+   output of this phase is a *doctree* for each source file; that is a tree of
+   docutils nodes.  For document elements that aren't fully known until all
+   existing files are read, temporary nodes are created.
+
+   There are nodes provided by docutils, which are documented `in the docutils
+   documentation <http://docutils.sourceforge.net/docs/ref/doctree.html>`__.
+   Additional nodes are provided by Sphinx and :ref:`documented here <nodes>`.
+
+   During reading, the build environment is updated with all meta- and cross
+   reference data of the read documents, such as labels, the names of headings,
+   described Python objects and index entries.  This will later be used to
+   replace the temporary nodes.
+
+   The parsed doctrees are stored on the disk, because it is not possible to
+   hold all of them in memory.
+
+**Phase 2: Consistency checks**
+
+   Some checking is done to ensure no surprises in the built documents.
+
+**Phase 3: Resolving**
+
+   Now that the metadata and cross-reference data of all existing documents is
+   known, all temporary nodes are replaced by nodes that can be converted into
+   output using components called transforms.  For example, links are created for
+   object references that exist, and simple literal nodes are created for those
+   that don't.
+
+**Phase 4: Writing**
+
+   This phase converts the resolved doctrees to the desired output format, such
+   as HTML or LaTeX.  This happens via a so-called docutils writer that visits
+   the individual nodes of each doctree and produces some output in the process.
+
+.. note::
+
+   Some builders deviate from this general build plan, for example, the builder
+   that checks external links does not need anything more than the parsed
+   doctrees and therefore does not have phases 2--4.
+
+To see an example of application, refer to :doc:`../development/tutorials/todo`.
+
+.. _ext-metadata:
+
 Extension metadata
 ------------------
 
@@ -63,6 +174,11 @@ as metadata of the extension.  Metadata keys currently recognized are:
 * ``'version'``: a string that identifies the extension version.  It is used for
   extension version requirement checking (see :confval:`needs_extensions`) and
   informational purposes.  If not given, ``"unknown version"`` is substituted.
+* ``'env_version'``: an integer that identifies the version of env data
+  structure if the extension stores any data to environment.  It is used to
+  detect the data structure has been changed from last build.  The extensions
+  have to increment the version when data structure has changed.  If not given,
+  Sphinx considers the extension does not stores any data to environment.
 * ``'parallel_read_safe'``: a boolean that specifies if parallel reading of
   source files can be used when the extension is loaded.  It defaults to
   ``False``, i.e. you have to explicitly specify your extension to be
@@ -75,9 +191,10 @@ APIs used for writing extensions
 --------------------------------
 
 .. toctree::
+   :maxdepth: 2
 
-   tutorial
    appapi
+   projectapi
    envapi
    builderapi
    collectorapi
@@ -86,3 +203,813 @@ APIs used for writing extensions
    parserapi
    nodes
    logging
+   i18n
+   utils
+
+.. _dev-deprecated-apis:
+
+Deprecated APIs
+---------------
+
+On developing Sphinx, we are always careful to the compatibility of our APIs.
+But, sometimes, the change of interface are needed for some reasons.  In such
+cases, we've marked them as deprecated. And they are kept during the two
+major versions (for more details, please see :ref:`deprecation-policy`).
+
+The following is a list of deprecated interfaces.
+
+.. tabularcolumns:: |>{\raggedright}\Y{.4}|>{\centering}\Y{.1}|>{\centering}\Y{.12}|>{\raggedright\arraybackslash}\Y{.38}|
+
+.. |LaTeXHyphenate| raw:: latex
+
+                    \hspace{0pt}
+
+.. list-table:: deprecated APIs
+   :header-rows: 1
+   :class: deprecated
+   :widths: 40, 10, 10, 40
+
+   * - Target
+     - |LaTeXHyphenate|\ Deprecated
+     - (will be) Removed
+     - Alternatives
+
+   * - ``encoding`` argument of ``autodoc.Documenter.get_doc()``,
+       ``autodoc.DocstringSignatureMixin.get_doc()``,
+       ``autodoc.DocstringSignatureMixin._find_signature()``, and
+       ``autodoc.ClassDocumenter.get_doc()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - arguments of ``EpubBuilder.build_mimetype()``,
+       ``EpubBuilder.build_container()``, ``EpubBuilder.build_content()``,
+       ``EpubBuilder.build_toc()`` and ``EpubBuilder.build_epub()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - arguments of ``Epub3Builder.build_navigation_doc()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``nodetype`` argument of
+       ``sphinx.search.WordCollector.is_meta_keywords()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``suffix`` argument of ``BuildEnvironment.doc2path()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - string style ``base`` argument of ``BuildEnvironment.doc2path()``
+     - 2.0
+     - 4.0
+     - ``os.path.join()``
+
+   * - ``sphinx.addnodes.abbreviation``
+     - 2.0
+     - 4.0
+     - ``docutils.nodes.abbreviation``
+
+   * - ``sphinx.builders.epub3.Epub3Builder.validate_config_value()``
+     - 2.0
+     - 4.0
+     - ``sphinx.builders.epub3.validate_config_values()``
+
+   * - ``sphinx.builders.html.SingleFileHTMLBuilder``
+     - 2.0
+     - 4.0
+     - ``sphinx.builders.singlehtml.SingleFileHTMLBuilder``
+
+   * - ``sphinx.builders.htmlhelp.HTMLHelpBuilder.open_file()``
+     - 2.0
+     - 4.0
+     - ``open()``
+
+   * - ``sphinx.cmd.quickstart.term_decode()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.cmd.quickstart.TERM_ENCODING``
+     - 2.0
+     - 4.0
+     - ``sys.stdin.encoding``
+
+   * - ``sphinx.config.check_unicode()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.config.string_classes``
+     - 2.0
+     - 4.0
+     - ``[str]``
+
+   * - ``sphinx.domains.cpp.DefinitionError.description``
+     - 2.0
+     - 4.0
+     - ``str(exc)``
+
+   * - ``sphinx.domains.cpp.NoOldIdError.description``
+     - 2.0
+     - 4.0
+     - ``str(exc)``
+
+   * - ``sphinx.domains.cpp.UnsupportedMultiCharacterCharLiteral.decoded``
+     - 2.0
+     - 4.0
+     - ``str(exc)``
+
+   * - ``sphinx.ext.autosummary.Autosummary.warn()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.Autosummary.genopt``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.Autosummary.warnings``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.autosummary.Autosummary.result``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.doctest.doctest_encode()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.jsmath``
+     - 2.0
+     - 4.0
+     - ``sphinxcontrib.jsmath``
+
+   * - ``sphinx.testing.util.remove_unicode_literal()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.util.attrdict``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.util.force_decode()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.util.get_matching_docs()``
+     - 2.0
+     - 4.0
+     - ``sphinx.util.get_matching_files()``
+
+   * - ``sphinx.util.inspect.Parameter``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.util.osutil.EEXIST``
+     - 2.0
+     - 4.0
+     - ``errno.EEXIST`` or ``FileExistsError``
+
+   * - ``sphinx.util.osutil.EINVAL``
+     - 2.0
+     - 4.0
+     - ``errno.EINVAL``
+
+   * - ``sphinx.util.osutil.ENOENT``
+     - 2.0
+     - 4.0
+     - ``errno.ENOENT`` or ``FileNotFoundError``
+
+   * - ``sphinx.util.osutil.EPIPE``
+     - 2.0
+     - 4.0
+     - ``errno.ENOENT`` or ``BrokenPipeError``
+
+   * - ``sphinx.util.osutil.walk()``
+     - 2.0
+     - 4.0
+     - ``os.walk()``
+
+   * - ``sphinx.util.pycompat.TextIOWrapper``
+     - 2.0
+     - 4.0
+     - ``io.TextIOWrapper``
+
+   * - ``sphinx.util.pycompat.UnicodeMixin``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.util.pycompat.htmlescape()``
+     - 2.0
+     - 4.0
+     - ``html.escape()``
+
+   * - ``sphinx.util.pycompat.indent()``
+     - 2.0
+     - 4.0
+     - ``textwrap.indent()``
+
+   * - ``sphinx.util.pycompat.u``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.util.PeekableIterator``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - Omitting the ``filename`` argument in an overriddent
+       ``IndexBuilder.feed()`` method.
+     - 2.0
+     - 4.0
+     - ``IndexBuilder.feed(docname, filename, title, doctree)``
+
+   * - ``sphinx.writers.latex.ExtBabel``
+     - 2.0
+     - 4.0
+     - ``sphinx.builders.latex.util.ExtBabel``
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.babel_defmacro()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.application.Sphinx._setting_up_extension``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - The ``importer`` argument of ``sphinx.ext.autodoc.importer._MockModule``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.ext.autodoc.importer._MockImporter``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.io.SphinxBaseFileInput``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.io.SphinxFileInput.supported``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.io.SphinxRSTFileInput``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.registry.SphinxComponentRegistry.add_source_input()``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator._make_visit_admonition()``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.collect_footnotes()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.writers.texinfo.TexinfoTranslator._make_visit_admonition()``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.text.TextTranslator._make_depart_admonition()``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.generate_numfig_format()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - :rst:dir:`highlightlang`
+     - 1.8
+     - 4.0
+     - :rst:dir:`highlight`
+
+   * - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
+     - 1.8
+     - 4.0
+     - :meth:`~sphinx.application.Sphinx.add_css_file()`
+
+   * - :meth:`~sphinx.application.Sphinx.add_javascript()`
+     - 1.8
+     - 4.0
+     - :meth:`~sphinx.application.Sphinx.add_js_file()`
+
+   * - :confval:`autodoc_default_flags`
+     - 1.8
+     - 4.0
+     - :confval:`autodoc_default_options`
+
+   * - ``content`` arguments of ``sphinx.util.image.guess_mimetype()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``gettext_compact`` arguments of
+       ``sphinx.util.i18n.find_catalog_source_files()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.io.SphinxI18nReader.set_lineno_for_reporter()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.io.SphinxI18nReader.line``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.directives.other.VersionChanges``
+     - 1.8
+     - 3.0
+     - ``sphinx.domains.changeset.VersionChanges``
+
+   * - ``sphinx.highlighting.PygmentsBridge.unhighlight()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``trim_doctest_flags`` arguments of
+       ``sphinx.highlighting.PygmentsBridge``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.ext.mathbase``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.ext.mathbase.MathDomain``
+     - 1.8
+     - 3.0
+     - ``sphinx.domains.math.MathDomain``
+
+   * - ``sphinx.ext.mathbase.MathDirective``
+     - 1.8
+     - 3.0
+     - ``sphinx.directives.patches.MathDirective``
+
+   * - ``sphinx.ext.mathbase.math_role()``
+     - 1.8
+     - 3.0
+     - ``docutils.parsers.rst.roles.math_role()``
+
+   * - ``sphinx.ext.mathbase.setup_math()``
+     - 1.8
+     - 3.0
+     - :meth:`~sphinx.application.Sphinx.add_html_math_renderer()`
+
+   * - ``sphinx.ext.mathbase.is_in_section_title()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.ext.mathbase.get_node_equation_number()``
+     - 1.8
+     - 3.0
+     - ``sphinx.util.math.get_node_equation_number()``
+
+   * - ``sphinx.ext.mathbase.wrap_displaymath()``
+     - 1.8
+     - 3.0
+     - ``sphinx.util.math.wrap_displaymath()``
+
+   * - ``sphinx.ext.mathbase.math`` (node)
+     - 1.8
+     - 3.0
+     - ``docutils.nodes.math``
+
+   * - ``sphinx.ext.mathbase.displaymath`` (node)
+     - 1.8
+     - 3.0
+     - ``docutils.nodes.math_block``
+
+   * - ``sphinx.ext.mathbase.eqref`` (node)
+     - 1.8
+     - 3.0
+     - ``sphinx.builders.latex.nodes.math_reference``
+
+   * - ``viewcode_import`` (config value)
+     - 1.8
+     - 3.0
+     - :confval:`viewcode_follow_imported_members`
+
+   * - ``sphinx.writers.latex.Table.caption_footnotetexts``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.Table.header_footnotetexts``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.footnotestack``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.in_container_literal_block``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.next_section_ids``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.next_hyperlink_ids``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.restrict_footnote()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.unrestrict_footnote()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.push_hyperlink_ids()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.pop_hyperlink_ids()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.bibitems``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.hlsettingstack``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.ExtBabel.get_shorthandoff()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html.HTMLTranslator.highlightlang()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html.HTMLTranslator.highlightlang_base()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html.HTMLTranslator.highlightlangopts()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html.HTMLTranslator.highlightlinenothreshold()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html5.HTMLTranslator.highlightlang()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html5.HTMLTranslator.highlightlang_base()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html5.HTMLTranslator.highlightlangopts()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.html5.HTMLTranslator.highlightlinenothreshold()``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.check_latex_elements()``
+     - 1.8
+     - 3.0
+     - Nothing
+
+   * - ``sphinx.application.CONFIG_FILENAME``
+     - 1.8
+     - 3.0
+     - ``sphinx.config.CONFIG_FILENAME``
+
+   * - ``Config.check_unicode()``
+     - 1.8
+     - 3.0
+     - ``sphinx.config.check_unicode()``
+
+   * - ``Config.check_types()``
+     - 1.8
+     - 3.0
+     - ``sphinx.config.check_confval_types()``
+
+   * - ``dirname``, ``filename`` and ``tags`` arguments of
+       ``Config.__init__()``
+     - 1.8
+     - 3.0
+     - ``Config.read()``
+
+   * - The value of :confval:`html_search_options`
+     - 1.8
+     - 3.0
+     - see :confval:`html_search_options`
+
+   * - ``sphinx.versioning.prepare()``
+     - 1.8
+     - 3.0
+     - ``sphinx.versioning.UIDTransform``
+
+   * - ``Sphinx.override_domain()``
+     - 1.8
+     - 3.0
+     - :meth:`~sphinx.application.Sphinx.add_domain()`
+
+   * - ``Sphinx.import_object()``
+     - 1.8
+     - 3.0
+     - ``sphinx.util.import_object()``
+
+   * - ``suffix`` argument of
+       :meth:`~sphinx.application.Sphinx.add_source_parser()`
+     - 1.8
+     - 3.0
+     - :meth:`~sphinx.application.Sphinx.add_source_suffix()`
+
+
+   * - ``BuildEnvironment.load()``
+     - 1.8
+     - 3.0
+     - ``pickle.load()``
+
+   * - ``BuildEnvironment.loads()``
+     - 1.8
+     - 3.0
+     - ``pickle.loads()``
+
+   * - ``BuildEnvironment.frompickle()``
+     - 1.8
+     - 3.0
+     - ``pickle.load()``
+
+   * - ``BuildEnvironment.dump()``
+     - 1.8
+     - 3.0
+     - ``pickle.dump()``
+
+   * - ``BuildEnvironment.dumps()``
+     - 1.8
+     - 3.0
+     - ``pickle.dumps()``
+
+   * - ``BuildEnvironment.topickle()``
+     - 1.8
+     - 3.0
+     - ``pickle.dump()``
+
+   * - ``BuildEnvironment._nitpick_ignore``
+     - 1.8
+     - 3.0
+     - :confval:`nitpick_ignore`
+
+   * - ``BuildEnvironment.versionchanges``
+     - 1.8
+     - 3.0
+     - N/A
+
+   * - ``BuildEnvironment.update()``
+     - 1.8
+     - 3.0
+     - ``Builder.read()``
+
+   * - ``BuildEnvironment.read_doc()``
+     - 1.8
+     - 3.0
+     - ``Builder.read_doc()``
+
+   * - ``BuildEnvironment._read_serial()``
+     - 1.8
+     - 3.0
+     - ``Builder.read()``
+
+   * - ``BuildEnvironment._read_parallel()``
+     - 1.8
+     - 3.0
+     - ``Builder.read()``
+
+   * - ``BuildEnvironment.write_doctree()``
+     - 1.8
+     - 3.0
+     - ``Builder.write_doctree()``
+
+   * - ``BuildEnvironment.note_versionchange()``
+     - 1.8
+     - 3.0
+     - ``ChangesDomain.note_changeset()``
+
+   * - ``warn()`` (template helper function)
+     - 1.8
+     - 3.0
+     - ``warning()``
+
+   * - :confval:`source_parsers`
+     - 1.8
+     - 3.0
+     - :meth:`~sphinx.application.Sphinx.add_source_parser()`
+
+   * - ``sphinx.util.docutils.directive_helper()``
+     - 1.8
+     - 3.0
+     - ``Directive`` class of docutils
+
+   * - ``sphinx.cmdline``
+     - 1.8
+     - 3.0
+     - ``sphinx.cmd.build``
+
+   * - ``sphinx.make_mode``
+     - 1.8
+     - 3.0
+     - ``sphinx.cmd.make_mode``
+
+   * - ``sphinx.locale.l_()``
+     - 1.8
+     - 3.0
+     - :func:`sphinx.locale._()`
+
+   * - ``sphinx.locale.lazy_gettext()``
+     - 1.8
+     - 3.0
+     - :func:`sphinx.locale._()`
+
+   * - ``sphinx.locale.mygettext()``
+     - 1.8
+     - 3.0
+     - :func:`sphinx.locale._()`
+
+   * - ``sphinx.util.copy_static_entry()``
+     - 1.5
+     - 3.0
+     - ``sphinx.util.fileutil.copy_asset()``
+
+   * - ``sphinx.build_main()``
+     - 1.7
+     - 2.0
+     - ``sphinx.cmd.build.build_main()``
+
+   * - ``sphinx.ext.intersphinx.debug()``
+     - 1.7
+     - 2.0
+     - ``sphinx.ext.intersphinx.inspect_main()``
+
+   * - ``sphinx.ext.autodoc.format_annotation()``
+     - 1.7
+     - 2.0
+     - ``sphinx.util.inspect.Signature``
+
+   * - ``sphinx.ext.autodoc.formatargspec()``
+     - 1.7
+     - 2.0
+     - ``sphinx.util.inspect.Signature``
+
+   * - ``sphinx.ext.autodoc.AutodocReporter``
+     - 1.7
+     - 2.0
+     - ``sphinx.util.docutils.switch_source_input()``
+
+   * - ``sphinx.ext.autodoc.add_documenter()``
+     - 1.7
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_autodocumenter()`
+
+   * - ``sphinx.ext.autodoc.AutoDirective._register``
+     - 1.7
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_autodocumenter()`
+
+   * - ``AutoDirective._special_attrgetters``
+     - 1.7
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_autodoc_attrgetter()`
+
+   * - ``Sphinx.warn()``, ``Sphinx.info()``
+     - 1.6
+     - 2.0
+     - :ref:`logging-api`
+
+   * - ``BuildEnvironment.set_warnfunc()``
+     - 1.6
+     - 2.0
+     - :ref:`logging-api`
+
+   * - ``BuildEnvironment.note_toctree()``
+     - 1.6
+     - 2.0
+     - ``Toctree.note()`` (in ``sphinx.environment.adapters.toctree``)
+
+   * - ``BuildEnvironment.get_toc_for()``
+     - 1.6
+     - 2.0
+     - ``Toctree.get_toc_for()`` (in ``sphinx.environment.adapters.toctree``)
+
+   * - ``BuildEnvironment.get_toctree_for()``
+     - 1.6
+     - 2.0
+     - ``Toctree.get_toctree_for()`` (in ``sphinx.environment.adapters.toctree``)
+
+   * - ``BuildEnvironment.create_index()``
+     - 1.6
+     - 2.0
+     - ``IndexEntries.create_index()`` (in ``sphinx.environment.adapters.indexentries``)
+
+   * - ``sphinx.websupport``
+     - 1.6
+     - 2.0
+     - `sphinxcontrib-websupport <https://pypi.org/project/sphinxcontrib-websupport/>`_
+
+   * - ``StandaloneHTMLBuilder.css_files``
+     - 1.6
+     - 2.0
+     - :meth:`~sphinx.application.Sphinx.add_stylesheet()`
+
+   * - ``document.settings.gettext_compact``
+     - 1.8
+     - 1.8
+     - :confval:`gettext_compact`
+
+   * - ``Sphinx.status_iterator()``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.status_iterator()``
+
+   * - ``Sphinx.old_status_iterator()``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.old_status_iterator()``
+
+   * - ``Sphinx._directive_helper()``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.docutils.directive_helper()``
+
+   * - ``sphinx.util.compat.Directive``
+     - 1.6
+     - 1.7
+     - ``docutils.parsers.rst.Directive``
+
+   * - ``sphinx.util.compat.docutils_version``
+     - 1.6
+     - 1.7
+     - ``sphinx.util.docutils.__version_info__``
+
+.. note:: On deprecating on public APIs (internal functions and classes),
+          we also follow the policy as much as possible.

doc/extdev/logging.rst

@@ -3,22 +3,15 @@
 Logging API
 ===========
 
-.. function:: sphinx.util.logging.getLogger(name)
+.. currentmodule:: sphinx.util.logging
 
-   Returns a logger wrapped by :class:`SphinxLoggerAdapter` with the specified *name*.
+.. autofunction:: getLogger(name)
 
-   Example usage::
+.. autoclass:: SphinxLoggerAdapter(logging.LoggerAdapter)
 
-     from sphinx.util import logging  # Load on top of python's logging module
+   .. method:: SphinxLoggerAdapter.error(msg, *args, **kwargs)
-
+   .. method:: SphinxLoggerAdapter.critical(msg, *args, **kwargs)
-     logger = logging.getLogger(__name__)
+   .. method:: SphinxLoggerAdapter.warning(msg, *args, **kwargs)
-     logger.info('Hello, this is an extension!')
-
-.. class:: SphinxLoggerAdapter(logging.LoggerAdapter)
-
-   .. method:: SphinxLoggerAdapter.error(level, msg, *args, **kwargs)
-   .. method:: SphinxLoggerAdapter.critical(level, msg, *args, **kwargs)
-   .. method:: SphinxLoggerAdapter.warning(level, msg, *args, **kwargs)
 
       Logs a message on this logger with the specified level.
       Basically, the arguments are as with python's logging module.
@@ -40,13 +33,14 @@ Logging API
           logger.warning('Warning happened!', location=some_node)
 
       **color**
-        The color of logs.  By default, warning level logs are
+        The color of logs.  By default, error level logs are colored as
-        colored as ``"darkred"``.  The others are not colored.
+        ``"darkred"``, critical level ones is not colored, and warning level
+        ones are colored as ``"red"``.
 
    .. method:: SphinxLoggerAdapter.log(level, msg, *args, **kwargs)
-   .. method:: SphinxLoggerAdapter.info(level, msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.info(msg, *args, **kwargs)
-   .. method:: SphinxLoggerAdapter.verbose(level, msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.verbose(msg, *args, **kwargs)
-   .. method:: SphinxLoggerAdapter.debug(level, msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.debug(msg, *args, **kwargs)
 
       Logs a message to this logger with the specified level.
       Basically, the arguments are as with python's logging module.
@@ -57,21 +51,16 @@ Logging API
         If true, the logger does not fold lines at the end of the log message.
         The default is ``False``.
 
+      **location**
+        Where the message emitted.  For more detail, see
+        :meth:`SphinxLoggerAdapter.warning`.
+
       **color**
-        The color of logs.  By default, debug level logs are
+        The color of logs.  By default, info and verbose level logs are not colored,
-        colored as ``"darkgray"``, and debug2 level ones are ``"lightgray"``.
+        and debug level ones are colored as ``"darkgray"``.
-        The others are not colored.
 
-.. function:: pending_logging()
+.. autofunction:: pending_logging()
 
-   Marks all logs as pending::
+.. autofunction:: pending_warnings()
 
-     with pending_logging():
+.. autofunction:: prefixed_warnings()
-       logger.warning('Warning message!')  # not flushed yet
-       some_long_process()
-
-     # the warning is flushed here
-
-.. function:: pending_warnings()
-
-   Marks warning logs as pending.  Similar to :func:`pending_logging`.

doc/extdev/markupapi.rst

@@ -117,12 +117,30 @@ Both APIs parse the content into a given node. They are used like this::
 
    node = docutils.nodes.paragraph()
    # either
-   from sphinx.ext.autodoc import AutodocReporter
-   self.state.memo.reporter = AutodocReporter(self.result, self.state.memo.reporter)  # override reporter to avoid errors from "include" directive
    nested_parse_with_titles(self.state, self.result, node)
    # or
    self.state.nested_parse(self.result, 0, node)
 
+.. note::
+
+   ``sphinx.util.docutils.switch_source_input()`` allows to change a target file
+   during nested_parse.  It is useful to mixed contents.  For example, ``sphinx.
+   ext.autodoc`` uses it to parse docstrings::
+
+       from sphinx.util.docutils import switch_source_input
+
+       # Switch source_input between parsing content.
+       # Inside this context, all parsing errors and warnings are reported as
+       # happened in new source_input (in this case, ``self.result``).
+       with switch_source_input(self.state, self.result):
+           node = docutils.nodes.paragraph()
+           self.state.nested_parse(self.result, 0, node)
+
+   .. deprecated:: 1.7
+
+      Until Sphinx-1.6, ``sphinx.ext.autodoc.AutodocReporter`` is used for this purpose.
+      For now, it is replaced by ``switch_source_input()``.
+
 If you don't need the wrapping node, you can use any concrete node type and
 return ``node.children`` from the Directive.
 

doc/extdev/parserapi.rst

@@ -3,6 +3,35 @@
 Parser API
 ==========
 
+`The docutils documentation describes`__ parsers as follows:
+
+    The Parser analyzes the input document and creates a node tree
+    representation.
+
+__ http://docutils.sourceforge.net/docs/dev/hacking.html#parsing-the-document
+
+In Sphinx, the parser modules works as same as docutils.  The parsers are
+registered to Sphinx by extensions using Application APIs;
+:meth:`.Sphinx.add_source_suffix()` and :meth:`.Sphinx.add_source_parser()`.
+
+The *source suffix* is a mapping from file suffix to file type.  For example,
+``.rst`` file is mapped to ``'restructuredtext'`` type.  Sphinx uses the
+file type to looking for parsers from registered list.  On searching,
+Sphinx refers to the ``Parser.supported`` attribute and picks up a parser
+which contains the file type in the attribute.
+
+The users can override the source suffix mappings using
+:confval:`source_suffix` like following::
+
+    # a mapping from file suffix to file types
+    source_suffix = {
+        '.rst': 'restructuredtext',
+        '.md': 'markdown',
+    }
+
+You should indicate file types your parser supports. This will allow users
+to configure their settings appropriately.
+
 .. module:: sphinx.parsers
 
 .. autoclass:: Parser

doc/extdev/projectapi.rst

@@ -0,0 +1,9 @@
+.. _project-api:
+
+Project API
+===========
+
+.. currentmodule:: sphinx.project
+
+.. autoclass:: Project
+   :members:

doc/extdev/utils.rst

@@ -0,0 +1,22 @@
+Utilities
+=========
+
+Sphinx provides utility classes and functions to develop extensions.
+
+Base classes for components
+---------------------------
+
+These base classes are useful to allow your extensions to obtain Sphinx
+components (e.g. :class:`.Config`, :class:`.BuildEnvironment` and so on) easily.
+
+.. note:: The subclasses of them might not work with bare docutils because they
+          are strongly coupled with Sphinx.
+
+.. autoclass:: sphinx.transforms.SphinxTransform
+   :members:
+
+.. autoclass:: sphinx.util.docutils.SphinxDirective
+   :members:
+
+.. autoclass:: sphinx.transforms.post_transforms.images.ImageConverter
+   :members:

doc/extensions.rst

@@ -1,16 +0,0 @@
-.. _extensions:
-
-Sphinx Extensions
-=================
-
-Since many projects will need special features in their documentation, Sphinx
-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
-documentation on writing your own extension, see :ref:`dev-extensions`.
-
-.. toctree::
-
-   ext/builtins
-   ext/thirdparty

doc/faq.rst

@@ -11,29 +11,26 @@ How do I...
 
 ... create PDF files without LaTeX?
    `rinohtype`_ provides a PDF builder that can be used as a drop-in
-   replacement for the LaTeX builder.  Alternatively, you can use `rst2pdf`_
+   replacement for the LaTeX builder.
-   version 0.12 or greater which comes with built-in Sphinx integration.  See
-   the :ref:`builders` section for details.
 
    .. _rinohtype: https://github.com/brechtm/rinohtype
-   .. _rst2pdf: https://github.com/rst2pdf/rst2pdf
 
 ... get section numbers?
    They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to
    the :rst:dir:`toctree` directive where you want to start numbering.
 
 ... customize the look of the built HTML files?
-   Use themes, see :doc:`theming`.
+   Use themes, see :doc:`/usage/theming`.
 
 ... add global substitutions or includes?
-   Add them in the :confval:`rst_epilog` config value.
+   Add them in the :confval:`rst_prolog` or :confval:`rst_epilog` config value.
 
 ... display the whole TOC tree in the sidebar?
    Use the :data:`toctree` callable in a custom layout template, probably in the
    ``sidebartoc`` block.
 
 ... write my own extension?
-   See the :ref:`extension tutorial <exttut>`.
+   See the :doc:`/development/tutorials/index`.
 
 ... convert from my existing docs using MoinMoin markup?
    The easiest way is to convert to xhtml, then convert `xhtml to reST`_.
@@ -58,7 +55,7 @@ Read the Docs
     Sphinx. They will host sphinx documentation, along with supporting a number
     of other features including version support, PDF generation, and more. The
     `Getting Started
-    <http://read-the-docs.readthedocs.org/en/latest/getting_started.html>`_
+    <https://read-the-docs.readthedocs.io/en/latest/getting_started.html>`_
     guide is a good place to start.
 
 Epydoc
@@ -75,9 +72,9 @@ SCons
 
 PyPI
    Jannis Leidel wrote a `setuptools command
-   <https://pypi.python.org/pypi/Sphinx-PyPI-upload>`_ that automatically
+   <https://pypi.org/project/Sphinx-PyPI-upload/>`_ that automatically
    uploads Sphinx documentation to the PyPI package documentation area at
-   http://pythonhosted.org/.
+   https://pythonhosted.org/.
 
 GitHub Pages
    Directories starting with underscores are ignored by default which breaks
@@ -106,7 +103,7 @@ Google Analytics
 
       {% block footer %}
       {{ super() }}
-      <div class="footer">This page uses <a href="http://analytics.google.com/">
+      <div class="footer">This page uses <a href="https://analytics.google.com/">
       Google Analytics</a> to collect statistics. You can disable it by blocking
       the JavaScript coming from www.google-analytics.com.
       <script type="text/javascript">
@@ -122,7 +119,7 @@ Google Analytics
       {% endblock %}
 
 
-.. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
+.. _api role: https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
 .. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
 
 
@@ -208,7 +205,7 @@ The following list gives some hints for the creation of epub files:
 .. _Epubcheck: https://github.com/IDPF/epubcheck
 .. _Calibre: https://calibre-ebook.com/
 .. _FBreader: https://fbreader.org/
-.. _Bookworm: http://www.oreilly.com/bookworm/index.html
+.. _Bookworm: https://www.oreilly.com/bookworm/index.html
 .. _kindlegen: https://www.amazon.com/gp/feature.html?docId=1000765211
 
 .. _texinfo-faq:

doc/glossary.rst

@@ -12,7 +12,8 @@ Glossary
       use the builder builders that e.g. check for broken links in the
       documentation, or build coverage information.
 
-      See :ref:`builders` for an overview over Sphinx's built-in builders.
+      See :doc:`/usage/builders/index` for an overview over Sphinx's built-in
+      builders.
 
    configuration directory
       The directory containing :file:`conf.py`.  By default, this is the same as
@@ -32,7 +33,7 @@ Glossary
 
             Content of the directive.
 
-      See :ref:`directives` for more information.
+      See :ref:`rst-directives` for more information.
 
    document name
       Since reST source files can have different extensions (some people like
@@ -56,8 +57,9 @@ Glossary
       Having domains means that there are no naming problems when one set of
       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.  For more information about domains,
+      languages are much easier to write.
-      see the chapter :ref:`domains`.
+
+      For more information, refer to :doc:`/usage/restructuredtext/domains`.
 
    environment
       A structure where information about all documents under the root is saved,
@@ -65,6 +67,12 @@ Glossary
       parsing stage, so that successive runs only need to read and parse new and
       changed documents.
 
+   extension
+     A custom :term:`role`, :term:`directive` or other aspect of Sphinx that
+     allows users to modify any aspect of the build process within Sphinx.
+
+     For more information, refer to :doc:`/usage/extensions/index`.
+
    master document
       The document that contains the root :rst:dir:`toctree` directive.
 
@@ -81,8 +89,12 @@ Glossary
    role
       A reStructuredText markup element that allows marking a piece of text.
       Like directives, roles are extensible.  The basic syntax looks like this:
-      ``:rolename:`content```.  See :ref:`inlinemarkup` for details.
+      ``:rolename:`content```.  See :ref:`rst-inline-markup` for details.
 
    source directory
       The directory which, including its subdirectories, contains all source
       files for one Sphinx project.
+
+   reStructuredText
+      An easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and
+      parser system.

doc/install.rst

@@ -1,155 +0,0 @@
-:orphan:
-
-Installing Sphinx
-=================
-
-Since Sphinx is written in the Python language, you need to install Python
-(the required version is at least 2.7) and Sphinx.
-
-Sphinx packages are available on the `Python Package Index
-<https://pypi.python.org/pypi/Sphinx>`_.
-
-You can also download a snapshot from the Git repository:
-
-* as a `.tar.gz <https://github.com/sphinx-doc/sphinx/archive/master.tar.gz>`__
-  file or
-* as a `.zip <https://github.com/sphinx-doc/sphinx/archive/master.zip>`_ file
-
-There are introductions for several environments:
-
-.. contents::
-   :depth: 1
-   :local:
-   :backlinks: none
-
-
-Debian/Ubuntu: Install Sphinx using packaging system
-----------------------------------------------------
-
-You may install using this command if you use Debian/Ubuntu.
-
-.. code-block:: bash
-
-   $ apt-get install python-sphinx
-
-
-Other Linux distributions
--------------------------
-
-Most Linux distributions have Sphinx in their package repositories.  Usually the
-package is called "python-sphinx", "python-Sphinx" or "sphinx".  Be aware that
-there are two other packages with "sphinx" in their name: a speech recognition
-toolkit (CMU Sphinx) and a full-text search database (Sphinx search).
-
-
-Mac OS X: Install Sphinx using MacPorts
----------------------------------------
-
-If you use Mac OS X `MacPorts <http://www.macports.org/>`_, use this command to
-install all necessary software.
-
-.. code-block:: bash
-
-   $ sudo port install py27-sphinx
-
-To set up the executable paths, use the ``port select`` command:
-
-.. code-block:: bash
-
-   $ sudo port select --set python python27
-   $ sudo port select --set sphinx py27-sphinx
-
-Type :command:`which sphinx-quickstart` to check if the installation was
-successful.
-
-
-Windows: Install Python and Sphinx
-----------------------------------
-
-Install Python
-^^^^^^^^^^^^^^
-
-Most Windows users do not have Python, so we begin with the installation of
-Python itself.  If you have already installed Python, please skip this section.
-
-Go to https://www.python.org/, the main download site for Python. Look at the left
-sidebar and under "Quick Links", click "Windows Installer" to download.
-
-.. image:: pythonorg.png
-
-.. note::
-
-   Currently, Python offers two major versions, 2.x and 3.x. Sphinx 1.5 can run
-   under Python 2.7, 3.4, 3.5, 3.6, with the recommended version being 2.7.  This
-   chapter assumes you have installed Python 2.7.
-
-Follow the Windows installer for Python.
-
-.. image:: installpython.jpg
-
-After installation, you better add the Python executable directories to the
-environment variable ``PATH`` in order to run Python and package commands such
-as ``sphinx-build`` easily from the Command Prompt.
-
-* Right-click the "My Computer" icon and choose "Properties"
-* Click the "Environment Variables" button under the "Advanced" tab
-
-* If "Path" (or "PATH") is already an entry in the "System variables" list, edit
-  it.  If it is not present, add a new variable called "PATH".
-
-* Add these paths, separating entries by ";":
-
-  - ``C:\Python27`` -- this folder contains the main Python executable
-  - ``C:\Python27\Scripts`` -- this folder will contain executables added by
-    Python packages installed with pip (see below)
-
-  This is for Python 2.7.  If you use another version of
-  Python or installed to a non-default location, change the digits "27"
-  accordingly.
-
-* Now run the **Command Prompt**.  After command prompt window appear, type
-  ``python`` and Enter.  If the Python installation was successful, the
-  installed Python version is printed, and you are greeted by the prompt
-  ``>>>``.  Type ``Ctrl+Z`` and Enter to quit.
-
-
-Install the pip command
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Python has a very useful :command:`pip` command which can download and install
-3rd-party libraries with a single command. This is provided by the
-Python Packaging Authority(PyPA):
-https://groups.google.com/forum/#!forum/pypa-dev
-
-To install pip, download https://bootstrap.pypa.io/get-pip.py and
-save it somewhere.  After download, invoke the command prompt, go to the
-directory with ``get-pip.py`` and run this command:
-
-.. code-block:: bat
-
-   C:\> python get-pip.py
-
-Now :command:`pip` command is installed.  From there we can go to the Sphinx
-install.
-
-.. note::
-
-   ``pip`` has been contained in the Python official installation after version
-   of Python-3.4.0 or Python-2.7.9.
-
-
-Installing Sphinx with pip
---------------------------
-
-If you finished the installation of pip, type this line in the command prompt:
-
-.. code-block:: bat
-
-   C:\> pip install sphinx
-
-After installation, type :command:`sphinx-build -h` on the command prompt.  If
-everything worked fine, you will get a Sphinx version number and a list of
-options for this command.
-
-That it.  Installation is over.  Head to :doc:`tutorial` to make a Sphinx
-project.

doc/intro.rst

@@ -3,12 +3,12 @@ Introduction
 
 This is the documentation for the Sphinx documentation builder.  Sphinx is a
 tool that translates a set of reStructuredText_ source files into various output
-formats, automatically producing cross-references, indices etc.  That is, if
+formats, automatically producing cross-references, indices, etc.  That is, if
 you have a directory containing a bunch of reST-formatted documents (and
 possibly subdirectories of docs in there as well), Sphinx can generate a
 nicely-organized arrangement of HTML files (in some other directory) for easy
 browsing and navigation.  But from the same source, it can also generate a PDF
-file using LaTeX, `rinohtype`_ or `rst2pdf`_ (see :ref:`builders`).
+file using LaTeX.
 
 The focus is on hand-written documentation, rather than auto-generated API docs.
 Though there is support for that kind of documentation as well (which is
@@ -17,11 +17,10 @@ docs have a look at `Epydoc <http://epydoc.sourceforge.net/>`_, which also
 understands reST.
 
 For a great "introduction" to writing docs in general -- the whys and hows, see
-also `Write the docs <http://write-the-docs.readthedocs.org/>`_, written by Eric
+also `Write the docs <https://write-the-docs.readthedocs.io/>`_, written by Eric
 Holscher.
 
 .. _rinohtype: https://github.com/brechtm/rinohtype
-.. _rst2pdf: https://github.com/rst2pdf/rst2pdf
 
 Conversion from other systems
 -----------------------------
@@ -30,20 +29,20 @@ This section is intended to collect helpful hints for those wanting to migrate
 to reStructuredText/Sphinx from other documentation systems.
 
 * Gerard Flanagan has written a script to convert pure HTML to reST; it can be
-  found at the `Python Package Index <https://pypi.python.org/pypi/html2rest>`_.
+  found at the `Python Package Index <https://pypi.org/project/html2rest/>`_.
 
 * For converting the old Python docs to Sphinx, a converter was written which
   can be found at `the Python SVN repository
-  <http://svn.python.org/projects/doctools/converter>`_.  It contains generic
+  <https://svn.python.org/projects/doctools/converter/>`_.  It contains generic
   code to convert Python-doc-style LaTeX markup to Sphinx reST.
 
 * Marcin Wojdyr has written a script to convert Docbook to reST with Sphinx
-  markup; it is at `Google Code <https://github.com/wojdyr/db2rst>`_.
+  markup; it is at `GitHub <https://github.com/wojdyr/db2rst>`_.
 
 * Christophe de Vienne wrote a tool to convert from Open/LibreOffice documents
-  to Sphinx: `odt2sphinx <https://pypi.python.org/pypi/odt2sphinx/>`_.
+  to Sphinx: `odt2sphinx <https://pypi.org/project/odt2sphinx/>`_.
 
-* To convert different markups, `Pandoc <http://pandoc.org/>`_ is
+* To convert different markups, `Pandoc <https://pandoc.org/>`_ is
   a very helpful tool.
 
 
@@ -56,19 +55,17 @@ See the :ref:`pertinent section in the FAQ list <usingwith>`.
 Prerequisites
 -------------
 
-Sphinx needs at least **Python 2.7** or **Python 3.4** to run, as well as the
+Sphinx needs at least **Python 3.5** to run, as well as the docutils_ and
-docutils_ and Jinja2_ libraries.  Sphinx should work with docutils version 0.10
+Jinja2_ libraries. Sphinx should work with docutils version 0.12 or some (not
-or some (not broken) SVN trunk snapshot.  If you like to have source code
+broken) SVN trunk snapshot.
-highlighting support, you must also install the Pygments_ library.
 
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _docutils: http://docutils.sourceforge.net/
 .. _Jinja2: http://jinja.pocoo.org/
-.. _Pygments: http://pygments.org/
 
 
 Usage
 -----
 
-See :doc:`tutorial` for an introduction.  It also contains links to more
+See :doc:`/usage/quickstart` for an introduction.  It also contains links to
-advanced sections in this manual for the topics it discusses.
+more advanced sections in this manual for the topics it discusses.

doc/latex.rst

@@ -1,4 +1,4 @@
-.. highlightlang:: python
+.. highlight:: python
 
 .. _latex:
 
@@ -8,9 +8,6 @@ LaTeX customization
 .. module:: latex
    :synopsis: LaTeX specifics.
 
-The *latex* target does not benefit from pre-prepared themes like the
-*html* target does (see :doc:`theming`).
-
 .. raw:: latex
 
    \begingroup
@@ -29,12 +26,24 @@ The *latex* target does not benefit from pre-prepared themes like the
          cautionBgColor={named}{LightCyan}}
    \relax
 
+The *latex* target does not benefit from prepared themes.
 
-Basic customization
+The :ref:`latex-options`, and particularly among them the
--------------------
+:ref:`latex_elements <latex_elements_confval>` variable
+provides much of the interface for customization.
 
-It is achieved via usage of the
+For some details of the LaTeX/PDF builder command line
-:ref:`latex-options` as described in :doc:`config`. For example::
+invocation, refer to :py:class:`~sphinx.builders.latex.LaTeXBuilder`.
+
+.. _latex-basic:
+
+Example
+-------
+
+Keep in mind that backslashes must be doubled in Python string literals to
+avoid interpretation as escape sequences, or use raw strings (as is done here).
+
+::
 
    # inside conf.py
    latex_engine = 'xelatex'
@@ -56,94 +65,460 @@ It is achieved via usage of the
    }
    latex_show_urls = 'footnote'
 
-.. the above was tested on Sphinx's own 1.5a2 documentation with good effect!
-
 .. highlight:: latex
 
-If the size of the ``'preamble'`` contents becomes inconvenient, one may move
+.. _latex_elements_confval:
-all needed macros into some file :file:`mystyle.tex` of the project source
-repertory, and get LaTeX to import it at run time::
 
-   'preamble': r'\input{mystyle.tex}',
+The latex_elements configuration setting
-   # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
+----------------------------------------
-   'preamble': r'\usepackage{mystyle}',
 
-It is needed to set appropriately :confval:`latex_additional_files`, for
+A dictionary that contains LaTeX snippets overriding those Sphinx usually puts
-example::
+into the generated ``.tex`` files.  Its ``'sphinxsetup'`` key is described
+:ref:`separately <latexsphinxsetup>`.
+
+* Keys that you may want to override include:
+
+  ``'papersize'``
+     Paper size option of the document class (``'a4paper'`` or
+     ``'letterpaper'``), default ``'letterpaper'``.
+
+  ``'pointsize'``
+     Point size option of the document class (``'10pt'``, ``'11pt'`` or
+     ``'12pt'``), default ``'10pt'``.
+
+  ``'pxunit'``
+     the value of the ``px`` when used in image attributes ``width`` and
+     ``height``. The default value is ``'0.75bp'`` which achieves
+     ``96px=1in`` (in TeX ``1in = 72bp = 72.27pt``.) To obtain for
+     example ``100px=1in`` use ``'0.01in'`` or ``'0.7227pt'`` (the latter
+     leads to TeX computing a more precise value, due to the smaller unit
+     used in the specification); for ``72px=1in``, simply use ``'1bp'``; for
+     ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``.
+
+     .. versionadded:: 1.5
+
+  ``'passoptionstopackages'``
+     A string which will be positioned early in the preamble, designed to
+     contain ``\\PassOptionsToPackage{options}{foo}`` commands. Default empty.
+
+     .. versionadded:: 1.4
+
+  ``'babel'``
+     "babel" package inclusion, default ``'\\usepackage{babel}'`` (the
+     suitable document language string is passed as class option, and
+     ``english`` is used if no language.) For Japanese documents, the
+     default is the empty string.
+
+     With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use
+     `polyglossia`_, but one should be aware that current `babel`_ has
+     improved its support for Unicode engines in recent years and for some
+     languages it may make sense to prefer ``babel`` over ``polyglossia``.
+
+     .. hint::
+
+        After modifiying a core LaTeX key like this one, clean up the LaTeX
+        build repertory before next PDF build, else left-over auxiliary
+        files are likely to break the build.
+
+     .. _`polyglossia`: https://ctan.org/pkg/polyglossia
+     .. _`babel`: https://ctan.org/pkg/babel
+
+     .. versionchanged:: 1.5
+        For :confval:`latex_engine` set to ``'xelatex'``, the default
+        is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``.
+     .. versionchanged:: 1.6
+        ``'lualatex'`` uses same default setting as ``'xelatex'``
+     .. versionchanged:: 1.7.6
+        For French, ``xelatex`` and ``lualatex`` default to using
+        ``babel``, not ``polyglossia``.
+
+  ``'fontpkg'``
+     Font package inclusion, the default is ``'\\usepackage{times}'`` which
+     uses Times for text, Helvetica for sans serif and Courier for monospace.
+
+     .. versionchanged:: 1.2
+        Defaults to ``''`` when the :confval:`language` uses the Cyrillic
+        script.
+     .. versionchanged:: 2.0
+        Support for individual Greek and Cyrillic letters:
+
+        - In order to support occasional Cyrillic (физика частиц)
+          or Greek letters (Σωματιδιακή φυσική) in
+          a document whose language is English or a  Latin European
+          one, the default set-up is enhanced (only for ``'pdflatex'``
+          engine) to do:
+
+          .. code-block:: latex
+
+             \substitutefont{LGR}{\rmdefault}{cmr}
+             \substitutefont{LGR}{\sfdefault}{cmss}
+             \substitutefont{LGR}{\ttdefault}{cmtt}
+             \substitutefont{X2}{\rmdefault}{cmr}
+             \substitutefont{X2}{\sfdefault}{cmss}
+             \substitutefont{X2}{\ttdefault}{cmtt}
+
+          but this is activated only under the condition that the
+          ``'fontenc'`` key is configured to load the ``LGR`` (Greek)
+          and/or ``X2`` (Cyrillic) pdflatex-font encodings (if the
+          :confval:`language` is set to a Cyrillic language, this
+          ``'fontpkg'`` key must be used as "times" package has no direct
+          support for it; then keep only ``LGR`` lines from the above,
+          if support is needed for Greek in the text).
+
+          The ``\substitutefont`` command is from the eponymous LaTeX
+          package, which is loaded by Sphinx if needed (on Ubuntu xenial it
+          is part of ``texlive-latex-extra`` which is a Sphinx
+          requirement).
+
+          Only if the document actually does contain Unicode Greek letters
+          (in text) or Cyrillic letters, will the above default set-up
+          cause additional requirements for the PDF build.  On Ubuntu
+          xenial, ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and
+          (with the above choice of fonts) the ``cm-super`` (or
+          ``cm-super-minimal``) package.
+
+        - For ``'xelatex'`` and ``'lualatex'``, the default is to
+          use the FreeFont family:  this OpenType font family
+          supports both Cyrillic and Greek scripts and is available as
+          separate Ubuntu xenial package ``fonts-freefont-otf``, it is not
+          needed to install the big package ``texlive-fonts-extra``.
+
+        - ``'platex'`` (Japanese documents) engine supports individual
+          Cyrillic and Greek letters with no need of extra user set-up.
+
+  ``'fncychap'``
+     Inclusion of the "fncychap" package (which makes fancy chapter titles),
+     default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation
+     (this option is slightly customized by Sphinx),
+     ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because
+     the "Bjarne" style uses numbers spelled out in English).  Other
+     "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and
+     "Bjornstrup".  You can also set this to ``''`` to disable fncychap.
+
+     The default is ``''`` for Japanese documents.
+
+  ``'preamble'``
+     Additional preamble content, default empty.  One may move all needed
+     macros into some file :file:`mystyle.tex.txt` of the project source
+     repertory, and get LaTeX to import it at run time::
+
+       'preamble': r'\input{mystyle.tex.txt}',
+       # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
+       'preamble': r'\usepackage{mystyle}',
+
+     It is then needed to set appropriately
+     :confval:`latex_additional_files`, for example::
+
+        latex_additional_files = ["mystyle.sty"]
+
+
+  ``'figure_align'``
+     Latex figure float alignment, default 'htbp' (here, top, bottom, page).
+     Whenever an image doesn't fit into the current page, it will be
+     'floated' into the next page but may be preceded by any other text.
+     If you don't like this behavior, use 'H' which will disable floating
+     and position figures strictly in the order they appear in the source.
+
+     .. versionadded:: 1.3
+
+  ``'atendofbody'``
+     Additional document content (right before the indices), default empty.
+
+     .. versionadded:: 1.5
+
+  ``'footer'``
+     Additional footer content (before the indices), default empty.
+
+     .. deprecated:: 1.5
+        Use ``'atendofbody'`` key instead.
+
+* Keys that don't need to be overridden unless in special cases are:
+
+  ``'extraclassoptions'``
+     The default is the empty string. Example: ``'extraclassoptions':
+     'openany'`` will allow chapters (for documents of the ``'manual'``
+     type) to start on any page.
+
+     .. versionadded:: 1.2
+     .. versionchanged:: 1.6
+        Added this documentation.
+
+  ``'maxlistdepth'``
+     LaTeX allows by default at most 6 levels for nesting list and
+     quote-like environments, with at most 4 enumerated lists, and 4 bullet
+     lists. Setting this key for example to ``'10'`` (as a string) will
+     allow up to 10 nested levels (of all sorts). Leaving it to the empty
+     string means to obey the LaTeX default.
+
+     .. warning::
+
+        - Using this key may prove incompatible with some LaTeX packages
+          or special document classes which do their own list customization.
+
+        - The key setting is silently *ignored* if ``\usepackage{enumitem}``
+          is executed inside the document preamble. Use then rather the
+          dedicated commands of this LaTeX package.
+
+     .. versionadded:: 1.5
+
+  ``'inputenc'``
+     "inputenc" package inclusion, defaults to
+     ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex.
+     Otherwise empty.
+
+     .. versionchanged:: 1.4.3
+        Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
+        compilers.
+
+  ``'cmappkg'``
+     "cmap" package inclusion, default ``'\\usepackage{cmap}'``.
+
+     .. versionadded:: 1.2
+
+  ``'fontenc'``
+     "fontenc" package inclusion, defaults to
+     ``'\\usepackage[T1]{fontenc}'``.
+
+     If ``'pdflatex'`` is the :confval:`latex_engine`, one can add ``LGR``
+     for support of Greek letters in the document, and also ``X2`` (or
+     ``T2A``) for Cyrillic letters, like this:
+
+     .. code-block:: latex
+
+        r'\usepackage[LGR,X2,T1]{fontenc}'
+
+     .. attention::
+
+        Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math
+        mark-up.  This is not the case anymore, and the above must be used
+        (only in case of ``'pdflatex'`` engine) if the source contains such
+        Unicode Greek.
+
+        On Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
+        (for the latter, only if the ``'fontpkg'`` setting is left to its
+        default) are needed for ``LGR`` to work.  In place of ``cm-super``
+        one can install smaller ``cm-super-minimal``, but it requires the
+        LaTeX document to execute ``\usepackage[10pt]{type1ec}`` before
+        loading ``fontenc``.  Thus, use this key with this extra at its
+        start if needed.
+
+     .. versionchanged:: 1.5
+        Defaults to ``'\\usepackage{fontspec}'`` when
+        :confval:`latex_engine` is ``'xelatex'``.
+     .. versionchanged:: 1.6
+        ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``.
+     .. versionchanged:: 2.0
+        ``'lualatex'`` executes
+        ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX
+        ligatures.
+     .. versionchanged:: 2.0
+        Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of
+        occasional Greek or Cyrillic (``'pdflatex'`` only, as this support
+        is provided natively by ``'platex'`` and only requires suitable
+        font with ``'xelatex'/'lualatex'``).
+
+  ``'textgreek'``
+     The default (``'pdflatex'`` only) is
+     ``'\\usepackage{textalpha}'``, but only if ``'fontenc'`` was
+     modified by user to include ``LGR`` option.  If not, the key
+     value will be forced to be the empty string.
+
+     This is needed for ``pdfLaTeX`` to support Unicode input of Greek
+     letters such as φύσις.  Expert users may want to load the ``textalpha``
+     package with its option ``normalize-symbols``.
+
+     .. hint::
+
+        Unicode Greek (but no further Unicode symbols) in :rst:dir:`math`
+        can be supported by ``'pdflatex'`` from setting this key to
+        ``r'\usepackage{textalpha,alphabeta}'``.  Then ``:math:`α``` (U+03B1)
+        will render as :math:`\alpha`.  For wider Unicode support in math
+        input, see the discussion of :confval:`latex_engine`.
+
+     With ``'platex'`` (Japanese),  ``'xelatex'`` or ``'lualatex'``, this
+     key is ignored.
+
+     .. versionadded:: 2.0
+  ``'geometry'``
+     "geometry" package inclusion, the default definition is:
+
+       ``'\\usepackage{geometry}'``
+
+     with an additional ``[dvipdfm]`` for Japanese documents.
+     The Sphinx LaTeX style file executes:
+
+       ``\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}``
+
+     which can be customized via corresponding :ref:`'sphinxsetup' options
+     <latexsphinxsetup>`.
+
+     .. versionadded:: 1.5
+
+     .. versionchanged:: 1.5.2
+        ``dvipdfm`` option if :confval:`latex_engine` is ``'platex'``.
+
+     .. versionadded:: 1.5.3
+        The :ref:`'sphinxsetup' keys for the margins
+        <latexsphinxsetuphmargin>`.
+
+     .. versionchanged:: 1.5.3
+        The location in the LaTeX file has been moved to after
+        ``\usepackage{sphinx}`` and ``\sphinxsetup{..}``, hence also after
+        insertion of ``'fontpkg'`` key. This is in order to handle the paper
+        layout options in a special way for Japanese documents: the text
+        width will be set to an integer multiple of the *zenkaku* width, and
+        the text height to an integer multiple of the baseline. See the
+        :ref:`hmargin <latexsphinxsetuphmargin>` documentation for more.
+
+  ``'hyperref'``
+     "hyperref" package inclusion; also loads package "hypcap" and issues
+     ``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is
+     loaded and before executing the contents of ``'preamble'`` key.
+
+     .. attention::
+
+        Loading of packages "hyperref" and "hypcap" is mandatory.
+
+     .. versionadded:: 1.5
+        Previously this was done from inside :file:`sphinx.sty`.
+
+  ``'maketitle'``
+     "maketitle" call, default ``'\\sphinxmaketitle'``. Override
+     if you want to generate a differently styled title page.
+
+     .. hint::
+
+        If the key value is set to
+        ``r'\newcommand\sphinxbackoftitlepage{<Extra
+        material>}\sphinxmaketitle'``, then ``<Extra material>`` will be
+        typeset on back of title page (``'manual'`` docclass only).
+
+     .. versionchanged:: 1.8.3
+        Original ``\maketitle`` from document class is not overwritten,
+        hence is re-usable as part of some custom setting for this key.
+     .. versionadded:: 1.8.3
+        ``\sphinxbackoftitlepage`` optional macro.  It can also be defined
+        inside ``'preamble'`` key rather than this one.
+
+  ``'releasename'``
+     value that prefixes ``'release'`` element on title page, default
+     ``'Release'``. As for *title* and *author* used in the tuples of
+     :confval:`latex_documents`, it is inserted as LaTeX markup.
+
+  ``'tableofcontents'``
+     "tableofcontents" call, default ``'\\sphinxtableofcontents'`` (it is a
+     wrapper of unmodified ``\tableofcontents``, which may itself be
+     customized by user loaded packages.)
+     Override if
+     you want to generate a different table of contents or put content
+     between the title page and the TOC.
+
+     .. versionchanged:: 1.5
+        Previously the meaning of ``\tableofcontents`` itself was modified
+        by Sphinx. This created an incompatibility with dedicated packages
+        modifying it also such as "tocloft" or "etoc".
+
+  ``'transition'``
+     Commands used to display transitions, default
+     ``'\n\n\\bigskip\\hrule\\bigskip\n\n'``.  Override if you want to
+     display transitions differently.
+
+     .. versionadded:: 1.2
+     .. versionchanged:: 1.6
+        Remove unneeded ``{}`` after ``\\hrule``.
+
+  ``'printindex'``
+     "printindex" call, the last thing in the file, default
+     ``'\\printindex'``.  Override if you want to generate the index
+     differently or append some content after the index. For example
+     ``'\\footnotesize\\raggedright\\printindex'`` is advisable when the
+     index is full of long entries.
+
+  ``'fvset'``
+     Customization of ``fancyvrb`` LaTeX package.  Sphinx does by default
+     ``'fvset': '\\fvset{fontsize=\\small}'``, to adjust for the large
+     character width of the monospace font, used in code-blocks.
+     You may need to modify this if you use custom fonts.
+
+     .. versionadded:: 1.8
+     .. versionchanged:: 2.0
+        Due to new default font choice for ``'xelatex'`` and ``'lualatex'``
+        (FreeFont), Sphinx does ``\\fvset{fontsize=\\small}`` also with these
+        engines (and not ``\\fvset{fontsize=auto}``).
+
+* Keys that are set by other options and therefore should not be overridden
+  are:
+
+  ``'docclass'``
+  ``'classoptions'``
+  ``'title'``
+  ``'release'``
+  ``'author'``
+  ``'makeindex'``
 
-   latex_additional_files = ["mystyle.tex"]
 
 .. _latexsphinxsetup:
 
-The LaTeX style file options
+\\'sphinxsetup\\' key
-----------------------------
+---------------------
 
-The sphinxsetup interface
+The ``'sphinxsetup'`` key of :ref:`latex_elements <latex_elements_confval>`
-~~~~~~~~~~~~~~~~~~~~~~~~~
+provides a LaTeX-type customization interface::
-
-The ``'sphinxsetup'`` key of :confval:`latex_elements` provides a convenient
-interface to the package options of the Sphinx style file::
 
    latex_elements = {
        'sphinxsetup': 'key1=value1, key2=value2, ...',
    }
 
-- some values may be LaTeX macros, then the backslashes must be
+It defaults to empty.  If non-empty, it will be passed as argument to the
-  Python-escaped, or the whole must be a Python raw string,
+``\sphinxsetup`` macro inside the document preamble, like this::
-- LaTeX boolean keys require *lowercase* ``true`` or ``false`` values,
-- spaces around the commas and equal signs are ignored, spaces inside LaTeX
-  macros may be significant.
-
-If non-empty, it will be passed as argument to the ``\sphinxsetup`` macro
-inside the document preamble, like this::
 
    \usepackage{sphinx}
    \sphinxsetup{key1=value1, key2=value2,...}
 
 .. versionadded:: 1.5
 
-It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro
+.. hint::
-directly into the body of the document, via the help of the :rst:dir:`raw`
-directive. This is what is done for this documentation, for local styling
-of this chapter in the PDF output::
 
-   .. raw:: latex
+   It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro
+   directly into the body of the document, via the help of the :rst:dir:`raw`
+   directive.  Here is how this present chapter is styled in the PDF output::
 
-      \begingroup
+     .. raw:: latex
-      \sphinxsetup{%
-            verbatimwithframe=false,
-            VerbatimColor={named}{OldLace},
-            TitleColor={named}{DarkGoldenrod},
-            hintBorderColor={named}{LightCoral},
-            attentionborder=3pt,
-            attentionBorderColor={named}{Crimson},
-            attentionBgColor={named}{FloralWhite},
-            noteborder=2pt,
-            noteBorderColor={named}{Olive},
-            cautionborder=3pt,
-            cautionBorderColor={named}{Cyan},
-            cautionBgColor={named}{LightCyan}}
 
-at the start of the chapter and::
+        \begingroup
+        \sphinxsetup{%
+              verbatimwithframe=false,
+              VerbatimColor={named}{OldLace},
+              TitleColor={named}{DarkGoldenrod},
+              hintBorderColor={named}{LightCoral},
+              attentionborder=3pt,
+              attentionBorderColor={named}{Crimson},
+              attentionBgColor={named}{FloralWhite},
+              noteborder=2pt,
+              noteBorderColor={named}{Olive},
+              cautionborder=3pt,
+              cautionBorderColor={named}{Cyan},
+              cautionBgColor={named}{LightCyan}}
 
-    .. raw:: latex
+   at the start of the chapter and::
 
-       \endgroup
+     .. raw:: latex
 
-at its end.
+        \endgroup
 
-.. note::
+   at its end.
 
-   The colors above are made available via the ``svgnames`` option of
+   The colors used in the above are provided by the ``svgnames`` option of the
-   the "xcolor" package::
+   "xcolor" package::
 
       latex_elements = {
           'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
       }
 
 
-The available styling options
+LaTeX boolean keys require *lowercase* ``true`` or ``false`` values.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Spaces around the commas and equal signs are ignored, spaces inside LaTeX
+macros may be significant.
 
 .. _latexsphinxsetuphmargin:
 
@@ -189,14 +564,25 @@ The available styling options
     default ``true``. Tells whether long lines in :rst:dir:`code-block`\ 's
     contents should wrap.
 
+``literalblockcappos``
+    default ``t`` for "top". Decides the caption position. Alternative is
+    ``b`` ("bottom").
+
+    .. versionadded:: 1.7
+
 ``verbatimhintsturnover``
-    default ``false``. If ``true``, code-blocks display "continued on next
+    default ``true``. If ``true``, code-blocks display "continued on next
     page", "continued from previous page" hints in case of pagebreaks.
 
     .. versionadded:: 1.6.3
-       the default will change to ``true`` at 1.7 and horizontal positioning
+    .. versionchanged:: 1.7
-       of continuation hints (currently right aligned only) will be
+       the default changed from ``false`` to ``true``.
-       customizable.
+
+``verbatimcontinuedalign``, ``verbatimcontinuesalign``
+    default ``r``. Horizontal position relative to the framed contents:
+    either ``l`` (left aligned), ``r`` (right aligned) or ``c`` (centered).
+
+    .. versionadded:: 1.7
 
 ``parsedliteralwraps``
     default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's
@@ -255,6 +641,16 @@ The available styling options
 ``VerbatimBorderColor``
     default ``{rgb}{0,0,0}``. The frame color, defaults to black.
 
+``VerbatimHighlightColor``
+    default ``{rgb}{0.878,1,1}``. The color for highlighted lines.
+
+    .. versionadded:: 1.6.6
+
+.. note::
+
+   Starting with this colour key, and for all others coming next, the actual
+   names declared to "color" or "xcolor" are prefixed with "sphinx".
+
 ``verbatimsep``
     default ``\fboxsep``. The separation between code lines and the frame.
 
@@ -276,11 +672,6 @@ The available styling options
     default ``{rgb}{0,0,0}`` (black). The colour for the two horizontal rules
     used by Sphinx in LaTeX for styling a :dudir:`note` type admonition.
 
-.. note::
-
-   The actual colour names declared to "color" or "xcolor" are prefixed with
-   "sphinx".
-
 ``noteborder``, ``hintborder``, ``importantborder``, ``tipborder``
     default ``0.5pt``. The width of the two horizontal rules.
 
@@ -333,9 +724,9 @@ The available styling options
                                ``attentionBgColor``, ``dangerBgColor``,
                                ``errorBgColor``
 
-.. |warningborders| replace:: ``warningBorder``, ``cautionBorder``,
+.. |warningborders| replace:: ``warningborder``, ``cautionborder``,
-                              ``attentionBorder``, ``dangerBorder``,
+                              ``attentionborder``, ``dangerborder``,
-                              ``errorBorder``
+                              ``errorborder``
 
 LaTeX macros and environments
 -----------------------------
@@ -344,6 +735,8 @@ Here are some macros from the package file :file:`sphinx.sty` and class files
 :file:`sphinxhowto.cls`, :file:`sphinxmanual.cls`, which have public names
 thus allowing redefinitions. Check the respective files for the defaults.
 
+.. _latex-macros:
+
 Macros
 ~~~~~~
 
@@ -356,10 +749,9 @@ Macros
      with LaTeX packages.
 - more text styling: ``\sphinxstyle<bar>`` with ``<bar>`` one of
   ``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
-  ``sidebartitle``, ``othertitle``, ``sidebarsubtitle``,
+  ``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``theadfamily``,
-  ``theadfamily``, ``emphasis``, ``literalemphasis``, ``strong``,
+  ``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``,
-  ``literalstrong``, ``abbreviation``, ``literalintitle``, ``codecontinued``,
+  ``abbreviation``, ``literalintitle``, ``codecontinued``, ``codecontinues``
-  ``codecontinues``.
 
   .. versionadded:: 1.5
      these macros were formerly hard-coded as non customizable ``\texttt``,
@@ -369,21 +761,35 @@ Macros
      multiple paragraphs in header cells of tables.
   .. versionadded:: 1.6.3
      ``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``.
-- by default the Sphinx style file ``sphinx.sty`` executes the command
-  ``\fvset{fontsize=\small}`` as part of its configuration of
-  ``fancyvrb.sty``. This may be overriden for example via
-  ``\fvset{fontsize=auto}`` which will let code listings use the ambient font
-  size. Refer to ``fancyvrb.sty``'s documentation for further keys.
-
-  .. versionadded:: 1.5
 - the table of contents is typeset via ``\sphinxtableofcontents`` which is a
-  wrapper (whose definition can be found in :file:`sphinxhowto.cls` or in
+  wrapper (defined differently in :file:`sphinxhowto.cls` and in
-  :file:`sphinxmanual.cls`) of standard ``\tableofcontents``.
+  :file:`sphinxmanual.cls`) of standard ``\tableofcontents``.  The macro
+  ``\sphinxtableofcontentshook`` is executed during its expansion right before
+  ``\tableofcontents`` itself.
 
   .. versionchanged:: 1.5
      formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
-- the ``\maketitle`` command is redefined by the class files
+  .. versionchanged:: 2.0
-  :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`.
+     hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` formerly
+     done during loading of ``'manual'`` docclass are now executed later via
+     ``\sphinxtableofcontentshook``.  This macro is also executed by the
+     ``'howto'`` docclass, but defaults to empty with it.
+- a custom ``\sphinxmaketitle`` is defined in the class files
+  :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls` and is used as
+  default setting of ``'maketitle'`` :confval:`latex_elements` key.
+
+  .. versionchanged:: 1.8.3
+     formerly, ``\maketitle`` from LaTeX document class was modified by
+     Sphinx.
+- for ``'manual'`` docclass a macro ``\sphinxbackoftitlepage``, if it is
+  defined, gets executed at end of ``\sphinxmaketitle``, before the final
+  ``\clearpage``.  Use either the ``'maketitle'`` key or the ``'preamble'`` key
+  of :confval:`latex_elements` to add a custom definition of
+  ``\sphinxbackoftitlepage``.
+
+  .. versionadded:: 1.8.3
+- the citation reference is typeset via ``\sphinxcite`` which is a wrapper
+  of standard ``\cite``.
 
 Environments
 ~~~~~~~~~~~~
@@ -430,6 +836,11 @@ Environments
   .. versionadded:: 1.5
      options ``verbatimwithframe``, ``verbatimwrapslines``,
      ``verbatimsep``, ``verbatimborder``.
+  .. versionadded:: 1.6.6
+     support for ``:emphasize-lines:`` option
+  .. versionadded:: 1.6.6
+     easier customizability of the formatting via exposed to user LaTeX macros
+     such as ``\sphinxVerbatimHighlightLine``.
 - the bibliography uses ``sphinxthebibliography`` and the Python Module index
   as well as the general index both use ``sphinxtheindex``; these environments
   are wrappers of the ``thebibliography`` and respectively ``theindex``
@@ -451,7 +862,6 @@ Miscellany
   .. versionchanged:: 1.5
      formerly, use of *fncychap* with other styles than ``Bjarne`` was
      dysfunctional.
-- check file :file:`sphinx.sty` for more...
 
 .. hint::
 

doc/make.bat

@@ -3,7 +3,7 @@
 REM Command file for Sphinx documentation
 
 if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=python ../sphinx-build.py
+	set SPHINXBUILD=python ../sphinx/cmd/build.py
 )
 set SOURCEDIR=.
 set BUILDDIR=_build

doc/man/sphinx-apidoc.rst

@@ -4,7 +4,7 @@ sphinx-apidoc
 Synopsis
 --------
 
-**sphinx-apidoc** [*options*] -o <*outputdir*> <*sourcedir*> [*pathnames* ...]
+**sphinx-apidoc** [*OPTIONS*] -o <*OUTPUT_PATH*> <*MODULE_PATH*> [*EXCLUDE_PATTERN*, ...]
 
 Description
 -----------
@@ -13,9 +13,12 @@ Description
 that, using the :rst:dir:`autodoc` extension, document a whole package in the
 style of other automatic API documentation tools.
 
-*sourcedir* is the path to a Python package to document, and *outputdir* is the
+*MODULE_PATH* is the path to a Python package to document, and *OUTPUT_PATH* is
-directory where the generated sources are placed. Any *pathnames* given are
+the directory where the generated sources are placed. Any *EXCLUDE_PATTERN*\s
-paths to be excluded from the generation.
+given are `fnmatch-style`_ file and/or directory patterns that will be excluded
+from generation.
+
+.. _fnmatch-style: https://docs.python.org/3/library/fnmatch.html
 
 .. warning::
 
@@ -31,13 +34,13 @@ Options
 
 .. program:: sphinx-apidoc
 
-.. option:: -o <outputdir>
+.. option:: -o <OUTPUT_PATH>
 
    Directory to place the output files. If it does not exist, it is created.
 
 .. option:: -f, --force
 
-   Force overwritting of any existing generated files.
+   Force overwriting of any existing generated files.
 
 .. option:: -l, --follow-links
 
@@ -51,10 +54,14 @@ Options
 
    Suffix for the source files generated. Defaults to ``rst``.
 
-.. option:: -d <maxdepth>
+.. option:: -d <MAXDEPTH>
 
    Maximum depth for the generated table of contents file.
 
+.. option:: --tocfile
+
+   Filename for a table of contents file. Defaults to ``modules``.
+
 .. option:: -T, --no-toc
 
    Do not create a table of contents file. Ignored when :option:`--full` is
@@ -91,7 +98,7 @@ Options
 
    Interpret paths recursively according to PEP-0420.
 
-.. option:: -M
+.. option:: -M, --module-first
 
    Put module documentation before submodule documentation.
 
@@ -118,7 +125,17 @@ These options are used when :option:`--full` is specified:
 
    Sets the project release to put in generated files (see :confval:`release`).
 
+Environment
+-----------
+
+.. envvar:: SPHINX_APIDOC_OPTIONS
+
+   A comma-separated list of option to append to generated ``automodule``
+   directives. Defaults to ``members,undoc-members,show-inheritance``.
+
 See also
 --------
 
 :manpage:`sphinx-build(1)`, :manpage:`sphinx-autogen(1)`
+
+.. _fnmatch: https://docs.python.org/3/library/fnmatch.html

doc/man/sphinx-autogen.rst

@@ -15,7 +15,7 @@ that, using the :rst:dir:`autodoc` extension, document items included in
 
 *sourcefile* is the path to one or more reStructuredText documents containing
 :rst:dir:`autosummary` entries with the ``:toctree::`` option set. *sourcefile*
-can be an :py:module:`fnmatch`-style pattern.
+can be an :py:mod:`fnmatch`-style pattern.
 
 Options
 -------
@@ -73,7 +73,7 @@ If you run the following:
 
 .. code-block:: bash
 
-    $ sphinx-autodoc doc/index.rst
+    $ PYTHONPATH=. sphinx-autodoc doc/index.rst
 
 then the following stub files will be created in ``docs``::
 

doc/man/sphinx-build.rst

@@ -86,8 +86,31 @@ Options
      Build compact pretty-printed "pseudo-XML" files displaying the
      internal structure of the intermediate document trees.
 
-   See :ref:`builders` for a list of all builders shipped with Sphinx.
+   See :doc:`/usage/builders/index` for a list of all builders shipped with
-   Extensions can add their own builders.
+   Sphinx.  Extensions can add their own builders.
+
+.. _make_mode:
+
+.. option:: -M buildername
+
+   Alternative to :option:`-b`. Uses the Sphinx :program:`make_mode` module,
+   which provides the same build functionality as a default :ref:`Makefile or
+   Make.bat <makefile_options>`. In addition to all Sphinx
+   :doc:`/usage/builders/index`, the following build pipelines are available:
+
+   **latexpdf**
+     Build LaTeX files and run them through :program:`pdflatex`, or as per
+     :confval:`latex_engine` setting.
+     If :confval:`language` is set to ``'ja'``, will use automatically
+     the :program:`platex/dvipdfmx` latex to PDF pipeline.
+
+   **info**
+     Build Texinfo files and run them through :program:`makeinfo`.
+
+   .. important::
+      Sphinx only recognizes the ``-M`` option if it is placed first.
+
+   .. versionadded:: 1.2.1
 
 .. option:: -a
 
@@ -120,11 +143,15 @@ Options
 
    Distribute the build over *N* processes in parallel, to make building on
    multiprocessor machines more effective.  Note that not all parts and not all
-   builders of Sphinx can be parallelized.
+   builders of Sphinx can be parallelized.  If ``auto`` argument is given,
+   Sphinx uses the number of CPUs as *N*.
 
    .. versionadded:: 1.2
       This option should be considered *experimental*.
 
+   .. versionchanged:: 1.7
+      Support ``auto`` argument.
+
 .. option:: -c path
 
    Don't look for the :file:`conf.py` in the source directory, but use the given
@@ -202,6 +229,13 @@ Options
    Turn warnings into errors.  This means that the build stops at the first
    warning and ``sphinx-build`` exits with exit status 1.
 
+.. option:: --keep-going
+
+   With -W option, keep going processing when getting warnings to the end
+   of build, and ``sphinx-build`` exits with exit status 1.
+
+   .. versionadded:: 1.8
+
 .. option:: -T
 
    Display the full traceback when an unhandled exception occurs.  Otherwise,
@@ -235,6 +269,8 @@ The :program:`sphinx-build` refers following environment variables:
    A path to make command.  A command name is also allowed.
    :program:`sphinx-build` uses it to invoke sub-build process on make-mode.
 
+.. _makefile_options:
+
 .. rubric:: Makefile Options
 
 The :file:`Makefile` and :file:`make.bat` files created by
@@ -244,7 +280,16 @@ variables to customize behavior:
 
 .. describe:: PAPER
 
-   The value for '"papersize"` key of :confval:`latex_elements`.
+   This sets the ``'papersize'`` key of :confval:`latex_elements`:
+   i.e. ``PAPER=a4`` sets it to ``'a4paper'`` and ``PAPER=letter`` to
+   ``'letterpaper'``.
+
+   .. note::
+
+      Usage of this environment variable got broken at Sphinx 1.5 as
+      ``a4`` or ``letter`` ended up as option to LaTeX document in
+      place of the needed ``a4paper``, resp. ``letterpaper``.  Fixed at
+      1.7.7.
 
 .. describe:: SPHINXBUILD
 

doc/man/sphinx-quickstart.rst

@@ -20,7 +20,7 @@ Options
 
 .. option:: -q, --quiet
 
-   Quiet mode that will skips interactive wizard to specify options.
+   Quiet mode that will skip interactive wizard to specify options.
    This option requires `-p`, `-a` and `-v` options.
 
 .. option:: -h, --help, --version
@@ -112,15 +112,20 @@ Options
 
    Enable `sphinx.ext.viewcode` extension.
 
+.. option:: --ext-githubpages
+
+   Enable `sphinx.ext.githubpages` extension.
+
 .. option:: --extensions=EXTENSIONS
 
-   Enable arbitary extensions.
+   Enable arbitrary extensions.
 
 .. rubric:: Makefile and Batchfile Creation Options
 
-.. option:: --use-make-mode, --no-use-make-mode
+.. option:: --use-make-mode (-m), --no-use-make-mode (-M)
 
-   Makefile/make.bat uses (or not use) make-mode. Default is use.
+   :file:`Makefile/make.bat` uses (or doesn't use) :ref:`make-mode <make_mode>`.
+   Default is ``use``, which generates a more concise :file:`Makefile/make.bat`.
 
    .. versionchanged:: 1.5
       make-mode is default.

doc/markdown.rst

@@ -1,45 +0,0 @@
-.. highlightlang:: python
-
-.. _markdown:
-
-Markdown support
-================
-
-`Markdown <https://daringfireball.net/projects/markdown/>`__ is a lightweight markup language with a simplistic plain
-text formatting syntax.
-It exists in many syntactically different *flavors*.
-To support Markdown-based documentation, Sphinx can use
-`recommonmark <http://recommonmark.readthedocs.io/en/latest/index.html>`__.
-recommonmark is a Docutils bridge to `CommonMark-py <https://github.com/rtfd/CommonMark-py>`__, a
-Python package for parsing the `CommonMark <http://commonmark.org/>`__ Markdown flavor.
-
-
-Configuration
--------------
-
-To configure your Sphinx project for Markdown support, proceed as follows:
-
-#. Install recommonmark:
-
-   ::
-
-      pip install recommonmark
-
-#. Add the Markdown parser to the ``source_parsers`` configuration variable in your Sphinx configuration file:
-
-   ::
-
-      source_parsers = {
-         '.md': 'recommonmark.parser.CommonMarkParser',
-      }
-
-   You can replace `.md` with a filename extension of your choice.
-
-#. Add the Markdown filename extension to the  ``source_suffix`` configuration variable:
-
-   ::
-
-      source_suffix = ['.rst', '.md']
-
-#. You can further configure recommonmark to allow custom syntax that standard CommonMark doesn't support. Read more in
-   the `recommonmark documentation <http://recommonmark.readthedocs.io/en/latest/auto_structify.html>`__.

doc/markup/code.rst

@@ -1,268 +0,0 @@
-.. highlight:: rest
-
-.. _code-examples:
-
-Showing code examples
----------------------
-
-.. index:: pair: code; examples
-           single: sourcecode
-
-Examples of Python source code or interactive sessions are represented using
-standard reST literal blocks.  They are started by a ``::`` at the end of the
-preceding paragraph and delimited by indentation.
-
-Representing an interactive session requires including the prompts and output
-along with the Python code.  No special markup is required for interactive
-sessions.  After the last line of input or output presented, there should not be
-an "unused" primary prompt; this is an example of what *not* to do::
-
-   >>> 1 + 1
-   2
-   >>>
-
-Syntax highlighting is done with `Pygments <http://pygments.org>`_ and handled
-in a smart way:
-
-* There is a "highlighting language" for each source file.  Per default, this is
-  ``'python'`` as the majority of files will have to highlight Python snippets,
-  but the doc-wide default can be set with the :confval:`highlight_language`
-  config value.
-
-* Within Python highlighting mode, interactive sessions are recognized
-  automatically and highlighted appropriately.  Normal Python code is only
-  highlighted if it is parseable (so you can use Python as the default, but
-  interspersed snippets of shell commands or other code blocks will not be
-  highlighted as Python).
-
-* The highlighting language can be changed using the ``highlight`` directive,
-  used as follows:
-
-  .. rst:directive:: .. highlight:: language
-
-     Example::
-
-        .. highlight:: c
-
-     This language is used until the next ``highlight`` directive is encountered.
-
-* For documents that have to show snippets in different languages, there's also
-  a :rst:dir:`code-block` directive that is given the highlighting language
-  directly:
-
-  .. rst:directive:: .. code-block:: language
-
-     Use it like this::
-
-        .. code-block:: ruby
-
-           Some Ruby code.
-
-     The directive's alias name :rst:dir:`sourcecode` works as well.
-
-* The valid values for the highlighting language are:
-
-  * ``none`` (no highlighting)
-  * ``python`` (the default when :confval:`highlight_language` isn't set)
-  * ``guess`` (let Pygments guess the lexer based on contents, only works with
-    certain well-recognizable languages)
-  * ``rest``
-  * ``c``
-  * ... and any other `lexer alias that Pygments supports
-    <http://pygments.org/docs/lexers/>`_.
-
-* If highlighting with the selected language fails (i.e. Pygments emits an
-  "Error" token), the block is not highlighted in any way.
-
-Line numbers
-^^^^^^^^^^^^
-
-Pygments can generate line numbers for code blocks.  For
-automatically-highlighted blocks (those started by ``::``), line numbers must be
-switched on in a :rst:dir:`highlight` directive, with the ``linenothreshold``
-option::
-
-   .. highlight:: python
-      :linenothreshold: 5
-
-This will produce line numbers for all code blocks longer than five lines.
-
-For :rst:dir:`code-block` blocks, a ``linenos`` flag option can be given to
-switch on line numbers for the individual block::
-
-   .. code-block:: ruby
-      :linenos:
-
-      Some more Ruby code.
-
-The first line number can be selected with the ``lineno-start`` option.  If
-present, ``linenos`` is automatically activated as well::
-
-   .. code-block:: ruby
-      :lineno-start: 10
-
-      Some more Ruby code, with line numbering starting at 10.
-
-Additionally, an ``emphasize-lines`` option can be given to have Pygments
-emphasize particular lines::
-
-    .. code-block:: python
-       :emphasize-lines: 3,5
-
-       def some_function():
-           interesting = False
-           print 'This line is highlighted.'
-           print 'This one is not...'
-           print '...but this one is.'
-
-.. versionchanged:: 1.1
-   ``emphasize-lines`` has been added.
-
-.. versionchanged:: 1.3
-   ``lineno-start`` has been added.
-
-
-Includes
-^^^^^^^^
-
-.. rst:directive:: .. literalinclude:: filename
-
-   Longer displays of verbatim text may be included by storing the example text
-   in an external file containing only plain text.  The file may be included
-   using the ``literalinclude`` directive. [1]_ For example, to include the
-   Python source file :file:`example.py`, use::
-
-      .. literalinclude:: example.py
-
-   The file name is usually relative to the current file's path.  However, if it
-   is absolute (starting with ``/``), it is relative to the top source
-   directory.
-
-   Tabs in the input are expanded if you give a ``tab-width`` option with the
-   desired tab width.
-
-   Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag
-   option to switch on line numbers, the ``lineno-start`` option to select the
-   first line number, the ``emphasize-lines`` option to emphasize particular
-   lines, and a ``language`` option to select a language different from the
-   current file's standard language.  Example with options::
-
-      .. literalinclude:: example.rb
-         :language: ruby
-         :emphasize-lines: 12,15-18
-         :linenos:
-
-   Include files are assumed to be encoded in the :confval:`source_encoding`.
-   If the file has a different encoding, you can specify it with the
-   ``encoding`` option::
-
-      .. literalinclude:: example.py
-         :encoding: latin-1
-
-   The directive also supports including only parts of the file.  If it is a
-   Python module, you can select a class, function or method to include using
-   the ``pyobject`` option::
-
-      .. literalinclude:: example.py
-         :pyobject: Timer.start
-
-   This would only include the code lines belonging to the ``start()`` method in
-   the ``Timer`` class within the file.
-
-   Alternately, you can specify exactly which lines to include by giving a
-   ``lines`` option::
-
-      .. literalinclude:: example.py
-         :lines: 1,3,5-10,20-
-
-   This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.
-
-   Another way to control which part of the file is included is to use the
-   ``start-after`` and ``end-before`` options (or only one of them).  If
-   ``start-after`` is given as a string option, only lines that follow the first
-   line containing that string are included.  If ``end-before`` is given as a
-   string option, only lines that precede the first lines containing that string
-   are included.
-
-   With lines selected using ``start-after`` it is still possible to use
-   ``lines``, the first allowed line having by convention the line number ``1``.
-
-   When lines have been selected in any of the ways described above, the
-   line numbers in ``emphasize-lines`` also refer to the selection, with the
-   first selected line having number ``1``.
-
-   When specifying particular parts of a file to display, it can be useful to
-   display the original line numbers. This can be done using the
-   ``lineno-match`` option, which is however allowed only when the selection
-   consists of contiguous lines.
-
-   You can prepend and/or append a line to the included code, using the
-   ``prepend`` and ``append`` option, respectively.  This is useful e.g. for
-   highlighting PHP code that doesn't include the ``<?php``/``?>`` markers.
-
-
-   If you want to show the diff of the code, you can specify the old
-   file by giving a ``diff`` option::
-
-      .. literalinclude:: example.py
-         :diff: example.py.orig
-
-   This shows the diff between example.py and example.py.orig with unified diff
-   format.
-
-   .. versionadded:: 0.4.3
-      The ``encoding`` option.
-   .. versionadded:: 0.6
-      The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options,
-      as well as support for absolute filenames.
-   .. versionadded:: 1.0
-      The ``prepend`` and ``append`` options, as well as ``tab-width``.
-   .. versionadded:: 1.3
-      The ``diff`` option.
-      The ``lineno-match`` option.
-   .. versionchanged:: 1.6
-      With both ``start-after`` and ``lines`` in use, the first line as per
-      ``start-after`` is considered to be with line number ``1`` for ``lines``.
-
-Caption and name
-^^^^^^^^^^^^^^^^
-
-.. versionadded:: 1.3
-
-A ``caption`` option can be given to show that name before the code block.
-A ``name`` option can be provided implicit target name that can be referenced
-by using :rst:role:`ref`.
-For example::
-
-   .. code-block:: python
-      :caption: this.py
-      :name: this-py
-
-      print 'Explicit is better than implicit.'
-
-
-:rst:dir:`literalinclude` also supports the ``caption`` and ``name`` option.
-``caption`` has an additional feature that if you leave the value empty, the shown
-filename will be exactly the one given as an argument.
-
-
-Dedent
-^^^^^^
-
-.. versionadded:: 1.3
-
-A ``dedent`` option can be given to strip indentation characters from the code
-block. For example::
-
-   .. literalinclude:: example.rb
-      :language: ruby
-      :dedent: 4
-      :lines: 10-15
-
-:rst:dir:`code-block` also supports the ``dedent`` option.
-
-
-.. rubric:: Footnotes
-
-.. [1] There is a standard ``.. include`` directive, but it raises errors if the
-       file is not found.  This one only emits a warning.

doc/markup/index.rst

@@ -1,19 +0,0 @@
-.. _sphinxmarkup:
-
-Sphinx Markup Constructs
-========================
-
-Sphinx adds a lot of new directives and interpreted text roles to `standard reST
-markup`_.  This section contains the reference material for these facilities.
-
-.. toctree::
-
-   toctree
-   para
-   code
-   inline
-   misc
-
-More markup is added by :ref:`domains`.
-
-.. _standard reST markup: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

doc/markup/misc.rst

@@ -1,339 +0,0 @@
-.. highlight:: rest
-
-Miscellaneous markup
-====================
-
-.. _metadata:
-
-File-wide metadata
-------------------
-
-reST has the concept of "field lists"; these are a sequence of fields marked up
-like this::
-
-   :fieldname: Field content
-
-A field list near the top of a file is parsed by docutils as the "docinfo"
-which is normally used to record the author, date of publication and other
-metadata.  *In Sphinx*, a field list preceding any other markup is moved from
-the docinfo to the Sphinx environment as document metadata and is not displayed
-in the output; a field list appearing after the document title will be part of
-the docinfo as normal and will be displayed in the output.
-
-At the moment, these metadata fields are recognized:
-
-``tocdepth``
-   The maximum depth for a table of contents of this file.
-
-   .. versionadded:: 0.4
-
-``nocomments``
-   If set, the web application won't display a comment form for a page generated
-   from this source file.
-
-``orphan``
-   If set, warnings about this file not being included in any toctree will be
-   suppressed.
-
-   .. versionadded:: 1.0
-
-
-Meta-information markup
------------------------
-
-.. rst:directive:: .. sectionauthor:: name <email>
-
-   Identifies the author of the current section.  The argument should include
-   the author's name such that it can be used for presentation and email
-   address.  The domain name portion of the address should be lower case.
-   Example::
-
-      .. sectionauthor:: Guido van Rossum <guido@python.org>
-
-   By default, this markup isn't reflected in the output in any way (it helps
-   keep track of contributions), but you can set the configuration value
-   :confval:`show_authors` to ``True`` to make them produce a paragraph in the
-   output.
-
-
-.. rst:directive:: .. codeauthor:: name <email>
-
-   The :rst:dir:`codeauthor` directive, which can appear multiple times, names
-   the authors of the described code, just like :rst:dir:`sectionauthor` names
-   the author(s) of a piece of documentation.  It too only produces output if
-   the :confval:`show_authors` configuration value is ``True``.
-
-
-Index-generating markup
------------------------
-
-Sphinx automatically creates index entries from all object descriptions (like
-functions, classes or attributes) like discussed in :ref:`domains`.
-
-However, there is also explicit markup available, to make the index more
-comprehensive and enable index entries in documents where information is not
-mainly contained in information units, such as the language reference.
-
-.. rst:directive:: .. index:: <entries>
-
-   This directive contains one or more index entries.  Each entry consists of a
-   type and a value, separated by a colon.
-
-   For example::
-
-      .. index::
-         single: execution; context
-         module: __main__
-         module: sys
-         triple: module; search; path
-
-      The execution context
-      ---------------------
-
-      ...
-
-   This directive contains five entries, which will be converted to entries in
-   the generated index which link to the exact location of the index statement
-   (or, in case of offline media, the corresponding page number).
-
-   Since index directives generate cross-reference targets at their location in
-   the source, it makes sense to put them *before* the thing they refer to --
-   e.g. a heading, as in the example above.
-
-   The possible entry types are:
-
-   single
-      Creates a single index entry.  Can be made a subentry by separating the
-      subentry text with a semicolon (this notation is also used below to
-      describe what entries are created).
-   pair
-      ``pair: loop; statement`` is a shortcut that creates two index entries,
-      namely ``loop; statement`` and ``statement; loop``.
-   triple
-      Likewise, ``triple: module; search; path`` is a shortcut that creates
-      three index entries, which are ``module; search path``, ``search; path,
-      module`` and ``path; module search``.
-   see
-      ``see: entry; other`` creates an index entry that refers from ``entry`` to
-      ``other``.
-   seealso
-      Like ``see``, but inserts "see also" instead of "see".
-   module, keyword, operator, object, exception, statement, builtin
-      These all create two index entries.  For example, ``module: hashlib``
-      creates the entries ``module; hashlib`` and ``hashlib; module``.  (These
-      are Python-specific and therefore deprecated.)
-
-   You can mark up "main" index entries by prefixing them with an exclamation
-   mark.  The references to "main" entries are emphasized in the generated
-   index.  For example, if two pages contain ::
-
-      .. index:: Python
-
-   and one page contains ::
-
-      .. index:: ! Python
-
-   then the backlink to the latter page is emphasized among the three backlinks.
-
-   For index directives containing only "single" entries, there is a shorthand
-   notation::
-
-      .. index:: BNF, grammar, syntax, notation
-
-   This creates four index entries.
-
-   .. versionchanged:: 1.1
-      Added ``see`` and ``seealso`` types, as well as marking main entries.
-
-.. rst:role:: index
-
-   While the :rst:dir:`index` directive is a block-level markup and links to the
-   beginning of the next paragraph, there is also a corresponding role that sets
-   the link target directly where it is used.
-
-   The content of the role can be a simple phrase, which is then kept in the
-   text and used as an index entry.  It can also be a combination of text and
-   index entry, styled like with explicit targets of cross-references.  In that
-   case, the "target" part can be a full entry as described for the directive
-   above.  For example::
-
-      This is a normal reST :index:`paragraph` that contains several
-      :index:`index entries <pair: index; entry>`.
-
-   .. versionadded:: 1.1
-
-
-.. _tags:
-
-Including content based on tags
--------------------------------
-
-.. rst:directive:: .. only:: <expression>
-
-   Include the content of the directive only if the *expression* is true.  The
-   expression should consist of tags, like this::
-
-      .. only:: html and draft
-
-   Undefined tags are false, defined tags (via the ``-t`` command-line option or
-   within :file:`conf.py`, see :ref:`here <conf-tags>`) are true.  Boolean
-   expressions, also using parentheses (like ``html and (latex or draft)``) are
-   supported.
-
-   The *format* and the *name* of the current builder (``html``, ``latex`` or
-   ``text``) are always set as a tag [#]_.  To make the distinction between
-   format and name explicit, they are also added with the prefix ``format_`` and
-   ``builder_``, e.g. the epub builder defines the tags  ``html``, ``epub``,
-   ``format_html`` and ``builder_epub``.
-
-   These standard tags are set *after* the configuration file is read, so they
-   are not available there.
-
-   All tags must follow the standard Python identifier syntax as set out in
-   the `Identifiers and keywords
-   <https://docs.python.org/2/reference/lexical_analysis.html#identifiers>`_
-   documentation.  That is, a tag expression may only consist of tags that
-   conform to the syntax of Python variables.  In ASCII, this consists of the
-   uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_``
-   and, except for the first character, the digits ``0`` through ``9``.
-
-   .. versionadded:: 0.6
-   .. versionchanged:: 1.2
-      Added the name of the builder and the prefixes.
-
-   .. warning::
-
-      This directive is designed to control only content of document.  It could
-      not control sections, labels and so on.
-
-
-Tables
-------
-
-Use :ref:`reStructuredText tables <rst-tables>`, i.e. either
-
-- grid table syntax (:duref:`ref <grid-tables>`),
-- simple table syntax (:duref:`ref <simple-tables>`),
-- :dudir:`csv-table` syntax,
-- or :dudir:`list-table` syntax.
-
-The :dudir:`table` directive serves as optional wrapper of the *grid* and
-*simple* syntaxes.
-
-They work fine in
-HTML output, however there are some gotchas when using tables in LaTeX: the
-column width is hard to determine correctly automatically.  For this reason, the
-following directive exists:
-
-.. rst:directive:: .. tabularcolumns:: column spec
-
-   This directive gives a "column spec" for the next table occurring in the
-   source file.  The spec is the second argument to the LaTeX ``tabulary``
-   package's environment (which Sphinx uses to translate tables).  It can have
-   values like ::
-
-      |l|l|l|
-
-   which means three left-adjusted, nonbreaking columns.  For columns with
-   longer text that should automatically be broken, use either the standard
-   ``p{width}`` construct, or tabulary's automatic specifiers:
-
-   +-----+------------------------------------------+
-   |``L``| flush left column with automatic width   |
-   +-----+------------------------------------------+
-   |``R``| flush right column with automatic width  |
-   +-----+------------------------------------------+
-   |``C``| centered column with automatic width     |
-   +-----+------------------------------------------+
-   |``J``| justified column with automatic width    |
-   +-----+------------------------------------------+
-
-   The automatic widths of the ``LRCJ`` columns are attributed by ``tabulary``
-   in proportion to the observed shares in a first pass where the table cells
-   are rendered at their natural "horizontal" widths.
-
-   By default, Sphinx uses a table layout with ``J`` for every column.
-
-   .. versionadded:: 0.3
-
-   .. versionchanged:: 1.6
-      Merged cells may now contain multiple paragraphs and are much better
-      handled, thanks to custom Sphinx LaTeX macros. This novel situation
-      motivated the switch to ``J`` specifier and not ``L`` by default.
-
-   .. hint::
-
-      Sphinx actually uses ``T`` specifier having done ``\newcolumntype{T}{J}``.
-      To revert to previous default, insert ``\newcolumntype{T}{L}`` in the
-      LaTeX preamble (see :confval:`latex_elements`).
-
-      A frequent issue with tabulary is that columns with little contents are
-      "squeezed". The minimal column width is a tabulary parameter called
-      ``\tymin``. You may set it globally in the LaTeX preamble via
-      ``\setlength{\tymin}{40pt}`` for example.
-
-      Else, use the :rst:dir:`tabularcolumns` directive with an explicit
-      ``p{40pt}`` (for example) for that column. You may use also ``l``
-      specifier but this makes the task of setting column widths more difficult
-      if some merged cell intersects that column.
-
-   .. warning::
-
-      Tables with more than 30 rows are rendered using ``longtable``, not
-      ``tabulary``, in order to allow pagebreaks. The ``L``, ``R``, ... specifiers
-      do not work for these tables.
-
-      Tables that contain list-like elements such as object descriptions,
-      blockquotes or any kind of lists cannot be set out of the box with
-      ``tabulary``. They are therefore set with the standard LaTeX ``tabular`` (or
-      ``longtable``) environment if you don't give a ``tabularcolumns`` directive.
-      If you do, the table will be set with ``tabulary`` but you must use the
-      ``p{width}`` construct (or Sphinx's ``\X`` and ``\Y`` specifiers described
-      below) for the columns containing these elements.
-
-      Literal blocks do not work with ``tabulary`` at all, so tables containing
-      a literal block are always set with ``tabular``. The verbatim environment
-      used for literal blocks only works in ``p{width}`` (and ``\X`` or ``\Y``)
-      columns, hence Sphinx generates such column specs for tables containing
-      literal blocks.
-
-   Since Sphinx 1.5, the ``\X{a}{b}`` specifier is used (there *is* a backslash
-   in the specifier letter). It is like ``p{width}`` with the width set to a
-   fraction ``a/b`` of the current line width. You can use it in the
-   :rst:dir:`tabularcolumns` (it is not a problem if some LaTeX macro is also
-   called ``\X``.)
-
-   It is *not* needed for ``b`` to be the total number of columns, nor for the
-   sum of the fractions of the ``\X`` specifiers to add  up to one. For example
-   ``|\X{2}{5}|\X{1}{5}|\X{1}{5}|`` is legitimate and the table will occupy
-   80% of the line width, the first of its three columns having the same width
-   as the sum  of the next two.
-
-   This is used by the ``:widths:`` option of the :dudir:`table` directive.
-
-   Since Sphinx 1.6, there is also the ``\Y{f}`` specifier which admits a
-   decimal argument, such has ``\Y{0.15}``: this would have the same effect as
-   ``\X{3}{20}``.
-
-   .. versionchanged:: 1.6
-
-      Merged cells from complex grid tables (either multi-row, multi-column, or
-      both) now allow blockquotes, lists, literal blocks, ... as do regular cells.
-
-      Sphinx's merged cells interact well with ``p{width}``, ``\X{a}{b}``, ``Y{f}``
-      and tabulary's columns.
-
-Math
-----
-
-See :ref:`math-support`.
-
-.. rubric:: Footnotes
-
-.. [#] For most builders name and format are the same. At the moment only
-       builders derived from the html builder distinguish between the builder
-       format and the builder name.
-
-       Note that the current builder tag is not available in ``conf.py``, it is
-       only available after the builder is initialized.
-

doc/markup/para.rst

@@ -1,253 +0,0 @@
-.. highlight:: rest
-
-Paragraph-level markup
-----------------------
-
-.. index:: note, warning
-           pair: changes; in version
-
-These directives create short paragraphs and can be used inside information
-units as well as normal text:
-
-.. rst:directive:: .. note::
-
-   An especially important bit of information about an API that a user should be
-   aware of when using whatever bit of API the note pertains to.  The content of
-   the directive should be written in complete sentences and include all
-   appropriate punctuation.
-
-   Example::
-
-      .. note::
-
-         This function is not suitable for sending spam e-mails.
-
-.. rst:directive:: .. warning::
-
-   An important bit of information about an API that a user should be very aware
-   of when using whatever bit of API the warning pertains to.  The content of
-   the directive should be written in complete sentences and include all
-   appropriate punctuation. This differs from :rst:dir:`note` in that it is
-   recommended over :rst:dir:`note` for information regarding security.
-
-.. rst:directive:: .. versionadded:: version
-
-   This directive documents the version of the project which added the described
-   feature to the library or C API. When this applies to an entire module, it
-   should be placed at the top of the module section before any prose.
-
-   The first argument must be given and is the version in question; you can add
-   a second argument consisting of a *brief* explanation of the change.
-
-   Example::
-
-      .. versionadded:: 2.5
-         The *spam* parameter.
-
-   Note that there must be no blank line between the directive head and the
-   explanation; this is to make these blocks visually continuous in the markup.
-
-.. rst:directive:: .. versionchanged:: version
-
-   Similar to :rst:dir:`versionadded`, but describes when and what changed in
-   the named feature in some way (new parameters, changed side effects, etc.).
-
-.. rst:directive:: .. deprecated:: version
-
-   Similar to :rst:dir:`versionchanged`, but describes when the feature was
-   deprecated.  An explanation can also be given, for example to inform the
-   reader what should be used instead.  Example::
-
-      .. deprecated:: 3.1
-         Use :func:`spam` instead.
-
-
---------------
-
-.. rst:directive:: seealso
-
-   Many sections include a list of references to module documentation or
-   external documents.  These lists are created using the :rst:dir:`seealso`
-   directive.
-
-   The :rst:dir:`seealso` directive is typically placed in a section just before
-   any subsections.  For the HTML output, it is shown boxed off from the main
-   flow of the text.
-
-   The content of the :rst:dir:`seealso` directive should be a reST definition
-   list. Example::
-
-      .. seealso::
-
-         Module :py:mod:`zipfile`
-            Documentation of the :py:mod:`zipfile` standard module.
-
-         `GNU tar manual, Basic Tar Format <http://link>`_
-            Documentation for tar archive files, including GNU tar extensions.
-
-   There's also a "short form" allowed that looks like this::
-
-      .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
-
-   .. versionadded:: 0.5
-      The short form.
-
-.. rst:directive:: .. rubric:: title
-
-   This directive creates a paragraph heading that is not used to create a
-   table of contents node.
-
-   .. note::
-
-      If the *title* of the rubric is "Footnotes" (or the selected language's
-      equivalent), this rubric is ignored by the LaTeX writer, since it is
-      assumed to only contain footnote definitions and therefore would create an
-      empty heading.
-
-
-.. rst:directive:: centered
-
-   This directive creates a centered boldfaced line of text.  Use it as
-   follows::
-
-      .. centered:: LICENSE AGREEMENT
-
-   .. deprecated:: 1.1
-      This presentation-only directive is a legacy from older versions.  Use a
-      :rst:dir:`rst-class` directive instead and add an appropriate style.
-
-
-.. rst:directive:: hlist
-
-   This directive must contain a bullet list.  It will transform it into a more
-   compact list by either distributing more than one item horizontally, or
-   reducing spacing between items, depending on the builder.
-
-   For builders that support the horizontal distribution, there is a ``columns``
-   option that specifies the number of columns; it defaults to 2.  Example::
-
-      .. hlist::
-         :columns: 3
-
-         * A list of
-         * short items
-         * that should be
-         * displayed
-         * horizontally
-
-   .. versionadded:: 0.6
-
-
-Table-of-contents markup
-------------------------
-
-The :rst:dir:`toctree` directive, which generates tables of contents of
-subdocuments, is described in :ref:`toctree-directive`.
-
-For local tables of contents, use the standard reST :dudir:`contents directive
-<table-of-contents>`.
-
-
-.. _glossary-directive:
-
-Glossary
---------
-
-.. rst:directive:: .. glossary::
-
-   This directive must contain a reST definition-list-like markup with terms and
-   definitions.  The definitions will then be referencable with the
-   :rst:role:`term` role.  Example::
-
-      .. glossary::
-
-         environment
-            A structure where information about all documents under the root is
-            saved, and used for cross-referencing.  The environment is pickled
-            after the parsing stage, so that successive runs only need to read
-            and parse new and changed documents.
-
-         source directory
-            The directory which, including its subdirectories, contains all
-            source files for one Sphinx project.
-
-   In contrast to regular definition lists, *multiple* terms per entry are
-   allowed, and inline markup is allowed in terms.  You can link to all of the
-   terms.  For example::
-
-      .. glossary::
-
-         term 1
-         term 2
-            Definition of both terms.
-
-   (When the glossary is sorted, the first term determines the sort order.)
-
-   If you want to specify "grouping key" for general index entries, you can put a "key"
-   as "term : key". For example::
-
-      .. glossary::
-
-         term 1 : A
-         term 2 : B
-            Definition of both terms.
-
-   Note that "key" is used for grouping key as is.
-   The "key" isn't normalized; key "A" and "a" become different groups.
-   The whole characters in "key" is used instead of a first character; it is used for
-   "Combining Character Sequence" and "Surrogate Pairs" grouping key.
-
-   In i18n situation, you can specify "localized term : key" even if original text only
-   have "term" part. In this case, translated "localized term" will be categorized in
-   "key" group.
-
-   .. versionadded:: 0.6
-      You can now give the glossary directive a ``:sorted:`` flag that will
-      automatically sort the entries alphabetically.
-
-   .. versionchanged:: 1.1
-      Now supports multiple terms and inline markup in terms.
-
-   .. versionchanged:: 1.4
-      Index key for glossary term should be considered *experimental*.
-
-Grammar production displays
----------------------------
-
-Special markup is available for displaying the productions of a formal grammar.
-The markup is simple and does not attempt to model all aspects of BNF (or any
-derived forms), but provides enough to allow context-free grammars to be
-displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
-the definition of the symbol.  There is this directive:
-
-.. rst:directive:: .. productionlist:: [name]
-
-   This directive is used to enclose a group of productions.  Each production is
-   given on a single line and consists of a name, separated by a colon from the
-   following definition.  If the definition spans multiple lines, each
-   continuation line must begin with a colon placed at the same column as in the
-   first line.
-
-   The argument to :rst:dir:`productionlist` serves to distinguish different
-   sets of production lists that belong to different grammars.
-
-   Blank lines are not allowed within ``productionlist`` directive arguments.
-
-   The definition can contain token names which are marked as interpreted text
-   (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references
-   to the productions of these tokens.  Outside of the production list, you can
-   reference to token productions using :rst:role:`token`.
-
-   Note that no further reST parsing is done in the production, so that you
-   don't have to escape ``*`` or ``|`` characters.
-
-The following is an example taken from the Python Reference Manual::
-
-   .. productionlist::
-      try_stmt: try1_stmt | try2_stmt
-      try1_stmt: "try" ":" `suite`
-               : ("except" [`expression` ["," `target`]] ":" `suite`)+
-               : ["else" ":" `suite`]
-               : ["finally" ":" `suite`]
-      try2_stmt: "try" ":" `suite`
-               : "finally" ":" `suite`

doc/markup/toctree.rst

@@ -1,242 +0,0 @@
-.. highlight:: rst
-.. _toctree-directive:
-
-The TOC tree
-============
-
-.. index:: pair: table of; contents
-
-Since reST does not have facilities to interconnect several documents, or split
-documents into multiple output files, Sphinx uses a custom directive to add
-relations between the single files the documentation is made of, as well as
-tables of contents.  The ``toctree`` directive is the central element.
-
-.. note::
-
-   Simple "inclusion" of one file in another can be done with the
-   :dudir:`include` directive.
-
-.. rst:directive:: toctree
-
-   This directive inserts a "TOC tree" at the current location, using the
-   individual TOCs (including "sub-TOC trees") of the documents given in the
-   directive body.  Relative document names (not beginning with a slash) are
-   relative to the document the directive occurs in, absolute names are relative
-   to the source directory.  A numeric ``maxdepth`` option may be given to
-   indicate the depth of the tree; by default, all levels are included. [#]_
-
-   Consider this example (taken from the Python docs' library reference index)::
-
-      .. toctree::
-         :maxdepth: 2
-
-         intro
-         strings
-         datatypes
-         numeric
-         (many more documents listed here)
-
-   This accomplishes two things:
-
-   * Tables of contents from all those documents are inserted, with a maximum
-     depth of two, that means one nested heading.  ``toctree`` directives in
-     those documents are also taken into account.
-   * Sphinx knows the relative order of the documents ``intro``,
-     ``strings`` and so forth, and it knows that they are children of the shown
-     document, the library index.  From this information it generates "next
-     chapter", "previous chapter" and "parent chapter" links.
-
-   **Entries**
-
-   Document titles in the :rst:dir:`toctree` will be automatically read from the
-   title of the referenced document. If that isn't what you want, you can
-   specify an explicit title and target using a similar syntax to reST
-   hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
-   looks like::
-
-       .. toctree::
-
-          intro
-          All about strings <strings>
-          datatypes
-
-   The second line above will link to the ``strings`` document, but will use the
-   title "All about strings" instead of the title of the ``strings`` document.
-
-   You can also add external links, by giving an HTTP URL instead of a document
-   name.
-
-   **Section numbering**
-
-   If you want to have section numbers even in HTML output, give the
-   **toplevel** toctree a ``numbered`` option.  For example::
-
-      .. toctree::
-         :numbered:
-
-         foo
-         bar
-
-   Numbering then starts at the heading of ``foo``.  Sub-toctrees are
-   automatically numbered (don't give the ``numbered`` flag to those).
-
-   Numbering up to a specific depth is also possible, by giving the depth as a
-   numeric argument to ``numbered``.
-
-   **Additional options**
-
-   You can use ``caption`` option to provide a toctree caption and you can use
-   ``name`` option to provide implicit target name that can be referenced by
-   using :rst:role:`ref`::
-
-      .. toctree::
-         :caption: Table of Contents
-         :name: mastertoc
-
-         foo
-
-   If you want only the titles of documents in the tree to show up, not other
-   headings of the same level, you can use the ``titlesonly`` option::
-
-      .. toctree::
-         :titlesonly:
-
-         foo
-         bar
-
-   You can use "globbing" in toctree directives, by giving the ``glob`` flag
-   option.  All entries are then matched against the list of available
-   documents, and matches are inserted into the list alphabetically.  Example::
-
-      .. toctree::
-         :glob:
-
-         intro*
-         recipe/*
-         *
-
-   This includes first all documents whose names start with ``intro``, then all
-   documents in the ``recipe`` folder, then all remaining documents (except the
-   one containing the directive, of course.) [#]_
-
-   The special entry name ``self`` stands for the document containing the
-   toctree directive.  This is useful if you want to generate a "sitemap" from
-   the toctree.
-
-   You can use the ``reversed`` flag option to reverse the order of the entries
-   in the list. This can be useful when using the ``glob`` flag option to
-   reverse the ordering of the files.  Example::
-
-      .. toctree::
-         :glob:
-         :reversed:
-
-         recipe/*
-
-   You can also give a "hidden" option to the directive, like this::
-
-      .. toctree::
-         :hidden:
-
-         doc_1
-         doc_2
-
-   This will still notify Sphinx of the document hierarchy, but not insert links
-   into the document at the location of the directive -- this makes sense if you
-   intend to insert these links yourself, in a different style, or in the HTML
-   sidebar.
-
-   In cases where you want to have only one top-level toctree and hide all other
-   lower level toctrees you can add the "includehidden" option to the top-level
-   toctree entry::
-
-      .. toctree::
-         :includehidden:
-
-         doc_1
-         doc_2
-
-   All other toctree entries can then be eliminated by the "hidden" option.
-
-   In the end, all documents in the :term:`source directory` (or subdirectories)
-   must occur in some ``toctree`` directive; Sphinx will emit a warning if it
-   finds a file that is not included, because that means that this file will not
-   be reachable through standard navigation.
-
-   Use :confval:`exclude_patterns` to explicitly exclude documents or
-   directories from building completely.  Use :ref:`the "orphan" metadata
-   <metadata>` to let a document be built, but notify Sphinx that it is not
-   reachable via a toctree.
-
-   The "master document" (selected by :confval:`master_doc`) is the "root" of
-   the TOC tree hierarchy.  It can be used as the documentation's main page, or
-   as a "full table of contents" if you don't give a ``maxdepth`` option.
-
-   .. versionchanged:: 0.3
-      Added "globbing" option.
-
-   .. versionchanged:: 0.6
-      Added "numbered" and "hidden" options as well as external links and
-      support for "self" references.
-
-   .. versionchanged:: 1.0
-      Added "titlesonly" option.
-
-   .. versionchanged:: 1.1
-      Added numeric argument to "numbered".
-
-   .. versionchanged:: 1.2
-      Added "includehidden" option.
-
-   .. versionchanged:: 1.3
-      Added "caption" and "name" option.
-
-Special names
--------------
-
-Sphinx reserves some document names for its own use; you should not try to
-create documents with these names -- it will cause problems.
-
-The special document names (and pages generated for them) are:
-
-* ``genindex``, ``modindex``, ``search``
-
-  These are used for the general index, the Python module index, and the search
-  page, respectively.
-
-  The general index is populated with entries from modules, all index-generating
-  :ref:`object descriptions <basic-domain-markup>`, and from :rst:dir:`index`
-  directives.
-
-  The Python module index contains one entry per :rst:dir:`py:module` directive.
-
-  The search page contains a form that uses the generated JSON search index and
-  JavaScript to full-text search the generated documents for search words; it
-  should work on every major browser that supports modern JavaScript.
-
-* every name beginning with ``_``
-
-  Though only few such names are currently used by Sphinx, you should not create
-  documents or document-containing directories with such names.  (Using ``_`` as
-  a prefix for a custom template directory is fine.)
-
-.. warning::
-
-   Be careful with unusual characters in filenames.  Some formats may interpret
-   these characters in unexpected ways:
-
-   * Do not use the colon ``:`` for HTML based formats.  Links to other parts
-     may not work.
-
-   * Do not use the plus ``+`` for the ePub format.  Some resources may not be
-     found.
-
-.. rubric:: Footnotes
-
-.. [#] The LaTeX writer only refers the ``maxdepth`` option of first toctree
-       directive in the document.
-
-.. [#] A note on available globbing syntax: you can use the standard shell
-       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
-       these all don't match slashes.  A double star ``**`` can be used to match
-       any sequence of characters *including* slashes.

doc/templating.rst

@@ -62,7 +62,7 @@ following contents::
 
     {% extends "!layout.html" %}
     {% block rootrellink %}
-        <li><a href="http://project.invalid/">Project Homepage</a> &raquo;</li>
+        <li><a href="https://project.invalid/">Project Homepage</a> &raquo;</li>
         {{ super() }}
     {% endblock %}
 
@@ -70,8 +70,8 @@ By prefixing the name of the overridden template with an exclamation mark,
 Sphinx will load the layout template from the underlying HTML theme.
 
 **Important**: If you override a block, call ``{{ super() }}`` somewhere to
-render the block's content in the extended template -- unless you don't want
+render the block's original content in the extended template -- unless you
-that content to show up.
+don't want that content to show up.
 
 
 Working with the builtin templates
@@ -200,6 +200,10 @@ Overriding works like this::
 
       {% set script_files = script_files + ["_static/myscript.js"] %}
 
+   .. deprecated:: 1.8.0
+
+      Please use ``.Sphinx.add_js_file()`` instead.
+
 Helper Functions
 ~~~~~~~~~~~~~~~~
 
@@ -228,6 +232,9 @@ them to generate links or output multiply used elements.
 
    Return the rendered relation bar.
 
+.. function:: warning(message)
+
+   Emit a warning message.
 
 Global Variables
 ~~~~~~~~~~~~~~~~

doc/theming.rst

@@ -1,10 +1,16 @@
-.. highlightlang:: python
+.. highlight:: python
 
 HTML theming support
 ====================
 
 .. versionadded:: 0.6
 
+.. note::
+
+   This document provides information about creating your own theme. If you
+   simply wish to use a pre-existing HTML themes, refer to
+   :doc:`/usage/theming`.
+
 Sphinx supports changing the appearance of its HTML output via *themes*.  A
 theme is a collection of HTML templates, stylesheet(s) and other static files.
 Additionally, it has a configuration file which specifies from which theme to
@@ -15,248 +21,13 @@ Themes are meant to be project-unaware, so they can be used for different
 projects without change.
 
 
-Using a theme
--------------
-
-Using an existing theme is easy.  If the theme is builtin to Sphinx, you only
-need to set the :confval:`html_theme` config value.  With the
-:confval:`html_theme_options` config value you can set theme-specific options
-that change the look and feel.  For example, you could have the following in
-your :file:`conf.py`::
-
-    html_theme = "classic"
-    html_theme_options = {
-        "rightsidebar": "true",
-        "relbarbgcolor": "black"
-    }
-
-That would give you the classic theme, but with a sidebar on the right side and
-a black background for the relation bar (the bar with the navigation links at
-the page's top and bottom).
-
-If the theme does not come with Sphinx, it can be in two static forms: either a
-directory (containing :file:`theme.conf` and other needed files), or a zip file
-with the same contents.  Either of them must be put where Sphinx can find it;
-for this there is the config value :confval:`html_theme_path`.  It gives a list
-of directories, relative to the directory containing :file:`conf.py`, that can
-contain theme directories or zip files.  For example, if you have a theme in the
-file :file:`blue.zip`, you can put it right in the directory containing
-:file:`conf.py` and use this configuration::
-
-    html_theme = "blue"
-    html_theme_path = ["."]
-
-The third form is a python package.  If a theme you want to use is distributed
-as a python package, you can use it after installing
-
-.. code-block:: bash
-
-    # installing theme package
-    $ pip install sphinxjp.themes.dotted
-
-    # use it in your conf.py
-    html_theme = "dotted"
-
-
-.. _builtin-themes:
-
-Builtin themes
---------------
-
-.. cssclass:: longtable
-
-+--------------------+--------------------+
-| **Theme overview** |                    |
-+--------------------+--------------------+
-| |alabaster|        | |classic|          |
-|                    |                    |
-| *alabaster*        | *classic*          |
-+--------------------+--------------------+
-| |sphinxdoc|        | |scrolls|          |
-|                    |                    |
-| *sphinxdoc*        | *scrolls*          |
-+--------------------+--------------------+
-| |agogo|            | |traditional|      |
-|                    |                    |
-| *agogo*            | *traditional*      |
-+--------------------+--------------------+
-| |nature|           | |haiku|            |
-|                    |                    |
-| *nature*           | *haiku*            |
-+--------------------+--------------------+
-| |pyramid|          | |bizstyle|         |
-|                    |                    |
-| *pyramid*          | *bizstyle*         |
-+--------------------+--------------------+
-
-.. |alabaster|        image:: themes/alabaster.png
-.. |classic|          image:: themes/classic.png
-.. |sphinxdoc|        image:: themes/sphinxdoc.png
-.. |scrolls|          image:: themes/scrolls.png
-.. |agogo|            image:: themes/agogo.png
-.. |traditional|      image:: themes/traditional.png
-.. |nature|           image:: themes/nature.png
-.. |haiku|            image:: themes/haiku.png
-.. |pyramid|          image:: themes/pyramid.png
-.. |bizstyle|         image:: themes/bizstyle.png
-
-Sphinx comes with a selection of themes to choose from.
-
-.. cssclass:: clear
-
-These themes are:
-
-* **basic** -- This is a basically unstyled layout used as the base for the
-  other themes, and usable as the base for custom themes as well.  The HTML
-  contains all important elements like sidebar and relation bar.  There are
-  these options (which are inherited by the other themes):
-
-  - **nosidebar** (true or false): Don't include the sidebar.  Defaults to
-    ``False``.
-
-  - **sidebarwidth** (an integer): Width of the sidebar in pixels.  (Do not
-    include ``px`` in the value.)  Defaults to 230 pixels.
-
-* **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.
-  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
-  these options:
-
-  - **rightsidebar** (true or false): Put the sidebar on the right side.
-    Defaults to ``False``.
-
-  - **stickysidebar** (true or false): Make the sidebar "fixed" so that it
-    doesn't scroll out of view for long body content.  This may not work well
-    with all browsers.  Defaults to ``False``.
-
-  - **collapsiblesidebar** (true or false): Add an *experimental* JavaScript
-    snippet that makes the sidebar collapsible via a button on its side.
-    *Doesn't work with "stickysidebar".* Defaults to ``False``.
-
-  - **externalrefs** (true or false): Display external links differently from
-    internal links.  Defaults to ``False``.
-
-  There are also various color and font options that can change the color scheme
-  without having to write a custom stylesheet:
-
-  - **footerbgcolor** (CSS color): Background color for the footer line.
-  - **footertextcolor** (CSS color): Text color for the footer line.
-  - **sidebarbgcolor** (CSS color): Background color for the sidebar.
-  - **sidebarbtncolor** (CSS color): Background color for the sidebar collapse
-    button (used when *collapsiblesidebar* is ``True``).
-  - **sidebartextcolor** (CSS color): Text color for the sidebar.
-  - **sidebarlinkcolor** (CSS color): Link color for the sidebar.
-  - **relbarbgcolor** (CSS color): Background color for the relation bar.
-  - **relbartextcolor** (CSS color): Text color for the relation bar.
-  - **relbarlinkcolor** (CSS color): Link color for the relation bar.
-  - **bgcolor** (CSS color): Body background color.
-  - **textcolor** (CSS color): Body text color.
-  - **linkcolor** (CSS color): Body link color.
-  - **visitedlinkcolor** (CSS color): Body color for visited links.
-  - **headbgcolor** (CSS color): Background color for headings.
-  - **headtextcolor** (CSS color): Text color for headings.
-  - **headlinkcolor** (CSS color): Link color for headings.
-  - **codebgcolor** (CSS color): Background color for code blocks.
-  - **codetextcolor** (CSS color): Default text color for code blocks, if not
-    set differently by the highlighting style.
-
-  - **bodyfont** (CSS font-family): Font for normal text.
-  - **headfont** (CSS font-family): Font for headings.
-
-* **sphinxdoc** -- The theme used for this documentation.  It features a sidebar
-  on the right side.  There are currently no options beyond *nosidebar* and
-  *sidebarwidth*.
-
-* **scrolls** -- A more lightweight theme, based on `the Jinja documentation
-  <http://jinja.pocoo.org/>`_.  The following color options are available:
-
-  - **headerbordercolor**
-  - **subheadlinecolor**
-  - **linkcolor**
-  - **visitedlinkcolor**
-  - **admonitioncolor**
-
-* **agogo** -- A theme created by Andi Albrecht.  The following options are
-  supported:
-
-  - **bodyfont** (CSS font family): Font for normal text.
-  - **headerfont** (CSS font family): Font for headings.
-  - **pagewidth** (CSS length): Width of the page content, default 70em.
-  - **documentwidth** (CSS length): Width of the document (without sidebar),
-    default 50em.
-  - **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
-  - **bgcolor** (CSS color): Background color.
-  - **headerbg** (CSS value for "background"): background for the header area,
-    default a grayish gradient.
-  - **footerbg** (CSS value for "background"): background for the footer area,
-    default a light gray gradient.
-  - **linkcolor** (CSS color): Body link color.
-  - **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
-    headings.
-  - **headerlinkcolor** (CSS color): Color for the backreference link in
-    headings.
-  - **textalign** (CSS *text-align* value): Text alignment for the body, default
-    is ``justify``.
-
-* **nature** -- A greenish theme.  There are currently no options beyond
-  *nosidebar* and *sidebarwidth*.
-
-* **pyramid** -- A theme from the Pyramid web framework project, designed by
-  Blaise Laflamme.  There are currently no options beyond *nosidebar* and
-  *sidebarwidth*.
-
-* **haiku** -- A theme without sidebar inspired by the `Haiku OS user guide
-  <https://www.haiku-os.org/docs/userguide/en/contents.html>`_.  The following
-  options are supported:
-
-  - **full_logo** (true or false, default ``False``): If this is true, the
-    header will only show the :confval:`html_logo`.  Use this for large logos.
-    If this is false, the logo (if present) will be shown floating right, and
-    the documentation title will be put in the header.
-  - **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**,
-    **hoverlinkcolor** (CSS colors): Colors for various body elements.
-
-* **traditional** -- A theme resembling the old Python documentation.  There are
-  currently no options beyond *nosidebar* and *sidebarwidth*.
-
-* **epub** -- A theme for the epub builder.  This theme tries to save visual
-  space which is a sparse resource on ebook readers.  The following options
-  are supported:
-
-  - **relbar1** (true or false, default ``True``): If this is true, the
-    `relbar1` block is inserted in the epub output, otherwise it is omitted.
-  - **footer**  (true or false, default ``True``): If this is true, the
-    `footer` block is inserted in the epub output, otherwise it is omitted.
-
-- **bizstyle** -- A simple bluish theme. The following options are supported
-  beyond *nosidebar* and *sidebarwidth*:
-
-  - **rightsidebar** (true or false): Put the sidebar on the right side.
-    Defaults to ``False``.
-
-.. versionadded:: 1.3
-   'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme.
-
-.. versionchanged:: 1.3
-   The 'default' theme has been renamed to 'classic'. 'default' is still
-   available, however it will emit a notice that it is an alias for the new
-   'alabaster' theme.
-
 Creating themes
 ---------------
 
-As said, themes are either a directory or a zipfile (whose name is the theme
+Themes take the form of either a directory or a zipfile (whose name is the
-name), containing the following:
+theme name), containing the following:
 
-* A :file:`theme.conf` file, see below.
+* A :file:`theme.conf` file.
 * HTML templates, if needed.
 * A ``static/`` directory containing any static files that will be copied to the
   output static directory on build.  These can be images, styles, script files.
@@ -270,6 +41,7 @@ Python :mod:`ConfigParser` module) and has the following structure:
     inherit = base theme
     stylesheet = main CSS name
     pygments_style = stylename
+    sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html
 
     [options]
     variable = default value
@@ -277,7 +49,8 @@ Python :mod:`ConfigParser` module) and has the following structure:
 * The **inherit** setting gives the name of a "base theme", or ``none``.  The
   base theme will be used to locate missing templates (most themes will not have
   to supply most templates if they use ``basic`` as the base theme), its options
-  will be inherited, and all of its static files will be used as well.
+  will be inherited, and all of its static files will be used as well. If you want
+  to also inherit the stylesheet, include it via CSS' ``@import`` in your own.
 
 * The **stylesheet** setting gives the name of a CSS file which will be
   referenced in the HTML header.  If you need more than one CSS file, either
@@ -289,21 +62,28 @@ Python :mod:`ConfigParser` module) and has the following structure:
   highlighting.  This can be overridden by the user in the
   :confval:`pygments_style` config value.
 
+* The **sidebars** setting gives the comma separated list of sidebar templates
+  for constructing sidebars.  This can be overridden by the user in the
+  :confval:`html_sidebars` config value.
+
 * The **options** section contains pairs of variable names and default values.
   These options can be overridden by the user in :confval:`html_theme_options`
   and are accessible from all templates as ``theme_<name>``.
 
+.. versionadded:: 1.7
+   sidebar settings
+
 
 .. _distribute-your-theme:
 
-Distribute your theme as a python package
+Distribute your theme as a Python package
 -----------------------------------------
 
-As a way to distribute your theme, you can use python package.  Python package
+As a way to distribute your theme, you can use Python package.  Python package
 brings to users easy setting up ways.
 
-To distribute your theme as a python package, please define an entry point
+To distribute your theme as a Python package, please define an entry point
-called ``sphinx.html_themes`` in your setup.py file, and write a ``setup()``
+called ``sphinx.html_themes`` in your ``setup.py`` file, and write a ``setup()``
 function to register your themes using ``add_html_theme()`` API in it::
 
     # 'setup.py'
@@ -323,9 +103,8 @@ function to register your themes using ``add_html_theme()`` API in it::
     def setup(app):
         app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))
 
-
+If your theme package contains two or more themes, please call
-If your theme package contains two or more themes, please call ``add_html_theme()``
+``add_html_theme()`` twice or more.
-twice or more.
 
 .. versionadded:: 1.2
    'sphinx_themes' entry_points feature.
@@ -336,8 +115,9 @@ twice or more.
 .. versionadded:: 1.6
    ``sphinx.html_themes`` entry_points feature.
 
+
 Templating
-~~~~~~~~~~
+----------
 
 The :doc:`guide to templating <templating>` is helpful if you want to write your
 own templates.  What is important to keep in mind is the order in which Sphinx
@@ -352,7 +132,6 @@ name as an explicit directory: ``{% extends "basic/layout.html" %}``.  From a
 user ``templates_path`` template, you can still use the "exclamation mark"
 syntax as described in the templating document.
 
-
 Static templates
 ~~~~~~~~~~~~~~~~
 
@@ -369,32 +148,6 @@ templating to put the color options into the stylesheet.  When a documentation
 is built with the classic theme, the output directory will contain a
 ``_static/classic.css`` file where all template tags have been processed.
 
-
 .. [1] It is not an executable Python file, as opposed to :file:`conf.py`,
        because that would pose an unnecessary security risk if themes are
        shared.
-
-Third Party Themes
-------------------
-
-.. cssclass:: longtable
-
-+--------------------+--------------------+
-| **Theme overview** |                    |
-+--------------------+--------------------+
-| |sphinx_rtd_theme| |                    |
-|                    |                    |
-| *sphinx_rtd_theme* |                    |
-+--------------------+--------------------+
-
-.. |sphinx_rtd_theme| image:: themes/sphinx_rtd_theme.png
-
-* **sphinx_rtd_theme** -- `Read the Docs Sphinx Theme`_.
-  This is a mobile-friendly sphinx theme that was made for readthedocs.org.
-  View a working demo over on readthedocs.org. You can get install and options
-  information at `Read the Docs Sphinx Theme`_ page.
-
-  .. _Read the Docs Sphinx Theme: https://pypi.python.org/pypi/sphinx_rtd_theme
-
-  .. versionchanged:: 1.4
-     **sphinx_rtd_theme** has become optional.

doc/usage/advanced/intl.rst

@@ -9,11 +9,11 @@ Complementary to translations provided for Sphinx-generated messages such as
 navigation bars, Sphinx provides mechanisms facilitating *document* translations
 in itself.  See the :ref:`intl-options` for details on configuration.
 
-.. figure:: translation.png
+.. figure:: /_static/translation.png
    :width: 100%
 
    Workflow visualization of translations in Sphinx.  (The stick-figure is taken
-   from an `XKCD comic <http://xkcd.com/779/>`_.)
+   from an `XKCD comic <https://xkcd.com/779/>`_.)
 
 .. contents::
    :local:
@@ -46,14 +46,14 @@ They can be delivered to translators which will transform them to ``.po`` files
 --- so called **message catalogs** --- containing a mapping from the original
 messages to foreign-language strings.
 
-Gettext compiles them into a binary format known as **binary catalogs** through
+*gettext* compiles them into a binary format known as **binary catalogs**
-:program:`msgfmt` for efficiency reasons.  If you make these files discoverable
+through :program:`msgfmt` for efficiency reasons.  If you make these files
-with :confval:`locale_dirs` for your :confval:`language`, Sphinx will pick them
+discoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx
-up automatically.
+will pick them up automatically.
 
 An example: you have a document ``usage.rst`` in your Sphinx project.  The
-gettext builder will put its messages into ``usage.pot``.  Imagine you have
+*gettext* builder will put its messages into ``usage.pot``.  Imagine you have
-Spanish translations [2]_ on your hands in ``usage.po`` --- for your builds to
+Spanish translations [2]_ stored in ``usage.po`` --- for your builds to
 be translated you need to follow these instructions:
 
 * Compile your message catalog to a locale directory, say ``locale``, so it
@@ -63,7 +63,8 @@ be translated you need to follow these instructions:
         msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
 
 * Set :confval:`locale_dirs` to ``["locale/"]``.
-* Set :confval:`language` to ``es`` (also possible via :option:`-D <sphinx-build -D>`).
+* Set :confval:`language` to ``es`` (also possible via
+  :option:`-D <sphinx-build -D>`).
 * Run your desired build.
 
 
@@ -71,103 +72,124 @@ Translating with sphinx-intl
 ----------------------------
 
 Quick guide
-^^^^^^^^^^^
+~~~~~~~~~~~
 
-`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.
+`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.  This
-This section describe an easy way to translate with sphinx-intl.
+section describe an easy way to translate with *sphinx-intl*.
 
-#. Install `sphinx-intl`_ by :command:`pip install sphinx-intl` or
+#. Install `sphinx-intl`_.
-   :command:`easy_install sphinx-intl`.
 
-#. Add configurations to your `conf.py`::
+   .. code-block:: console
+
+      $ pip install sphinx-intl
+
+#. Add configurations to ``conf.py``.
+
+   ::
 
       locale_dirs = ['locale/']   # path is example but recommended.
       gettext_compact = False     # optional.
 
-   This case-study assumes that :confval:`locale_dirs` is set to 'locale/' and
+   This case-study assumes that :confval:`locale_dirs` is set to ``locale/`` and
-   :confval:`gettext_compact` is set to `False` (the Sphinx document is
+   :confval:`gettext_compact` is set to ``False`` (the Sphinx document is
    already configured as such).
 
-#. Extract document's translatable messages into pot files:
+#. Extract translatable messages into pot files.
 
    .. code-block:: console
 
       $ make gettext
 
-   As a result, many pot files are generated under ``_build/gettext``
+   The generated pot files will be placed in the ``_build/gettext`` directory.
-   directory.
 
-#. Setup/Update your `locale_dir`:
+#. Generate po files.
+
+   We'll use the pot files generated in the above step.
 
    .. code-block:: console
 
       $ sphinx-intl update -p _build/gettext -l de -l ja
 
-   Done. You got these directories that contain po files:
+   Once completed, the generated po files will be placed in the below
+   directories:
 
-   * `./locale/de/LC_MESSAGES/`
+   * ``./locale/de/LC_MESSAGES/``
-   * `./locale/ja/LC_MESSAGES/`
+   * ``./locale/ja/LC_MESSAGES/``
 
-#. Translate your po files under `./locale/<lang>/LC_MESSAGES/`.
+#. Translate po files.
 
-#. make translated document.
+   AS noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
+   directory.  An example of one such file, from Sphinx, ``builders.po``, is
+   given below.
+
+   .. code-block:: po
+
+      # a5600c3d2e3d48fc8c261ea0284db79b
+      #: ../../builders.rst:4
+      msgid "Available builders"
+      msgstr "<FILL HERE BY TARGET LANGUAGE>"
+
+   Another case, msgid is multi-line text and contains reStructuredText syntax:
+
+   .. code-block:: po
+
+      # 302558364e1d41c69b3277277e34b184
+      #: ../../builders.rst:9
+      msgid ""
+      "These are the built-in Sphinx builders. More builders can be added by "
+      ":ref:`extensions <extensions>`."
+      msgstr ""
+      "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
+      "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
+
+   Please be careful not to break reST notation.  Most po-editors will help you
+   with that.
+
+#. Build translated document.
 
    You need a :confval:`language` parameter in ``conf.py`` or you may also
-   specify the parameter on the command line:
+   specify the parameter on the command line.
+
+   For for BSD/GNU make, run:
 
    .. code-block:: console
 
       $ make -e SPHINXOPTS="-D language='de'" html
 
+   For Windows :command:`cmd.exe`, run:
+
+   .. code-block:: console
+
+      > set SPHINXOPTS=-D language=de
+      > .\make.bat html
+
+   For PowerShell, run:
+
+   .. code-block:: console
+
+      > Set-Item env:SPHINXOPTS "-D language=de"
+      > .\make.bat html
+
 Congratulations! You got the translated documentation in the ``_build/html``
 directory.
 
 .. versionadded:: 1.3
 
-   sphinx-build that is invoked by make command will build po files into mo files.
+   :program:`sphinx-build` that is invoked by make command will build po files
-
+   into mo files.
-   If you are using 1.2.x or earlier, please invoke ``sphinx-intl build`` command
-   before make command.
 
+   If you are using 1.2.x or earlier, please invoke :command:`sphinx-intl build`
+   command before :command:`make` command.
 
 Translating
-^^^^^^^^^^^
+~~~~~~~~~~~
-
-Translate po file under ``./locale/de/LC_MESSAGES`` directory.
-The case of builders.po file for sphinx document:
-
-.. code-block:: po
-
-   # a5600c3d2e3d48fc8c261ea0284db79b
-   #: ../../builders.rst:4
-   msgid "Available builders"
-   msgstr "<FILL HERE BY TARGET LANGUAGE>"
-
-Another case, msgid is multi-line text and contains reStructuredText
-syntax:
-
-.. code-block:: po
-
-   # 302558364e1d41c69b3277277e34b184
-   #: ../../builders.rst:9
-   msgid ""
-   "These are the built-in Sphinx builders. More builders can be added by "
-   ":ref:`extensions <extensions>`."
-   msgstr ""
-   "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
-   "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
-
-Please be careful not to break reST notation.  Most po-editors will help you
-with that.
-
 
 Update your po files by new pot files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If a document is updated, it is necessary to generate updated pot files
+If a document is updated, it is necessary to generate updated pot files and to
-and to apply differences to translated po files.
+apply differences to translated po files.  In order to apply the updates from a
-In order to apply the updating difference of a pot file to po file,
+pot file to the po file, use the :command:`sphinx-intl update` command.
-use the :command:`sphinx-intl update` command.
 
 .. code-block:: console
 
@@ -184,7 +206,7 @@ easy to fetch and push translations.
 .. TODO: why use transifex?
 
 
-#. Install `transifex-client`_
+#. Install `transifex-client`_.
 
    You need :command:`tx` command to upload resources (pot files).
 
@@ -192,10 +214,9 @@ easy to fetch and push translations.
 
       $ pip install transifex-client
 
-   .. seealso:: `Transifex Client v0.8 &mdash; Transifex documentation`_
+   .. seealso:: `Transifex Client documentation`_
 
-
+#. Create your transifex_ account and create new project for your document.
-#. Create your transifex_ account and create new project for your document
 
    Currently, transifex does not allow for a translation project to have more
    than one version of the document, so you'd better include a version number in
@@ -206,8 +227,7 @@ easy to fetch and push translations.
    :Project ID: ``sphinx-document-test_1_0``
    :Project URL: ``https://www.transifex.com/projects/p/sphinx-document-test_1_0/``
 
-
+#. Create config files for :command:`tx` command.
-#. Create config files for tx command
 
    This process will create ``.tx/config`` in the current directory, as well as
    a ``~/.transifexrc`` file that includes auth information.
@@ -223,7 +243,7 @@ easy to fetch and push translations.
       ...
       Done.
 
-#. Upload pot files to transifex service
+#. Upload pot files to transifex service.
 
    Register pot files to ``.tx/config`` file:
 
@@ -244,15 +264,14 @@ easy to fetch and push translations.
       ...
       Done.
 
-
+#. Forward the translation on transifex.
-#. Forward the translation on transifex
 
    .. TODO: write this section
 
+#. Pull translated po files and make translated HTML.
 
-#. Pull translated po files and make translated html
+   Get translated catalogs and build mo files. For example, to build mo files
-
+   for German (de):
-   Get translated catalogs and build mo files (ex. for 'de'):
 
    .. code-block:: console
 
@@ -263,52 +282,47 @@ easy to fetch and push translations.
       ...
       Done.
 
-   Invoke make html:
+   Invoke :command:`make html` (for BSD/GNU make):
 
    .. code-block:: console
 
       $ make -e SPHINXOPTS="-D language='de'" html
 
-
 That's all!
 
-
 .. tip:: Translating locally and on Transifex
 
    If you want to push all language's po files, you can be done by using
-   :command:`tx push -t` command.
+   :command:`tx push -t` command.  Watch out! This operation overwrites
-   Watch out! This operation overwrites translations in transifex.
+   translations in transifex.
 
    In other words, if you have updated each in the service and local po files,
    it would take much time and effort to integrate them.
 
 
-
 Contributing to Sphinx reference translation
 --------------------------------------------
 
-The recommended way for new contributors to translate Sphinx reference
+The recommended way for new contributors to translate Sphinx reference is to
-is to join the translation team on Transifex.
+join the translation team on Transifex.
 
-There is `sphinx translation page`_ for Sphinx-1.3 documentation.
+There is `sphinx translation page`_ for Sphinx (master) documentation.
 
 1. Login to transifex_ service.
 2. Go to `sphinx translation page`_.
 3. Click ``Request language`` and fill form.
 4. Wait acceptance by transifex sphinx translation maintainers.
-5. (after acceptance) translate on transifex.
+5. (After acceptance) Translate on transifex.
-
 
 .. rubric:: Footnotes
 
 .. [1] See the `GNU gettext utilities
-       <http://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_
+       <https://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_
        for details on that software suite.
 .. [2] Because nobody expects the Spanish Inquisition!
 
-
+.. _`transifex-client`: https://pypi.org/project/transifex-client/
-.. _`transifex-client`: https://pypi.python.org/pypi/transifex-client
+.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
-.. _`sphinx-intl`: https://pypi.python.org/pypi/sphinx-intl
 .. _Transifex: https://www.transifex.com/
-.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc-1_3/
+.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc/
-.. _`Transifex Client v0.8 &mdash; Transifex documentation`: http://docs.transifex.com/developer/client/
+.. _`Transifex Client documentation`: https://docs.transifex.com/client/introduction/

doc/usage/advanced/setuptools.rst

@@ -32,15 +32,23 @@ For instance, from ``setup.py``::
             'build_sphinx': {
                 'project': ('setup.py', name),
                 'version': ('setup.py', version),
-                'release': ('setup.py', release)}},
+                'release': ('setup.py', release),
+                'source_dir': ('setup.py', 'doc')}},
     )
 
+.. note::
+
+    If you set Sphinx options directly in the ``setup()`` command, replace
+    hyphens in variable names with underscores. In the example above,
+    ``source-dir`` becomes ``source_dir``.
+
 Or add this section in ``setup.cfg``::
 
     [build_sphinx]
     project = 'My project'
     version = 1.2
     release = 1.2.0
+    source-dir = 'doc'
 
 Once configured, call this by calling the relevant command on ``setup.py``::
 
@@ -54,7 +62,7 @@ Options for setuptools integration
    A boolean that determines whether the saved environment should be discarded
    on build. Default is false.
 
-   This can also be set by passing the `-E` flag to ``setup.py``.
+   This can also be set by passing the `-E` flag to ``setup.py``:
 
    .. code-block:: bash
 
@@ -74,7 +82,9 @@ Options for setuptools integration
 .. confval:: source-dir
 
    The target source directory. This can be relative to the ``setup.py`` or
-   ``setup.cfg`` file, or it can be absolute. Default is ``''``.
+   ``setup.cfg`` file, or it can be absolute.  It defaults to ``./doc`` or
+   ``./docs`` if either contains a file named ``conf.py`` (checking ``./doc``
+   first); otherwise it defaults to the current directory.
 
    This can also be set by passing the `-s` flag to ``setup.py``:
 
@@ -85,13 +95,13 @@ Options for setuptools integration
 .. confval:: build-dir
 
    The target build directory. This can be relative to the ``setup.py`` or
-   ``setup.cfg`` file, or it can be absolute. Default is ``''``.
+   ``setup.cfg`` file, or it can be absolute. Default is ``./build/sphinx``.
 
 .. confval:: config-dir
 
    Location of the configuration directory. This can be relative to the
-   ``setup.py`` or ``setup.cfg`` file, or it can be absolute. Default is
+   ``setup.py`` or ``setup.cfg`` file, or it can be absolute. Default is to use
-   ``''``.
+   `source-dir`.
 
    This can also be set by passing the `-c` flag to ``setup.py``:
 
@@ -171,6 +181,14 @@ Options for setuptools integration
 
    .. versionadded:: 1.3
 
+.. confval:: nitpicky
+
+   Run in nit-picky mode.  Currently, this generates warnings for all missing
+   references.  See the config value :confval:`nitpick_ignore` for a way to
+   exclude some references as "known missing".
+
+   .. versionadded:: 1.8
+
 .. confval:: pdb
 
    A boolean to configure ``pdb`` on exception. Default is false.

doc/usage/advanced/websupport/api.rst

@@ -40,9 +40,17 @@ The WebSupport Class
        comment that was added.
 
    staticdir
-       If static files are served from a location besides ``'/static'``, this
+       If the static files should be created in a different location
-       should be a string with the name of that location
+       **and not in** ``'/static'``, this should be a string with the name of
-       (e.g. ``'/static_files'``).
+       that location (e.g. ``builddir + '/static_files'``).
+
+       .. note::
+           If you specify ``staticdir``, you will typically want to adjust
+           ``staticroot`` accordingly.
+
+   staticroot
+       If the static files are not served from ``'/static'``, this should be a
+       string with the name of that location (e.g. ``'/static_files'``).
 
    docroot
        If the documentation is not served from the base path of a URL, this
@@ -57,7 +65,7 @@ The WebSupport Class
 
 
 Methods
-~~~~~~~
+-------
 
 .. automethod:: sphinxcontrib.websupport.WebSupport.build
 

doc/usage/advanced/websupport/index.rst

@@ -10,7 +10,7 @@ web application.  To learn more read the :ref:`websupportquickstart`.
 
 .. toctree::
 
-   web/quickstart
+   quickstart
-   web/api
+   api
-   web/searchadapters
+   searchadapters
-   web/storagebackends
+   storagebackends

doc/usage/advanced/websupport/quickstart.rst

@@ -4,7 +4,7 @@ Web Support Quick Start
 =======================
 
 Building Documentation Data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 To make use of the web support package in your application you'll need to build
 the data it uses.  This data includes pickle files representing documents,
@@ -20,11 +20,11 @@ things are in a document.  To do this you will need to create an instance of the
 
    support.build()
 
-This will read reStructuredText sources from `srcdir` and place the necessary
+This will read reStructuredText sources from ``srcdir`` and place the necessary
-data in `builddir`.  The `builddir` will contain two sub-directories: one named
+data in ``builddir``.  The ``builddir`` will contain two sub-directories: one
-"data" that contains all the data needed to display documents, search through
+named "data" that contains all the data needed to display documents, search
-documents, and add comments to documents.  The other directory will be called
+through documents, and add comments to documents.  The other directory will be
-"static" and contains static files that should be served from "/static".
+called "static" and contains static files that should be served from "/static".
 
 .. note::
 
@@ -34,7 +34,7 @@ documents, and add comments to documents.  The other directory will be called
 
 
 Integrating Sphinx Documents Into Your Webapp
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------
 
 Now that the data is built, it's time to do something useful with it.  Start off
 by creating a :class:`~.WebSupport` object for your application::
@@ -96,7 +96,7 @@ integrate with your existing templating system.  An example using `Jinja2
 
 
 Authentication
---------------
+~~~~~~~~~~~~~~
 
 To use certain features such as voting, it must be possible to authenticate
 users.  The details of the authentication are left to your application.  Once a
@@ -146,13 +146,14 @@ add this data to the ``COMMENT_OPTIONS`` that are used in the template.
 
 
 Performing Searches
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 To use the search form built-in to the Sphinx sidebar, create a function to
-handle requests to the url 'search' relative to the documentation root.  The
+handle requests to the URL 'search' relative to the documentation root.  The
 user's search query will be in the GET parameters, with the key `q`.  Then use
-the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to retrieve
+the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to
-search results. In `Flask <http://flask.pocoo.org/>`_ that would be like this::
+retrieve search results. In `Flask <http://flask.pocoo.org/>`_ that would be
+like this::
 
    @app.route('/search')
    def search():
@@ -167,7 +168,7 @@ does.
 
 
 Comments & Proposals
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 Now that this is done it's time to define the functions that handle the AJAX
 calls from the script.  You will need three functions.  The first function is
@@ -186,9 +187,9 @@ used to add a new comment, and will call the web support method
                                      username=username, proposal=proposal)
        return jsonify(comment=comment)
 
-You'll notice that both a `parent_id` and `node_id` are sent with the
+You'll notice that both a ``parent_id`` and ``node_id`` are sent with the
-request. If the comment is being attached directly to a node, `parent_id`
+request. If the comment is being attached directly to a node, ``parent_id``
-will be empty. If the comment is a child of another comment, then `node_id`
+will be empty. If the comment is a child of another comment, then ``node_id``
 will be empty. Then next function handles the retrieval of comments for a
 specific node, and is aptly named
 :meth:`~sphinxcontrib.websupport.WebSupport.get_data`::
@@ -217,11 +218,11 @@ and will handle user votes on comments::
 
 
 Comment Moderation
-~~~~~~~~~~~~~~~~~~
+------------------
 
 By default, all comments added through :meth:`~.WebSupport.add_comment` are
 automatically displayed.  If you wish to have some form of moderation, you can
-pass the `displayed` keyword argument::
+pass the ``displayed`` keyword argument::
 
    comment = support.add_comment(text, node_id='node_id',
                                  parent_id='parent_id',

doc/usage/advanced/websupport/searchadapters.rst

@@ -26,13 +26,13 @@ documentation of the :class:`BaseSearch` class below.
    BaseSearch class is moved to sphinxcontrib.websupport.search from
    sphinx.websupport.search.
 
-BaseSearch Methods
+Methods
-~~~~~~~~~~~~~~~~~~
+-------
 
-   The following methods are defined in the BaseSearch class. Some methods do
+The following methods are defined in the BaseSearch class. Some methods do not
-   not need to be overridden, but some (:meth:`~BaseSearch.add_document` and
+need to be overridden, but some (:meth:`~BaseSearch.add_document` and
-   :meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
+:meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
-   working example, look at the built-in adapter for whoosh.
+working example, look at the built-in adapter for whoosh.
 
 .. automethod:: BaseSearch.init_indexing
 

doc/usage/advanced/websupport/storagebackends.rst

@@ -27,8 +27,8 @@ documentation of the :class:`StorageBackend` class below.
    sphinx.websupport.storage.
 
 
-StorageBackend Methods
+Methods
-~~~~~~~~~~~~~~~~~~~~~~
+-------
 
 .. automethod:: StorageBackend.pre_build
 

doc/usage/builders/index.rst

@@ -1,13 +1,14 @@
 .. _builders:
 
-Available builders
+========
-==================
+Builders
+========
 
 .. module:: sphinx.builders
    :synopsis: Available built-in builder classes.
 
 These are the built-in Sphinx builders.  More builders can be added by
-:ref:`extensions <extensions>`.
+:doc:`extensions </usage/extensions/index>`.
 
 The builder's "name" must be given to the **-b** command-line option of
 :program:`sphinx-build` to select a builder.
@@ -75,8 +76,8 @@ The builder's "name" must be given to the **-b** command-line option of
 .. class:: QtHelpBuilder
 
    This builder produces the same output as the standalone HTML builder, but
-   also generates `Qt help`_ collection support files that allow
+   also generates `Qt help`_ collection support files that allow the Qt
-   the Qt collection generator to compile them.
+   collection generator to compile them.
 
    .. autoattribute:: name
 
@@ -144,7 +145,8 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. versionchanged:: 1.5
 
-      Since Sphinx-1.5, the epub3 builder is used for the default builder of epub.
+      Since Sphinx-1.5, the epub3 builder is used for the default builder of
+      epub.
 
 .. module:: sphinx.builders.latex
 .. class:: LaTeXBuilder
@@ -155,36 +157,48 @@ The builder's "name" must be given to the **-b** command-line option of
    configuration values that customize the output of this builder, see the
    chapter :ref:`latex-options` for details.
 
+   The produced LaTeX file uses several LaTeX packages that may not be present
+   in a "minimal" TeX distribution installation.
+
+   On Ubuntu xenial, the following packages need to be installed for
+   successful PDF builds:
+
+   * ``texlive-latex-recommended``
+   * ``texlive-fonts-recommended``
+   * ``texlive-latex-extra``
+   * ``latexmk`` (this is a Sphinx requirement on GNU/Linux and MacOS X
+     for functioning of ``make latexpdf``)
+
+   Additional packages are needed in some circumstances (see the discussion of
+   the ``'fontpkg'`` key of :confval:`latex_elements` for more information):
+
+   * to support occasional Cyrillic letters or words, and a fortiori if
+     :confval:`language` is set to a Cyrillic language, the package
+     ``texlive-lang-cyrillic`` is required, and, with unmodified ``'fontpkg'``,
+     also ``cm-super`` or ``cm-super-minimal``,
+   * to support occasional Greek letters or words (in text, not in
+     :rst:dir:`math` directive contents), ``texlive-lang-greek`` is required,
+     and, with unmodified ``'fontpkg'``, also ``cm-super`` or
+     ``cm-super-minimal``,
+   * for ``'xelatex'`` or ``'lualatex'`` (see :confval:`latex_engine`),
+     ``texlive-xetex`` resp. ``texlive-luatex``, and, if leaving unchanged
+     ``'fontpkg'``, ``fonts-freefont-otf``.
+
+   The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX distribution
+   is based on a TeXLive 2015 snapshot dated March 2016.
+
+   .. versionchanged:: 1.6
+      Formerly, testing had been done on Ubuntu precise (TeXLive 2009).
+
+   .. versionchanged:: 2.0
+      Formerly, testing had been done on Ubuntu trusty (TeXLive 2013).
+
    .. note::
 
-      The produced LaTeX file uses several LaTeX packages that may not be
+      Since 1.6, ``make latexpdf`` uses ``latexmk`` (not on Windows).  This
-      present in a "minimal" TeX distribution installation. For example, on
+      makes sure the needed number of runs is automatically executed to get
-      Ubuntu, the following packages need to be installed for successful PDF
+      the cross-references, bookmarks, indices, and tables of contents right.
-      builds:
 
-      * texlive-latex-recommended
-      * texlive-fonts-recommended
-      * texlive-latex-extra
-      * latexmk (for ``make latexpdf``)
-
-      Sphinx will use ``xcolor.sty`` if present: recent Ubuntu distributions
-      have ``xcolor.sty`` included in latex-recommended, earlier ones have it
-      in latex-xcolor. Unicode engines will need texlive-luatex or
-      texlive-xetex.
-
-      The testing of Sphinx LaTeX is done on Ubuntu trusty with the above
-      mentioned packages, which are from a TeXLive 2013 snapshot dated
-      February 2014.
-
-      .. versionchanged:: 1.6
-         Formerly, testing had been done for some years on Ubuntu precise
-         (based on TeXLive 2009).
-      .. versionchanged:: 1.6
-         Use of ``latexmk`` for ``make latexpdf`` on GNU/Linux and Mac OS X
-
-      Since 1.6, ``make latexpdf`` (or
-      ``make -C "<builddir>/latex"`` after a ``sphinx-build`` run) uses
-      ``latexmk`` (not on Windows).
       One can pass to ``latexmk`` options via the ``LATEXMKOPTS``
       Makefile variable. For example:
 
@@ -192,13 +206,18 @@ The builder's "name" must be given to the **-b** command-line option of
 
          make latexpdf LATEXMKOPTS="-silent"
 
-      reduces console output to a minimum. Also, if ``latexmk`` version is
+      reduces console output to a minimum.
-      4.52b or higher (Jan 17) and ``xelatex`` is the :confval:`latex_engine`,
-      then ``LATEXMKOPTS="-xelatex"`` will speed up PDF builds.
 
-      To pass options directly to the
+      Also, if ``latexmk`` is at version 4.52b or higher (January 2017)
-      ``(pdf|xe|lua)latex`` executable, use variable ``LATEXOPTS`` (for example
+      ``LATEXMKOPTS="-xelatex"`` speeds up PDF builds via XeLateX in case
-      ``LATEXOPTS="--interaction=nonstopmode"``).
+      of numerous graphics inclusions.
+
+      To pass options directly to the ``(pdf|xe|lua)latex`` binary, use
+      variable ``LATEXOPTS``, for example:
+
+      .. code-block:: console
+
+         make latexpdf LATEXOPTS="--halt-on-error"
 
    .. autoattribute:: name
 
@@ -207,16 +226,10 @@ The builder's "name" must be given to the **-b** command-line option of
    .. autoattribute:: supported_image_types
 
 Note that a direct PDF builder is being provided by `rinohtype`_. The builder's
-name is ``rinoh``. Refer to the `rinohtype manual`_ for details. There is also
+name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
-PDF builder using ReportLab in `rst2pdf`_ version 0.12 or greater. However,
-rst2pdf is no longer being actively maintained and suffers from some problems
-when used with recent Sphinx versions.  See the `rst2pdf manual`_ for usage
-instructions.
 
 .. _rinohtype: https://github.com/brechtm/rinohtype
-.. _rinohtype manual: http://www.mos6581.org/rinohtype/quickstart.html#sphinx-builder
+.. _rinohtype manual: https://www.mos6581.org/rinohtype/quickstart.html#sphinx-builder
-.. _rst2pdf: https://github.com/rst2pdf/rst2pdf
-.. _rst2pdf manual: http://ralsina.me/static/manual.pdf
 
 .. module:: sphinx.builders.text
 .. class:: TextBuilder
@@ -291,7 +304,7 @@ instructions.
             globalcontext_filename = 'globalcontext.phpdump'
             searchindex_filename = 'searchindex.phpdump'
 
-   .. _PHP serialization: https://pypi.python.org/pypi/phpserialize
+   .. _PHP serialization: https://pypi.org/project/phpserialize/
 
    .. attribute:: implementation
 
@@ -314,7 +327,6 @@ instructions.
 
       The filename for the search index Sphinx generates.
 
-
    See :ref:`serialization-details` for details about the output format.
 
    .. versionadded:: 0.5
@@ -403,8 +415,8 @@ instructions.
 .. class:: CheckExternalLinksBuilder
 
    This builder scans all documents for external links, tries to open them with
-   :mod:`urllib2`, and writes an overview which ones are broken and redirected
+   ``requests``, and writes an overview which ones are broken and redirected to
-   to standard output and to :file:`output.txt` in the output directory.
+   standard output and to :file:`output.txt` in the output directory.
 
    .. autoattribute:: name
 
@@ -412,6 +424,10 @@ instructions.
 
    .. autoattribute:: supported_image_types
 
+   .. versionchanged:: 1.5
+
+      Since Sphinx-1.5, the linkcheck builder comes to use requests module.
+
 .. module:: sphinx.builders.xml
 .. class:: XMLBuilder
 

doc/usage/extensions/autodoc.rst

@@ -41,10 +41,14 @@ you can also enable the :mod:`napoleon <sphinx.ext.napoleon>` extension.
 docstrings to correct reStructuredText before :mod:`autodoc` processes them.
 
 .. _Google:
-   https://google.github.io/styleguide/pyguide.html#Comments
+   https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings
 .. _NumPy:
    https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
 
+
+Directives
+----------
+
 :mod:`autodoc` provides several directives that are versions of the usual
 :rst:dir:`py:module`, :rst:dir:`py:class` and so forth.  On parsing time, they
 import the corresponding module and extract the docstring of the given objects,
@@ -103,8 +107,10 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
      will document all non-private member functions and properties (that is,
      those whose name doesn't start with ``_``).
 
-     For modules, ``__all__`` will be respected when looking for members; the
+     For modules, ``__all__`` will be respected when looking for members unless
-     order of the members will also be the order in ``__all__``.
+     you give the ``ignore-module-all`` flag option.  Without
+     ``ignore-module-all``, the order of the members will also be the order in
+     ``__all__``.
 
      You can also give an explicit list of members; only these will then be
      documented::
@@ -112,8 +118,17 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
         .. autoclass:: Noodle
            :members: eat, slurp
 
-   * If you want to make the ``members`` option (or other flag options described
+   * If you want to make the ``members`` option (or other options described
-     below) the default, see :confval:`autodoc_default_flags`.
+     below) the default, see :confval:`autodoc_default_options`.
+
+     .. tip::
+
+        You can use a negated form, :samp:`'no-{flag}'`, as an option of
+        autodoc directive, to disable it temporarily.  For example::
+
+           .. automodule:: foo
+              :no-undoc-members:
+
 
    * Members without docstrings will be left out, unless you give the
      ``undoc-members`` flag option::
@@ -295,6 +310,9 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
       well-behaved decorating functions.
 
 
+Configuration
+-------------
+
 There are also new config values that you can set:
 
 .. confval:: autoclass_content
@@ -339,20 +357,39 @@ There are also new config values that you can set:
    This value is a list of autodoc directive flags that should be automatically
    applied to all autodoc directives.  The supported flags are ``'members'``,
    ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
-   ``'inherited-members'`` and ``'show-inheritance'``.
+   ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``
-
+   and ``'exclude-members'``.
-   If you set one of these flags in this config value, you can use a negated
-   form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.
-   For example, if ``autodoc_default_flags`` is set to ``['members',
-   'undoc-members']``, and you write a directive like this::
-
-      .. automodule:: foo
-         :no-undoc-members:
-
-   the directive will be interpreted as if only ``:members:`` was given.
 
    .. versionadded:: 1.0
 
+   .. deprecated:: 1.8
+
+      Integrated into :confval:`autodoc_default_options`.
+
+.. confval:: autodoc_default_options
+
+   The default options for autodoc directives.  They are applied to all autodoc
+   directives automatically.  It must be a dictionary which maps option names
+   to the values.  For example::
+
+       autodoc_default_options = {
+           'members': 'var1, var2',
+           'member-order': 'bysource',
+           'special-members': '__init__',
+           'undoc-members': None,
+           'exclude-members': '__weakref__'
+       }
+
+   Setting ``None`` is equivalent to giving the option name in the list format
+   (i.e. it means "yes/true/on").
+
+   The supported options are ``'members'``, ``'member-order'``,
+   ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
+   ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'`` and
+   ``'exclude-members'``.
+
+   .. versionadded:: 1.8
+
 .. confval:: autodoc_docstring_signature
 
    Functions imported from C modules cannot be introspected, and therefore the
@@ -372,7 +409,7 @@ There are also new config values that you can set:
    This value contains a list of modules to be mocked up. This is useful when
    some external dependencies are not met at build time and break the building
    process. You may only specify the root package of the dependencies
-   themselves and ommit the sub-modules:
+   themselves and omit the sub-modules:
 
    .. code-block:: python
 
@@ -386,6 +423,34 @@ There are also new config values that you can set:
       This config value only requires to declare the top-level modules that
       should be mocked.
 
+.. confval:: autodoc_warningiserror
+
+   This value controls the behavior of :option:`sphinx-build -W` during
+   importing modules.
+   If ``False`` is given, autodoc forcedly suppresses the error if the imported
+   module emits warnings.  By default, ``True``.
+
+.. confval:: autodoc_inherit_docstrings
+
+   This value controls the docstrings inheritance.
+   If set to True the docstring for classes or methods, if not explicitly set,
+   is inherited form parents.
+
+   The default is ``True``.
+
+   .. versionadded:: 1.7
+
+.. confval:: suppress_warnings
+   :noindex:
+
+   :mod:`autodoc` supports to suppress warning messages via
+   :confval:`suppress_warnings`.  It allows following warnings types in
+   addition:
+
+   * autodoc
+   * autodoc.import_object
+
+
 Docstring preprocessing
 -----------------------
 

doc/usage/extensions/autosectionlabel.rst

@@ -27,6 +27,7 @@ default. The ``autosectionlabel_prefix_document`` configuration variable can be
 used to make headings which appear multiple times but in different documents
 unique.
 
+
 Configuration
 -------------
 

doc/usage/extensions/autosummary.rst

@@ -25,7 +25,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
    These files by default contain only the corresponding
    :mod:`sphinx.ext.autodoc` directive, but can be customized with templates.
 
-
 .. rst:directive:: autosummary
 
    Insert a table that contains links to documented items, and a short summary
@@ -59,7 +58,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
    :event:`autodoc-process-docstring` and :event:`autodoc-process-signature`
    hooks as :mod:`~sphinx.ext.autodoc`.
 
-
    **Options**
 
    * If you want the :rst:dir:`autosummary` table to also serve as a
@@ -205,6 +203,13 @@ The following variables available in the templates:
    List containing names of all members of the module or class.  Only available
    for modules and classes.
 
+.. data:: inherited_members
+
+   List containing names of all inherited members of class.  Only available for
+   classes.
+
+   .. versionadded:: 1.8.0
+
 .. data:: functions
 
    List containing names of "public" functions in the module.  Here, "public"
@@ -237,7 +242,7 @@ 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
+   contexts. For instance, this prevents asterisks making things bold. This
    replaces the builtin Jinja `escape filter`_ that does html-escaping.
 
 .. function:: underline(s, line='=')

doc/usage/extensions/coverage.rst

@@ -4,7 +4,6 @@
 .. module:: sphinx.ext.coverage
    :synopsis: Check Python modules and C API for coverage in the documentation.
 
-
 This extension features one additional builder, the :class:`CoverageBuilder`.
 
 .. class:: CoverageBuilder
@@ -14,7 +13,6 @@ This extension features one additional builder, the :class:`CoverageBuilder`.
 
 .. todo:: Write this section.
 
-
 Several new configuration values can be used to specify what the builder
 should check: