Merge branch 'master' into docs/extension-tutorials

.appveyor.yml

@@ -5,21 +5,15 @@ environment:
     PYTHONWARNINGS: all
 
   matrix:
-    - PYTHON: 27
-      DOCUTILS: 0.12
-      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
+    - PYTHON: 37
+    - PYTHON: 37-x64
 
 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 -r test-reqs.txt
+  - C:\Python%PYTHON%\python.exe -m pip install .[test,websupport]
+
+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" }
       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,5 +1,13 @@
 Subject: <what happen when you do on which document project>
 
+<!--
+  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,
+-->
+
 ### Problem
 - <Detail of problem>
 

.gitignore

@@ -5,11 +5,17 @@
 
 .dir-locals.el
 .cache/
+.idea
 .mypy_cache/
+.pytest_cache/
 .ropeproject/
 TAGS
 .tags
-.tox
+.tox/
+.tx/
+.venv/
+.coverage
+htmlcov
 .DS_Store
 sphinx/pycode/Grammar*pickle
 distribute-*
@@ -19,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,53 @@
 language: python
 sudo: false
 dist: trusty
-cache:
-  directories:
-    - $HOME/.cache/pip
-python:
-  - "pypy-5.4.1"
-  - "3.6"
-  - "3.5"
-  - "3.4"
-  - "2.7"
-  - "nightly"
+cache: pip
+
 env:
   global:
-    - TEST='-v --durations 25'
     - PYTHONFAULTHANDLER=x
-    - PYTHONWARNINGS=all
     - SKIP_LATEX_BUILD=1
-  matrix:
-    - DOCUTILS=0.12
-    - DOCUTILS=0.13.1
+    - IS_PYTHON=true
+
 matrix:
-  exclude:
-    - python: "3.4"
-      env: DOCUTILS=0.12
-    - python: "3.5"
-      env: DOCUTILS=0.12
-    - python: "3.6"
-      env: DOCUTILS=0.12
-    - python: nightly
-      env: DOCUTILS=0.12
-    - python: "pypy-5.4.1"
-      env: DOCUTILS=0.12
-addons:
-  apt:
-    packages:
-      - graphviz
-      - imagemagick
+  include:
+    - python: '3.5'
+      env:
+        - TOXENV=du13
+    - python: '3.6'
+      env:
+        - TOXENV=py36
+        - PYTEST_ADDOPTS="--cov ./ --cov-append --cov-config setup.cfg"
+    - python: '3.7'
+      env: TOXENV=py37
+      dist: xenial
+      sudo: true
+    - python: 'nightly'
+      env: TOXENV=py38
+      dist: xenial
+      sudo: true
+    - python: '3.6'
+      env: TOXENV=docs
+    - python: '3.6'
+      env: TOXENV=mypy
+    - python: '3.6'
+      env: TOXENV=flake8
+
+    - language: node_js
+      node_js:
+        - 10.7
+      env: IS_PYTHON=false
+      before_script:
+        - export DISPLAY=:99.0
+        - sh -e /etc/init.d/xvfb start
+
 install:
-  - pip install -U pip setuptools
-  - pip install docutils==$DOCUTILS
-  - pip install -r test-reqs.txt
-  - if [[ $TRAVIS_PYTHON_VERSION == '3.6' ]]; then python3.6 -m pip install mypy typed-ast; fi
+  - if [ $IS_PYTHON = true ]; then pip install -U tox codecov; fi
+  - if [ $IS_PYTHON = false ]; then npm install; fi
+
 script:
-  - flake8
-  - if [[ $TRAVIS_PYTHON_VERSION == '3.6' ]]; then make style-check type-check test-async; fi
-  - if [[ $TRAVIS_PYTHON_VERSION != '3.6' ]]; then make test; fi
+  - if [ $IS_PYTHON = true ]; then tox -- -v; fi
+  - if [ $IS_PYTHON = false ]; then npm 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,21 @@ 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
 
 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
-   minor version.
+   ``master`` branch for next major version, or ``X.Y`` branch for next
+   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
@@ -91,17 +92,22 @@ 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
-   fixes), use the ``stable`` branch. ::
+   fixes), use the ``X.Y`` branch. ::
 
-       git checkout stable
+       git checkout X.Y
 
    For new features or other substantial changes that should wait until the
-   next major release, use the ``master`` branch.
+   next major release, use the ``master`` branch  (see `Branch Model`_ for
+   detail).
 
-#. Optional: setup a virtual environment. ::
+#. Setup a virtual environment.
 
-       virtualenv ~/sphinxenv
-       . ~/sphinxenv/bin/activate
+   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 +118,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
-       make test
+   * To list all possible targets::
 
-   * Again, it's useful to turn on deprecation warnings on so they're shown in
-     the test output::
+         tox -av
 
-       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
-       make clean html latexpdf
+   * To run unit tests for a specific Python version and turn on deprecation
+     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
-       make type-check
+   * To run code style and type checks::
 
-   * Run the unit tests under different Python environments using
-     :program:`tox`::
+         tox -e mypy
+         tox -e flake8
 
-       pip install tox
-       tox -v
+   * Arguments to ``pytest`` can be passed via ``tox``, e.g. in order to run a
+     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 +194,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.
 
@@ -262,7 +287,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 +308,26 @@ 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
-     $ node_modules/.bin/grunt build # -> dest/*.global.js
+     npm install
+     node_modules/.bin/grunt build # -> dest/*.global.js
+
+
+Branch Model
+------------
+
+Sphinx project uses following branches for developing.
+
+``master``
+    Used for main development.  All improvement and refactoring, bug fixes
+    are allowed.
+
+``X.Y``
+    Where ``X.Y`` is the ``MAJOR.MINOR`` release.  Used to maintain current
+    stable release.  Only bug fixes and stable changes are allowed.  Only the
+    most recent stable release is currently retained. When a new version is
+    released, the old release branch will be deleted and replaced by an
+    equivalent tag.
+
 
 Deprecating a feature
 ---------------------
@@ -299,14 +342,17 @@ 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,
-the first release of Sphinx that deprecates a feature (``A.B``) should raise a
-``RemovedInSphinxXXWarning`` (where XX is the Sphinx version where the feature
-will be removed) when the deprecated feature is invoked. Assuming we have good
-test coverage, these warnings are converted to errors when running the test
-suite with warnings enabled: ``python -Wall tests/run.py``. Thus, when adding
-a ``RemovedInSphinxXXWarning`` you need to eliminate or silence any warnings
-generated when running the tests.
+As the :ref:`deprecation-policy` describes, the first release of Sphinx that
+deprecates a feature (``A.B``) should raise a ``RemovedInSphinxXXWarning``
+(where ``XX`` is the Sphinx version where the feature will be removed) when the
+deprecated feature is invoked. Assuming we have good test coverage, these
+warnings are converted to errors when running the test suite with warnings
+enabled::
+
+    pytest -Wall
+
+Thus, when adding a ``RemovedInSphinxXXWarning`` you need to eliminate or
+silence any warnings generated when running the tests.
 
 .. _deprecation-policy:
 
@@ -362,3 +408,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,235 +12,398 @@ interesting examples.
 Documentation using the alabaster theme
 ---------------------------------------
 
-* CodePy: https://documen.tician.de/codepy/
-* MeshPy: https://documen.tician.de/meshpy/
-* PyCuda: https://documen.tician.de/pycuda/
-* PyLangAcq: http://pylangacq.org/
+* `Alabaster <https://alabaster.readthedocs.io/>`__
+* `Blinker <https://pythonhosted.org/blinker/>`__
+* `Calibre <https://manual.calibre-ebook.com/>`__
+* `Click <http://click.pocoo.org/>`__ (customized)
+* `coala <https://docs.coala.io/>`__ (customized)
+* `CodePy <https://documen.tician.de/codepy/>`__
+* `Fabric <https://docs.fabfile.org/>`__
+* `Fityk <https://fityk.nieto.pl/>`__
+* `Flask <http://flask.pocoo.org/docs/>`__
+* `Flask-OpenID <https://pythonhosted.org/Flask-OpenID/>`__
+* `Invoke <https://docs.pyinvoke.org/>`__
+* `Jinja <http://jinja.pocoo.org/docs/>`__
+* `Lino <http://www.lino-framework.org/>`__ (customized)
+* `marbl <https://getmarbl.readthedocs.io/>`__
+* `MDAnalysis <https://www.mdanalysis.org/docs/>`__ (customized)
+* `MeshPy <https://documen.tician.de/meshpy/>`__
+* `Molecule <https://molecule.readthedocs.io/>`__
+* `PyCUDA <https://documen.tician.de/pycuda/>`__
+* `PyOpenCL <https://documen.tician.de/pyopencl/>`__
+* `PyLangAcq <http://pylangacq.org/>`__
+* `pytest <https://docs.pytest.org/>`__ (customized)
+* `python-apt <https://apt.alioth.debian.org/python-apt-doc/>`__
+* `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
 -------------------------------------
 
-* APSW: https://rogerbinns.github.io/apsw/
-* Calibre: http://manual.calibre-ebook.com/
-* Cython: http://docs.cython.org/
-* Cormoran: http://cormoran.nhopkg.org/docs/
-* Director: http://pythonhosted.org/director/
-* F2py: http://f2py.sourceforge.net/docs/
-* Genomedata:
-  http://noble.gs.washington.edu/proj/genomedata/doc/1.2.2/genomedata.html
-* GSL Shell: http://www.nongnu.org/gsl-shell/
-* Hands-on Python Tutorial:
-  http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
-* Hedge: https://documen.tician.de/hedge/
-* Leo: http://leoeditor.com/
-* Lino: http://www.lino-framework.org/
-* mpmath: http://mpmath.org/doc/current/
-* OpenEXR: http://excamera.com/articles/26/doc/index.html
-* OpenGDA: http://www.opengda.org/gdadoc/html/
-* openWNS: http://docs.openwns.org/
-* Pioneers and Prominent Men of Utah: http://pioneers.rstebbing.com/
-* PyCantonese: http://pycantonese.org/
-* Pyevolve: http://pyevolve.sourceforge.net/
-* PyMQI: http://pythonhosted.org/pymqi/
-* pySPACE: http://pyspace.github.io/pyspace/
-* Python: https://docs.python.org/3/
-* python-apt: http://apt.alioth.debian.org/python-apt-doc/
-* PyUblas: https://documen.tician.de/pyublas/
-* Ring programming language: http://ring-lang.sourceforge.net/doc/index.html
-* Scapy: http://www.secdev.org/projects/scapy/doc/
-* Segway: http://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html
-* SymPy: http://docs.sympy.org/
-* WTForms: http://wtforms.simplecodes.com/docs/
-* z3c: http://www.ibiblio.org/paulcarduner/z3ctutorial/
-
-
-Documentation using a customized version of the classic theme
--------------------------------------------------------------
-
-* Advanced Generic Widgets:
-  http://xoomer.virgilio.it/infinity77/AGW_Docs/index.html
-* Arb: http://fredrikj.net/arb/
-* Bazaar: http://doc.bazaar.canonical.com/en/
-* CakePHP: http://book.cakephp.org/2.0/en/index.html
-* Chaco: http://docs.enthought.com/chaco/
-* Chef: https://docs.chef.io/index.html
-* Djagios: http://djagios.org/
-* EZ-Draw: http://pageperso.lif.univ-mrs.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html
-* GetFEM++: http://home.gna.org/getfem/
-* Google or-tools:
-  https://or-tools.googlecode.com/svn/trunk/documentation/user_manual/index.html
-* GPAW: https://wiki.fysik.dtu.dk/gpaw/
-* Grok: http://grok.zope.org/doc/current/
-* Kaa: http://api.freevo.org/kaa-base/
-* LEPL: http://www.acooke.org/lepl/
-* Mayavi: http://docs.enthought.com/mayavi/mayavi/
-* NICOS: http://trac.frm2.tum.de/nicos/doc/nicos-master/index.html
-* NOC: http://redmine.nocproject.org/projects/noc
-* NumPy: http://docs.scipy.org/doc/numpy/reference/
-* OpenCV: http://docs.opencv.org/
-* Peach^3: http://peach3.nl/doc/latest/userdoc/
-* Pygame: http://www.pygame.org/docs/
-* Sage: http://www.sagemath.org/doc/
-* SciPy: http://docs.scipy.org/doc/scipy/reference/
-* simuPOP: http://simupop.sourceforge.net/manual_release/build/userGuide.html
-* Sprox: http://sprox.org/
-* TurboGears: http://turbogears.readthedocs.org/en/latest/
-* Varnish: https://www.varnish-cache.org/docs/
-* Zentyal: http://doc.zentyal.org/
-* Zope: http://docs.zope.org/zope2/index.html
-* zc.async: http://pythonhosted.org/zc.async/1.5.0/
-
+* `Advanced Generic Widgets <http://xoomer.virgilio.it/infinity77/AGW_Docs/>`__ (customized)
+* `Apache CouchDB <http://docs.couchdb.org/>`__ (customized)
+* `APSW <https://rogerbinns.github.io/apsw/>`__
+* `Arb <http://arblib.org/>`__
+* `Bazaar <http://doc.bazaar.canonical.com/>`__ (customized)
+* `Beautiful Soup <https://www.crummy.com/software/BeautifulSoup/bs4/doc/>`__
+* `Blender <https://docs.blender.org/api/current/>`__
+* `Bugzilla <https://bugzilla.readthedocs.io/>`__
+* `Buildbot <https://docs.buildbot.net/latest/>`__
+* `CMake <https://cmake.org/documentation/>`__ (customized)
+* `Chaco <https://docs.enthought.com/chaco/>`__ (customized)
+* `CORE <https://downloads.pf.itd.nrl.navy.mil/docs/core/core-html/>`__
+* `CORE Python modules <https://downloads.pf.itd.nrl.navy.mil/docs/core/core-python-html/>`__
+* `Cormoran <http://cormoran.nhopkg.org/docs/>`__
+* `DEAP <https://deap.readthedocs.io/>`__ (customized)
+* `Director <https://pythonhosted.org/director/>`__
+* `EZ-Draw <https://pageperso.lif.univ-mrs.fr/~edouard.thiel/ez-draw/doc/en/html/ez-manual.html>`__ (customized)
+* `F2py <http://f2py.sourceforge.net/docs/>`__
+* `Generic Mapping Tools (GMT) <https://gmt.soest.hawaii.edu/doc/latest/>`__ (customized)
+* `Genomedata <https://noble.gs.washington.edu/proj/genomedata/doc/1.3.3/>`__
+* `GetFEM++ <http://getfem.org/>`__ (customized)
+* `Glasgow Haskell Compiler <https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/>`__ (customized)
+* `Grok <http://grok.zope.org/doc/current/>`__ (customized)
+* `GROMACS <http://manual.gromacs.org/documentation/>`__
+* `GSL Shell <https://www.nongnu.org/gsl-shell/>`__
+* `Hands-on Python Tutorial <https://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/>`__
+* `Kaa <https://api.freevo.org/kaa-base/>`__ (customized)
+* `Leo <https://leoeditor.com/>`__
+* `LEPL <http://www.acooke.org/lepl/>`__ (customized)
+* `Mayavi <https://docs.enthought.com/mayavi/mayavi/>`__ (customized)
+* `MediaGoblin <https://mediagoblin.readthedocs.io/>`__ (customized)
+* `mpmath <http://mpmath.org/doc/current/>`__
+* `OpenCV <https://docs.opencv.org/>`__ (customized)
+* `OpenEXR <http://excamera.com/articles/26/doc/index.html>`__
+* `OpenGDA <http://www.opengda.org/gdadoc/html/>`__
+* `Peach^3 <https://peach3.nl/doc/latest/userdoc/>`__ (customized)
+* `Plone <https://docs.plone.org/>`__ (customized)
+* `PyEMD <https://pyemd.readthedocs.io/>`__
+* `Pyevolve <http://pyevolve.sourceforge.net/>`__
+* `Pygame <https://www.pygame.org/docs/>`__ (customized)
+* `PyMQI <https://pythonhosted.org/pymqi/>`__
+* `PyQt4 <http://pyqt.sourceforge.net/Docs/PyQt4/>`__ (customized)
+* `PyQt5 <http://pyqt.sourceforge.net/Docs/PyQt5/>`__ (customized)
+* `Python 2 <https://docs.python.org/2/>`__
+* `Python 3 <https://docs.python.org/3/>`__ (customized)
+* `Python Packaging Authority <https://www.pypa.io/>`__ (customized)
+* `Ring programming language <http://ring-lang.sourceforge.net/doc/>`__ (customized)
+* `SageMath <https://doc.sagemath.org/>`__ (customized)
+* `Segway <https://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html>`__
+* `simuPOP <http://simupop.sourceforge.net/manual_release/build/userGuide.html>`__ (customized)
+* `Sprox <http://sprox.org/>`__ (customized)
+* `SymPy <https://docs.sympy.org/>`__
+* `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
 ---------------------------------------
 
-* Fityk: http://fityk.nieto.pl/
-* MapServer: http://mapserver.org/
-* Matplotlib: http://matplotlib.org/
-* Music21: http://web.mit.edu/music21/doc/index.html
-* NetworkX: http://networkx.github.io/
-* Pweave: http://mpastell.com/pweave/
-* Pyre: http://docs.danse.us/pyre/sphinx/
-* Pysparse: http://pysparse.sourceforge.net/
-* PyTango:
-  http://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango/latest/index.html
-* Python Wild Magic: http://vmlaker.github.io/pythonwildmagic/
-* Reteisi: http://www.reteisi.org/contents.html
-* Sqlkit: http://sqlkit.argolinux.org/
-* Turbulenz: http://docs.turbulenz.com/
-* WebFaction: https://docs.webfaction.com/
+* `cartopy <https://scitools.org.uk/cartopy/docs/latest/>`__
+* `Jython <http://www.jython.org/docs/>`__
+* `Matplotlib <https://matplotlib.org/>`__
+* `MDAnalysis Tutorial <https://www.mdanalysis.org/MDAnalysisTutorial/>`__
+* `NetworkX <https://networkx.github.io/>`__
+* `PyCantonese <http://pycantonese.org/>`__
+* `Pyre <http://docs.danse.us/pyre/sphinx/>`__
+* `pySPACE <https://pyspace.github.io/pyspace/>`__
+* `Pysparse <http://pysparse.sourceforge.net/>`__
+* `PyTango <https://www.esrf.eu/computing/cs/tango/tango_doc/kernel_doc/pytango/latest/>`__
+* `Python Wild Magic <https://vmlaker.github.io/pythonwildmagic/>`__ (customized)
+* `Reteisi <http://www.reteisi.org/contents.html>`__ (customized)
+* `Sqlkit <http://sqlkit.argolinux.org/>`__ (customized)
+* `Turbulenz <http://docs.turbulenz.com/>`__
 
+Documentation using the nature theme
+------------------------------------
+
+* `Alembic <http://alembic.zzzcomputing.com/>`__
+* `Cython <http://docs.cython.org/>`__
+* `easybuild <https://easybuild.readthedocs.io/>`__
+* `jsFiddle <http://doc.jsfiddle.net/>`__
+* `libLAS <https://www.liblas.org/>`__ (customized)
+* `Lmod <https://lmod.readthedocs.io/>`__
+* `MapServer <https://mapserver.org/>`__ (customized)
+* `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
 -----------------------------------------
 
-* ASE: https://wiki.fysik.dtu.dk/ase/ (sphinx_rtd_theme)
-* C/C++ Development with Eclipse: http://eclipsebook.in/ (agogo)
-* ESWP3 (http://eswp3.org) (sphinx_rtd_theme)
-* Jinja: http://jinja.pocoo.org/ (scrolls)
-* jsFiddle: http://doc.jsfiddle.net/ (nature)
-* libLAS: http://www.liblas.org/ (nature)
-* Linguistica: http://linguistica-uchicago.github.io/lxa5/ (sphinx_rtd_theme)
-* MoinMoin: https://moin-20.readthedocs.io/en/latest/ (sphinx_rtd_theme)
-* MPipe: http://vmlaker.github.io/mpipe/ (sphinx13)
-* Paver: http://paver.readthedocs.io/en/latest/
-* pip: https://pip.pypa.io/en/latest/ (sphinx_rtd_theme)
-* Programmieren mit PyGTK und Glade (German):
-  http://www.florian-diesch.de/doc/python-und-glade/online/ (agogo)
-* PyPubSub: http://pypubsub.readthedocs.io/ (bizstyle)
-* Pyramid web framework:
-  http://docs.pylonsproject.org/projects/pyramid/en/latest/ (pyramid)
-* Quex: http://quex.sourceforge.net/doc/html/main.html
-* Satchmo: http://docs.satchmoproject.com/en/latest/ (sphinx_rtd_theme)
-* Setuptools: http://pythonhosted.org/setuptools/ (nature)
-* SimPy: http://simpy.readthedocs.org/en/latest/
-* Spring Python: http://docs.spring.io/spring-python/1.2.x/sphinx/html/ (nature)
-* sqlparse: http://python-sqlparse.googlecode.com/svn/docs/api/index.html
-  (agogo)
-* Sylli: http://sylli.sourceforge.net/ (nature)
-* Tuleap Open ALM: https://tuleap.net/doc/en/ (nature)
-* Valence: http://docs.valence.desire2learn.com/ (haiku)
+* `Breathe <https://breathe.readthedocs.io/>`__ (haiku)
+* `MPipe <https://vmlaker.github.io/mpipe/>`__ (sphinx13)
+* `NLTK <https://www.nltk.org/>`__ (agogo)
+* `Programmieren mit PyGTK und Glade (German) <https://www.florian-diesch.de/doc/python-und-glade/online/>`__ (agogo, customized)
+* `PyPubSub <https://pypubsub.readthedocs.io/>`__ (bizstyle)
+* `Pylons <https://docs.pylonsproject.org/projects/pylons-webframework/>`__ (pyramid)
+* `Pyramid web framework <https://docs.pylonsproject.org/projects/pyramid/>`__ (pyramid)
+* `Sphinx <http://www.sphinx-doc.org/>`__ (sphinx13) :-)
+* `Valence <https://docs.valence.desire2learn.com/>`__ (haiku, customized)
 
+Documentation using sphinx_rtd_theme
+------------------------------------
 
-Documentation using a custom theme/integrated in a site
--------------------------------------------------------
+* `Annotator <http://docs.annotatorjs.org/>`__
+* `Ansible <https://docs.ansible.com/>`__ (customized)
+* `Arcade <http://arcade.academy/>`__
+* `aria2 <https://aria2.github.io/manual/en/html/>`__
+* `ASE <https://wiki.fysik.dtu.dk/ase/>`__
+* `Autofac <http://docs.autofac.org/>`__
+* `BigchainDB <https://docs.bigchaindb.com/>`__
+* `Blocks <https://blocks.readthedocs.io/>`__
+* `bootstrap-datepicker <https://bootstrap-datepicker.readthedocs.io/>`__
+* `Certbot <https://letsencrypt.readthedocs.io/>`__
+* `Chainer <https://docs.chainer.org/>`__ (customized)
+* `CherryPy <https://docs.cherrypy.org/>`__
+* `cloud-init <https://cloudinit.readthedocs.io/>`__
+* `CodeIgniter <https://www.codeigniter.com/user_guide/>`__
+* `Conda <https://conda.io/docs/>`__
+* `Corda <https://docs.corda.net/>`__
+* `Dask <https://dask.pydata.org/>`__
+* `Databricks <https://docs.databricks.com/>`__ (customized)
+* `Dataiku DSS <https://doc.dataiku.com/>`__
+* `DNF <https://dnf.readthedocs.io/>`__
+* `edX <https://docs.edx.org/>`__
+* `Electrum <http://docs.electrum.org/>`__
+* `Elemental <http://libelemental.org/documentation/dev/>`__
+* `ESWP3 <https://eswp3.readthedocs.io/>`__
+* `Ethereum Homestead <http://www.ethdocs.org/>`__
+* `Fidimag <https://fidimag.readthedocs.io/>`__
+* `Flake8 <http://flake8.pycqa.org/>`__
+* `FluidDyn <https://fluiddyn.readthedocs.io/>`__
+* `Fluidsim <https://fluidsim.readthedocs.io/>`__
+* `GeoNode <http://docs.geonode.org/>`__
+* `Godot <https://godot.readthedocs.io/>`__
+* `Graylog <http://docs.graylog.org/>`__
+* `GPAW <https://wiki.fysik.dtu.dk/gpaw/>`__ (customized)
+* `HDF5 for Python (h5py) <http://docs.h5py.org/>`__
+* `Hyperledger Fabric <https://hyperledger-fabric.readthedocs.io/>`__
+* `Hyperledger Sawtooth <https://intelledger.github.io/>`__
+* `IdentityServer <http://docs.identityserver.io/>`__
+* `Idris <http://docs.idris-lang.org/>`__
+* `javasphinx <https://bronto-javasphinx.readthedocs.io/>`__
+* `Julia <https://julia.readthedocs.io/>`__
+* `Jupyter Notebook <https://jupyter-notebook.readthedocs.io/>`__
+* `Lasagne <https://lasagne.readthedocs.io/>`__
+* `latexindent.pl <https://latexindentpl.readthedocs.io/>`__
+* `Linguistica <https://linguistica-uchicago.github.io/lxa5/>`__
+* `Linux kernel <https://www.kernel.org/doc/html/latest/index.html>`__
+* `MathJax <https://docs.mathjax.org/>`__
+* `MDTraj <http://mdtraj.org/latest/>`__ (customized)
+* `MICrobial Community Analysis (micca) <http://micca.org/docs/latest/>`__
+* `MicroPython <https://docs.micropython.org/>`__
+* `Minds <https://www.minds.org/docs/>`__ (customized)
+* `Mink <http://mink.behat.org/>`__
+* `Mockery <http://docs.mockery.io/>`__
+* `mod_wsgi <https://modwsgi.readthedocs.io/>`__
+* `MoinMoin <https://moin-20.readthedocs.io/>`__
+* `Mopidy <https://docs.mopidy.com/>`__
+* `MyHDL <http://docs.myhdl.org/>`__
+* `Nextflow <https://www.nextflow.io/docs/latest/index.html>`__
+* `NICOS <https://forge.frm2.tum.de/nicos/doc/nicos-master/>`__ (customized)
+* `Pelican <http://docs.getpelican.com/>`__
+* `picamera <https://picamera.readthedocs.io/>`__
+* `Pillow <https://pillow.readthedocs.io/>`__
+* `pip <https://pip.pypa.io/>`__
+* `Paver <https://paver.readthedocs.io/>`__
+* `peewee <http://docs.peewee-orm.com/>`__
+* `Phinx <http://docs.phinx.org/>`__
+* `phpMyAdmin <https://docs.phpmyadmin.net/>`__
+* `PROS <https://pros.cs.purdue.edu/v5/>`__ (customized)
+* `Pweave <http://mpastell.com/pweave/>`__
+* `PyPy <http://doc.pypy.org/>`__
+* `python-sqlparse <https://sqlparse.readthedocs.io/>`__
+* `PyVISA <https://pyvisa.readthedocs.io/>`__
+* `Read The Docs <https://docs.readthedocs.io/>`__
+* `Free your information from their silos (French) <http://redaction-technique.org/>`__ (customized)
+* `Releases Sphinx extension <https://releases.readthedocs.io/>`__
+* `Qtile <http://docs.qtile.org/>`__
+* `Quex <http://quex.sourceforge.net/doc/html/main.html>`__
+* `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/>`__
 
-* Blender: https://www.blender.org/api/250PythonDoc/
-* Blinker: http://discorporate.us/projects/Blinker/docs/
-* Ceph: http://docs.ceph.com/docs/master/
-* Classy: http://www.pocoo.org/projects/classy/
-* DEAP: http://deap.gel.ulaval.ca/doc/0.8/index.html
-* Django: https://docs.djangoproject.com/
-* Elemental: http://libelemental.org/documentation/dev/index.html
-* Enterprise Toolkit for Acrobat products:
-  http://www.adobe.com/devnet-docs/acrobatetk/
-* e-cidadania: http://e-cidadania.readthedocs.org/en/latest/
-* Flask: http://flask.pocoo.org/docs/
-* Flask-OpenID: http://pythonhosted.org/Flask-OpenID/
-* Gameduino: http://excamera.com/sphinx/gameduino/
-* GeoServer: http://docs.geoserver.org/
-* gevent: http://www.gevent.org/
-* GHC - Glasgow Haskell Compiler: http://downloads.haskell.org/~ghc/master/users-guide/
-* Glashammer: http://glashammer.org/
-* Istihza (Turkish Python documentation project): http://belgeler.istihza.com/py2/
-* Lasso: http://lassoguide.com/
-* Manage documentation such as source code (fr): http://redaction-technique.org/
-* MathJax: http://docs.mathjax.org/en/latest/
-* MirrorBrain: http://mirrorbrain.org/docs/
-* MyHDL: http://docs.myhdl.org/en/latest/
-* nose: http://nose.readthedocs.org/en/latest/
-* NoTex: https://www.notex.ch/overview/
-* ObjectListView: http://objectlistview.sourceforge.net/python/
-* Open ERP: https://doc.odoo.com/
-* OpenCV: http://docs.opencv.org/
-* Open Dylan: http://opendylan.org/documentation/
-* OpenLayers: http://docs.openlayers.org/
-* PyEphem: http://rhodesmill.org/pyephem/
-* German Plone user manual: http://www.hasecke.com/plone-benutzerhandbuch/
-* PSI4: http://www.psicode.org/psi4manual/master/index.html
-* Pylons: http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/
-* PyMOTW: https://pymotw.com/2/
-* python-aspectlib: http://python-aspectlib.readthedocs.org/en/latest/
-  (`sphinx-py3doc-enhanced-theme`_)
-* QGIS: http://qgis.org/en/docs/index.html
-* qooxdoo: http://manual.qooxdoo.org/current/
-* Roundup: http://www.roundup-tracker.org/
-* Seaborn: https://stanford.edu/~mwaskom/software/seaborn/
-* Selenium: http://docs.seleniumhq.org/docs/
-* Self: http://www.selflanguage.org/
-* Substance D: http://docs.pylonsproject.org/projects/substanced/en/latest/
-* Tablib: http://tablib.org/
-* SQLAlchemy: http://www.sqlalchemy.org/docs/
-* tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
-* Ubuntu packaging guide: http://packaging.ubuntu.com/html/
-* Werkzeug: http://werkzeug.pocoo.org/docs/
-* WFront: http://discorporate.us/projects/WFront/
+Documentation using sphinx_bootstrap_theme
+------------------------------------------
 
-.. _sphinx-py3doc-enhanced-theme: https://pypi.python.org/pypi/sphinx_py3doc_enhanced_theme
+* `Bootstrap Theme <https://ryan-roemer.github.io/sphinx-bootstrap-theme/>`__
+* `C/C++ Software Development with Eclipse <https://eclipsebook.in/>`__
+* `Dataverse <http://guides.dataverse.org/>`__
+* `e-cidadania <https://e-cidadania.readthedocs.io/>`__
+* `Hangfire <http://docs.hangfire.io/>`__
+* `Hedge <https://documen.tician.de/hedge/>`__
+* `ObsPy <https://docs.obspy.org/>`__
+* `Open Dylan <https://opendylan.org/documentation/>`__
+* `Pootle <http://docs.translatehouse.org/projects/pootle/>`__
+* `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/>`__
+* `Astropy <http://docs.astropy.org/>`__
+* `Bokeh <https://bokeh.pydata.org/>`__
+* `Boto 3 <https://boto3.readthedocs.io/>`__
+* `CakePHP <https://book.cakephp.org/>`__
+* `CasperJS <http://docs.casperjs.org/>`__
+* `Ceph <http://docs.ceph.com/docs/master/>`__
+* `Chef <https://docs.chef.io/>`__
+* `CKAN <https://docs.ckan.org/>`__
+* `Confluent Platform <https://docs.confluent.io/>`__
+* `Django <https://docs.djangoproject.com/>`__
+* `Doctrine <https://www.doctrine-project.org/>`__
+* `Enterprise Toolkit for Acrobat products <https://www.adobe.com/devnet-docs/acrobatetk/>`__
+* `Gameduino <http://excamera.com/sphinx/gameduino/>`__
+* `gensim <https://radimrehurek.com/gensim/>`__
+* `GeoServer <http://docs.geoserver.org/>`__
+* `gevent <http://www.gevent.org/>`__
+* `GHC - Glasgow Haskell Compiler <https://downloads.haskell.org/~ghc/master/users-guide/>`__
+* `Guzzle <http://docs.guzzlephp.org/>`__
+* `H2O.ai <http://docs.h2o.ai/>`__
+* `Istihza (Turkish Python documentation project) <https://belgeler.yazbel.com/python-istihza/>`__
+* `Kombu <http://docs.kombu.me/>`__
+* `Lasso <http://lassoguide.com/>`__
+* `Mako <http://docs.makotemplates.org/>`__
+* `MirrorBrain <http://mirrorbrain.org/docs/>`__
+* `MongoDB <https://docs.mongodb.com/>`__
+* `Music21 <https://web.mit.edu/music21/doc/>`__
+* `MyHDL <http://docs.myhdl.org/>`__
+* `nose <https://nose.readthedocs.io/>`__
+* `ns-3 <https://www.nsnam.org/documentation/>`__
+* `NumPy <https://docs.scipy.org/doc/numpy/reference/>`__
+* `ObjectListView <http://objectlistview.sourceforge.net/python/>`__
+* `OpenERP <https://doc.odoo.com/>`__
+* `OpenCV <https://docs.opencv.org/>`__
+* `OpenLayers <http://docs.openlayers.org/>`__
+* `OpenTURNS <https://openturns.github.io/openturns/master/>`__
+* `Open vSwitch <http://docs.openvswitch.org/>`__
+* `PlatformIO <https://docs.platformio.org/>`__
+* `PyEphem <http://rhodesmill.org/pyephem/>`__
+* `Pygments <http://pygments.org/docs/>`__
+* `Plone User Manual (German) <https://www.hasecke.com/plone-benutzerhandbuch/4.0/>`__
+* `PSI4 <http://www.psicode.org/psi4manual/master/index.html>`__
+* `PyMOTW <https://pymotw.com/2/>`__
+* `python-aspectlib <https://python-aspectlib.readthedocs.io/>`__ (`sphinx_py3doc_enhanced_theme <https://pypi.org/project/sphinx_py3doc_enhanced_theme/>`__)
+* `QGIS <https://qgis.org/en/docs/index.html>`__
+* `qooxdoo <https://www.qooxdoo.org/current/>`__
+* `Roundup <http://www.roundup-tracker.org/>`__
+* `SaltStack <https://docs.saltstack.com/>`__
+* `scikit-learn <http://scikit-learn.org/stable/>`__
+* `SciPy <https://docs.scipy.org/doc/scipy/refrence/>`__
+* `Scrapy <https://doc.scrapy.org/>`__
+* `Seaborn <https://seaborn.pydata.org/>`__
+* `Selenium <https://docs.seleniumhq.org/docs/>`__
+* `Self <http://www.selflanguage.org/>`__
+* `Substance D <https://docs.pylonsproject.org/projects/substanced/>`__
+* `Sulu <http://docs.sulu.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
 -------------------------------------------
 
-* A personal page: http://www.dehlia.in/
-* Benoit Boissinot: http://bboissin.appspot.com/
-* lunarsite: http://lunaryorn.de/
-* The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
-* UC Berkeley Advanced Control Systems course:
-  http://msc.berkeley.edu/tomizuka/me233spring13/
-* VOR: http://www.vor-cycling.be/
-
+* `Arizona State University PHY494/PHY598/CHM598 Simulation approaches to Bio-and Nanophysics <https://becksteinlab.physics.asu.edu/pages/courses/2013/SimBioNano/>`__ (classic)
+* `Benoit Boissinot <https://bboissin.appspot.com/>`__ (classic, customized)
+* `Computer Networks, Parallelization, and Simulation Laboratory (CNPSLab) <https://lab.miletic.net/>`__ (sphinx_rtd_theme)
+* `Deep Learning Tutorials <http://www.deeplearning.net/tutorial/>`__ (sphinxdoc)
+* `Eric Holscher <http://ericholscher.com/>`__ (alabaster)
+* `Lei Ma's Statistical Mechanics lecture notes <http://statisticalphysics.openmetric.org/>`__ (sphinx_bootstrap_theme)
+* `Loyola University Chicago COMP 339-439 Distributed Systems course <https://books.cs.luc.edu/distributedsystems/>`__ (sphinx_bootstrap_theme)
+* `Pylearn2 <http://www.deeplearning.net/software/pylearn2/>`__ (sphinxdoc, customized)
+* `PyXLL <https://www.pyxll.com/>`__ (sphinx_bootstrap_theme, customized)
+* `SciPy Cookbook <https://scipy-cookbook.readthedocs.io/>`__ (sphinx_rtd_theme)
+* `The Wine Cellar Book <https://www.thewinecellarbook.com/doc/en/>`__ (sphinxdoc)
+* `Thomas Cokelaer's Python, Sphinx and reStructuredText tutorials <https://thomas-cokelaer.info/tutorials/>`__ (standard)
+* `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
 ---------------------------
 
-* "The ``repoze.bfg`` Web Application Framework":
-  http://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379
-* A Theoretical Physics Reference book: http://www.theoretical-physics.net/
-* "Simple and Steady Way of Learning for Software Engineering" (in Japanese):
-  http://www.amazon.co.jp/dp/477414259X/
-* "Expert Python Programming":
-  https://www.packtpub.com/application-development/expert-python-programming
-* "Expert Python Programming" (Japanese translation):
-  http://www.amazon.co.jp/dp/4048686291/
-* "Pomodoro Technique Illustrated" (Japanese translation):
-  http://www.amazon.co.jp/dp/4048689525/
-* "Python Professional Programming" (in Japanese):
-  http://www.amazon.co.jp/dp/4798032948/
-* "Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski":
-  http://www.hasecke.eu/Dekalog/
-* The "Varnish Book":
-  http://book.varnish-software.com/4.0/
-* "Learning Sphinx" (in Japanese):
-  http://www.oreilly.co.jp/books/9784873116488/
-* "LassoGuide":
-  http://www.lassosoft.com/Lasso-Documentation
-* "Software-Dokumentation mit Sphinx": http://www.amazon.de/dp/1497448689/
+* `"The Art of Community" (Japanese translation) <https://www.oreilly.co.jp/books/9784873114958/>`__
+* `"Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski" <https://literatur.hasecke.com/post/die-wahrheit-des-sehens-dekalog-kieslowski/>`__
+* `"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 2nd Edition" (Japanese translation) <https://www.amazon.co.jp/dp/4048930613/>`__
+* `"The Hitchhiker's Guide to Python" <https://docs.python-guide.org/>`__
+* `"LassoGuide" <http://www.lassosoft.com/Lasso-Documentation>`__
+* `"Learning Sphinx" (in Japanese) <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)" <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/>`__
+* `"Pomodoro Technique Illustrated" (Japanese translation) <https://www.amazon.co.jp/dp/4048689525/>`__
+* `"Python Professional Programming" (in Japanese) <http://www.amazon.co.jp/dp/4798032948/>`__
+* `"Python Professional Programming 2nd Edition" (in Japanese) <https://www.amazon.co.jp/dp/479804315X/>`__
+* `"Python Professional Programming 3rd Edition" (in Japanese) <https://www.amazon.co.jp/dp/4798053821/>`__
+* `"Real World HTTP -- Learning The Internet and Web Technology via its history and code (Japanese)" <https://www.oreilly.co.jp/books/9784873118048/>`__
+* `"Redmine Primer 5th Edition (in Japanese)" <https://www.shuwasystem.co.jp/products/7980html/4825.html>`__
+* `"The repoze.bfg Web Application Framework" <https://www.amazon.com/repoze-bfg-Web-Application-Framework-Version/dp/0615345379>`__
+* `"The Self-Taught Programmer" (Japanese translation) <https://www.amazon.co.jp/dp/4822292274/>`__
+* `"Simple and Steady Way of Learning for Software Engineering" (in Japanese) <https://www.amazon.co.jp/dp/477414259X/>`__
+* `"Software-Dokumentation mit Sphinx" <https://www.amazon.de/dp/1497448689/>`__
+* `"Theoretical Physics Reference" <https://www.theoretical-physics.net/>`__
+* `"The Varnish Book" <https://info.varnish-software.com/the-varnish-book>`__
 
+Theses produced using Sphinx
+----------------------------
 
-Thesis using Sphinx
--------------------
+* `"A Web-Based System for Comparative Analysis of OpenStreetMap Data by the Use
+  of CouchDB" <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>`__
+* `"The Sphinx Thesis Resource" <https://jterrace.github.io/sphinxtr/>`__
 
-* "A Web-Based System for Comparative Analysis of OpenStreetMap Data
-  by the Use of CouchDB":
-  https://www.yumpu.com/et/document/view/11722645/masterthesis-markusmayr-0542042
+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-2018 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
-
-.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
+PYTHON ?= python3
 
+.PHONY: all
 all: clean-pyc clean-backupfiles style-check type-check test
 
-style-check:
-	@PYTHONWARNINGS=all $(PYTHON) utils/check_sources.py $(DONT_CHECK) .
-
-type-check:
-	mypy sphinx/
-
+.PHONY: clean
 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:
-	@$(PYTHON) utils/reindent.py -r -n .
-
+.PHONY: test
 test:
-	@cd tests; $(PYTHON) run.py --ignore py35 -v $(TEST)
-
-test-async:
-	@cd tests; $(PYTHON) run.py -v $(TEST)
+	@$(PYTHON) -m pytest -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
-.. image:: https://readthedocs.org/projects/sphinx/badge/
+   :target: https://pypi.org/project/Sphinx/
+   :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)
 
-=================
-README for Sphinx
-=================
+.. image:: https://ci.appveyor.com/api/projects/status/github/sphinx-doc/sphinx?branch=master&svg=true
+   :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/_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:
-    a <a href="http://readthedocs.org/projects/sphinx/downloads/pdf/stable/">PDF version</a> generated from
-    the LaTeX Sphinx produces, and
-    a <a href="http://readthedocs.org/projects/sphinx/downloads/epub/stable/">EPUB version</a>.
-   {%endtrans%}
+    You can also download PDF/EPUB versions of the Sphinx documentation
+    from pop up menu on lower right corner.{%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>{%trans%}This documentation is for version <b><a href="changes.html">{{ version }}</a></b>, which is
-  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>
+<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%}Install Sphinx 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>
-<form action="http://groups.google.com/group/sphinx-users/boxsubscribe"
-      style="padding-left: 0.5em">
-  <input type="text" name="email" value="your@email" style="font-size: 90%; width: 120px"
-         onfocus="$(this).val('');"/>
-  <input type="submit" name="sub" value="Subscribe" style="font-size: 90%; width: 70px"/>
+<p>{%trans%}Join the <a href="https://groups.google.com/group/sphinx-users">sphinx-users</a> mailing list on Google Groups:{%endtrans%}</p>
+<div class="subscribeformwrapper">
+<form action="https://groups.google.com/group/sphinx-users/boxsubscribe"
+      class="subscribeform">
+  <input type="text" name="email" value="your@email"
+         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-2018 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-2018 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

@@ -3,6 +3,7 @@
 # Sphinx documentation build configuration file
 
 import re
+
 import sphinx
 
 
@@ -15,7 +16,7 @@ templates_path = ['_templates']
 exclude_patterns = ['_build']
 
 project = 'Sphinx'
-copyright = '2007-2017, Georg Brandl and the Sphinx team'
+copyright = '2007-2018, Georg Brandl and the Sphinx team'
 version = sphinx.__display_version__
 release = version
 show_authors = True
@@ -38,11 +39,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 +57,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 +80,7 @@ latex_elements = {
 ''',
 }
 latex_show_urls = 'footnote'
+latex_use_xindy = True
 
 autodoc_member_order = 'groupwise'
 todo_include_todos = True
@@ -84,6 +100,8 @@ man_pages = [
      'template generator', '', 1),
     ('man/sphinx-apidoc', 'sphinx-apidoc', 'Sphinx API doc generator tool',
      '', 1),
+    ('man/sphinx-autogen', 'sphinx-autogen', 'Generate autodoc stub pages',
+     '', 1),
 ]
 
 texinfo_documents = [
@@ -94,7 +112,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/']
@@ -134,3 +152,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

@@ -7,24 +7,25 @@ Sphinx documentation contents
 .. toctree::
    :maxdepth: 2
 
+   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
+
    intro
-   tutorial
-   invocation
-   rest
-   markup/index
-   domains
-   builders
-   config
-   intl
+   man/index
    theming
-   setuptools
    templating
    latex
-   markdown
-   extensions
    extdev/index
    extdev/tutorials/index
-   websupport
 
    faq
    glossary
@@ -34,6 +35,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`.
 
@@ -106,40 +106,40 @@ own extensions.
 
 .. _aafigure: https://launchpad.net/aafigure
 .. _gnuplot: http://www.gnuplot.info/
-.. _paver: http://paver.github.io/paver/
-.. _Sword: http://www.crosswire.org/sword/
+.. _paver: https://paver.readthedocs.io/en/latest/
+.. _Sword: https://www.crosswire.org/sword/
 .. _Lilypond: http://lilypond.org/
 .. _sdedit: http://sdedit.sourceforge.net/
-.. _Trac: http://trac.edgewall.org
-.. _TracLinks: http://trac.edgewall.org/wiki/TracLinks
-.. _OmegaT: http://www.omegat.org/
+.. _Trac: https://trac.edgewall.org/
+.. _TracLinks: https://trac.edgewall.org/wiki/TracLinks
+.. _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/
-.. _YouTube: http://www.youtube.com/
-.. _ClearQuest: http://www-03.ibm.com/software/products/en/clearquest
-.. _Zope interfaces: http://docs.zope.org/zope.interface/README.html
-.. _slideshare: http://www.slideshare.net/
+.. _exceltable: https://pythonhosted.org/sphinxcontrib-exceltable/
+.. _YouTube: https://www.youtube.com/
+.. _ClearQuest: https://www.ibm.com/us-en/marketplace/rational-clearquest
+.. _Zope interfaces: https://zopeinterface.readthedocs.io/en/latest/README.html
+.. _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/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.
-This function is called at initialization time with one argument, the
-application object representing the Sphinx process.
+Each Sphinx extension is a Python module with at least a :func:`setup`
+function.  This function is called at initialization time with one argument,
+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
-   needs the features provided by another extension.
+.. automethod:: Sphinx.setup_extension(name)
 
-.. method:: Sphinx.add_builder(builder)
+.. automethod:: Sphinx.require_sphinx(version)
 
-   Register a new builder.  *builder* must be a class that inherits from
-   :class:`~sphinx.builders.Builder`.
+.. automethod:: Sphinx.connect(event, callback)
 
-.. method:: Sphinx.add_config_value(name, default, rebuild)
+.. automethod:: Sphinx.disconnect(listener_id)
 
-   Register a configuration value.  This is necessary for Sphinx to recognize
-   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:
+.. automethod:: Sphinx.add_builder(builder)
 
-   * ``'env'`` if a change in the setting only takes effect when a document is
-     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.
+.. automethod:: Sphinx.add_config_value(name, default, rebuild)
 
-   .. versionchanged:: 0.4
-      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.
+.. automethod:: Sphinx.add_event(name)
 
-   .. versionchanged:: 0.6
-      Changed *rebuild* from a simple boolean (equivalent to ``''`` or
-      ``'env'``) to a string.  However, booleans are still accepted and
-      converted internally.
+.. automethod:: Sphinx.set_translator(name, translator_class)
 
-.. 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
-   :class:`~sphinx.domains.Domain`) known to Sphinx.
+.. automethod:: Sphinx.add_enumerable_node(node, figtype, title_getter=None, \*\*kwds)
 
-   .. 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
-   a domain with its ``.name``.  The new domain must be a subclass of the
-   existing one.
+.. automethod:: Sphinx.add_generic_role(name, nodeclass)
 
-   .. 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
-   subclass of :class:`~sphinx.domains.Index`.
+.. method:: Sphinx.add_directive_to_domain(domain, name, func, content, arguments, \*\*options)
+.. 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
-   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`).
+.. automethod:: Sphinx.add_transform(transform)
 
-   .. 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.
-   It may also be used in the future to validate nodes in the parsed documents.
+.. automethod:: Sphinx.add_css_file(filename, **kwargs)
 
-   Node visitor functions for the Sphinx HTML, LaTeX, text and manpage writers
-   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:
+.. automethod:: Sphinx.add_latex_package(packagename, options=None)
 
-   .. 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):
-          self.body.append(self.starttag(node, 'math'))
-      def depart_math_html(self, node):
-          self.body.append('</math>')
+.. automethod:: Sphinx.add_autodoc_attrgetter(type, getter)
 
-      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
-   on the node when encountered in a document to translate.
+.. automethod:: Sphinx.add_source_suffix(suffix, filetype)
 
-   .. versionchanged:: 0.5
-      Added the support for keyword arguments giving visit functions.
+.. automethod:: Sphinx.add_source_parser(parser)
 
-.. 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
-   automatically. And then the users can refer it using :rst:role:`numref`.
+.. automethod:: Sphinx.add_html_theme(name, theme_path)
 
-   *figtype* is a type of enumerable nodes.  Each figtypes have individual
-   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.
+.. automethod:: Sphinx.add_html_math_renderer(name, inline_renderers, block_renderers)
 
-   *title_getter* is a getter function to obtain the title of node.  It takes
-   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.add_message_catalog(catalog, locale_dir)
 
+.. 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
-   return values of all callbacks as a list.  Do not emit core Sphinx events
-   in extensions!
+   .. automethod:: emit(event, \*arguments)
 
-.. method:: Sphinx.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
+   .. automethod:: emit_firstresult(event, \*arguments)
 
 
-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
-   the build; just raise an exception (:exc:`sphinx.errors.SphinxError` or a
-   custom subclass) to do that.
+   Target project.  See :class:`.Project`.
 
-.. 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
-
-   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__``.
+.. autodata:: version_info
 
 
 The Config object
 -----------------
 
-.. module:: sphinx.config
+.. currentmodule:: sphinx.config
 
-.. class:: 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``.
+.. autoclass:: Config
 
 
 .. _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
-   raised, Sphinx will abort the build and present the exception category and
-   message to the user.
+.. autoexception:: ConfigError
 
-   Extensions are encouraged to derive from this exception for their custom
-   errors.
+.. autoexception:: ExtensionError
 
-   Exceptions *not* derived from :exc:`SphinxError` are treated as unexpected
-   and shown to the user with a part of the traceback (and the full traceback
-   saved in a temporary file).
+.. autoexception:: ThemeError
 
-   .. attribute:: category
-
-      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.
+.. autoexception:: VersionRequirementError

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,8 @@ 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
 
+.. _ext-metadata:
+
 Extension metadata
 ------------------
 
@@ -63,6 +65,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
@@ -79,6 +86,7 @@ APIs used for writing extensions
 
    tutorials/index
    appapi
+   projectapi
    envapi
    builderapi
    collectorapi
@@ -87,3 +95,597 @@ APIs used for writing extensions
    parserapi
    nodes
    logging
+   i18n
+   utils
+
+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
+
+   * - ``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.ext.config.check_unicode()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.ext.doctest.doctest_encode()``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.testing.util.remove_unicode_literal()``
+     - 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.osutil.walk()``
+     - 2.0
+     - 4.0
+     - ``os.walk()``
+
+   * - ``sphinx.util.pycompat.u``
+     - 2.0
+     - 4.0
+     - N/A
+
+   * - ``sphinx.application.Sphinx._setting_up_extension``
+     - 2.0
+     - 3.0
+     - N/A
+
+   * - ``sphinx.writers.latex.LaTeXTranslator.babel_defmacro()``
+     - 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
-
-     logger = logging.getLogger(__name__)
-     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)
+   .. method:: SphinxLoggerAdapter.error(msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.critical(msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.warning(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
-        colored as ``"darkred"``.  The others are not colored.
+        The color of logs.  By default, error level logs are colored as
+        ``"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.verbose(level, msg, *args, **kwargs)
-   .. method:: SphinxLoggerAdapter.debug(level, msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.info(msg, *args, **kwargs)
+   .. method:: SphinxLoggerAdapter.verbose(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
-        colored as ``"darkgray"``, and debug2 level ones are ``"lightgray"``.
-        The others are not colored.
+        The color of logs.  By default, info and verbose level logs are not colored,
+        and deug level ones are colored as ``"darkgray"``.
 
-.. function:: pending_logging()
+.. autofunction:: pending_logging()
 
-   Marks all logs as pending::
+.. autofunction:: pending_warnings()
 
-     with pending_logging():
-       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`.
+.. autofunction:: prefixed_warnings()

doc/extdev/markupapi.rst

@@ -70,14 +70,6 @@ using :meth:`.Sphinx.add_directive` or :meth:`.Sphinx.add_directive_to_domain`.
       The absolute line number on which the directive appeared.  This is not
       always a useful value; use :attr:`srcline` instead.
 
-   .. attribute:: src
-
-      The source file of the directive.
-
-   .. attribute:: srcline
-
-      The line number in the source file on which the directive appeared.
-
    .. attribute:: content_offset
 
       Internal offset of the directive content.  Used when calling
@@ -125,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,22 +11,19 @@ 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`_
-   version 0.12 or greater which comes with built-in Sphinx integration.  See
-   the :ref:`builders` section for details.
+   replacement for the LaTeX builder.
 
    .. _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
@@ -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,
-      see the chapter :ref:`domains`.
+      languages are much easier to write.
+
+      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
-docutils_ and Jinja2_ libraries.  Sphinx should work with docutils version 0.10
-or some (not broken) SVN trunk snapshot.  If you like to have source code
-highlighting support, you must also install the Pygments_ library.
+Sphinx needs at least **Python 3.5** to run, as well as the docutils_ and
+Jinja2_ libraries. Sphinx should work with docutils version 0.12 or some (not
+broken) SVN trunk snapshot.
 
 .. _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
-advanced sections in this manual for the topics it discusses.
+See :doc:`/usage/quickstart` for an introduction.  It also contains links to
+more advanced sections in this manual for the topics it discusses.

doc/invocation.rst

@@ -1,566 +0,0 @@
-.. default-role:: any
-
-.. _invocation:
-
-Invocation of sphinx-quickstart
-===============================
-
-The :program:`sphinx-quickstart` script generates a Sphinx documentation set.
-It is called like this:
-
-.. code-block:: console
-
-   $ sphinx-quickstart [options] [projectdir]
-
-where *projectdir* is the Sphinx documentation set directory in which you want
-to place. If you omit *projectdir*, files are generated into current directory
-by default.
-
-The :program:`sphinx-quickstart` script has several options:
-
-.. program:: sphinx-quickstart
-
-.. option:: -q, --quiet
-
-   Quiet mode that will skips interactive wizard to specify options.
-   This option requires `-p`, `-a` and `-v` options.
-
-.. option:: -h, --help, --version
-
-   Display usage summary or Sphinx version.
-
-
-Structure options
------------------
-
-.. option:: --sep
-
-   If specified, separate source and build directories.
-
-.. option:: --dot=DOT
-
-   Inside the root directory, two more directories will be created;
-   "_templates" for custom HTML templates and "_static" for custom stylesheets
-   and other static files. You can enter another prefix (such as ".") to
-   replace the underscore.
-
-Project basic options
----------------------
-
-.. option:: -p PROJECT, --project=PROJECT
-
-   Project name will be set. (see :confval:`project`).
-
-.. option:: -a AUTHOR, --author=AUTHOR
-
-   Author names. (see :confval:`copyright`).
-
-.. option:: -v VERSION
-
-   Version of project. (see :confval:`version`).
-
-.. option:: -r RELEASE, --release=RELEASE
-
-   Release of project. (see :confval:`release`).
-
-.. option:: -l LANGUAGE, --language=LANGUAGE
-
-   Document language. (see :confval:`language`).
-
-.. option:: --suffix=SUFFIX
-
-   Source file suffix. (see :confval:`source_suffix`).
-
-.. option:: --master=MASTER
-
-   Master document name. (see :confval:`master_doc`).
-
-.. option:: --epub
-
-   Use epub.
-
-Extension options
------------------
-
-.. option:: --ext-autodoc
-
-   Enable `sphinx.ext.autodoc` extension.
-
-.. option:: --ext-doctest
-
-   Enable `sphinx.ext.doctest` extension.
-
-.. option:: --ext-intersphinx
-
-   Enable `sphinx.ext.intersphinx` extension.
-
-.. option:: --ext-todo
-
-   Enable `sphinx.ext.todo` extension.
-
-.. option:: --ext-coverage
-
-   Enable `sphinx.ext.coverage` extension.
-
-.. option:: --ext-imgmath
-
-   Enable `sphinx.ext.imgmath` extension.
-
-.. option:: --ext-mathjax
-
-   Enable `sphinx.ext.mathjax` extension.
-
-.. option:: --ext-ifconfig
-
-   Enable `sphinx.ext.ifconfig` extension.
-
-.. option:: --ext-viewcode
-
-   Enable `sphinx.ext.viewcode` extension.
-
-.. option:: --extensions=EXTENSIONS
-
-   Enable arbitary extensions.
-
-
-Makefile and Batchfile creation options
----------------------------------------
-
-.. option:: --use-make-mode, --no-use-make-mode
-
-   Makefile/make.bat uses (or not use) make-mode. Default is use.
-
-   .. versionchanged:: 1.5
-      make-mode is default.
-
-.. option:: --makefile, --no-makefile
-
-   Create (or not create) makefile.
-
-.. option:: --batchfile, --no-batchfile
-
-   Create (or not create) batchfile
-
-
-.. versionadded:: 1.3
-   Add various options for sphinx-quickstart invocation.
-
-Project templating
-------------------
-
-.. option:: -t, --templatedir=TEMPLATEDIR
-
-   Template directory for template files.  You can modify the templates of
-   sphinx project files generated by quickstart.  Following Jinja2 template
-   files are allowed:
-
-   * master_doc.rst_t
-   * conf.py_t
-   * Makefile_t
-   * Makefile.new_t
-   * make.bat_t
-   * make.bat.new_t
-
-   In detail, please refer the system template files Sphinx provides.
-   (sphinx/templates/quickstart)
-
-.. option:: -d NAME=VALUE
-
-   Define a template variable
-
-.. versionadded:: 1.5
-   Project templating options for sphinx-quickstart
-
-
-Invocation of sphinx-build
-==========================
-
-The :program:`sphinx-build` script builds a Sphinx documentation set.  It is
-called like this:
-
-.. code-block:: console
-
-   $ sphinx-build [options] sourcedir builddir [filenames]
-
-where *sourcedir* is the :term:`source directory`, and *builddir* is the
-directory in which you want to place the built documentation.  Most of the time,
-you don't need to specify any *filenames*.
-
-The :program:`sphinx-build` script has several options:
-
-.. program:: sphinx-build
-
-.. option:: -b buildername
-
-   The most important option: it selects a builder.  The most common builders
-   are:
-
-   **html**
-      Build HTML pages.  This is the default builder.
-
-   **dirhtml**
-      Build HTML pages, but with a single directory per document.  Makes for
-      prettier URLs (no ``.html``) if served from a webserver.
-
-   **singlehtml**
-      Build a single HTML with the whole content.
-
-   **htmlhelp**, **qthelp**, **devhelp**, **epub**
-      Build HTML files with additional information for building a documentation
-      collection in one of these formats.
-
-   **applehelp**
-      Build an Apple Help Book.  Requires :program:`hiutil` and
-      :program:`codesign`, which are not Open Source and presently only
-      available on Mac OS X 10.6 and higher.
-
-   **latex**
-      Build LaTeX sources that can be compiled to a PDF document using
-      :program:`pdflatex`.
-
-   **man**
-      Build manual pages in groff format for UNIX systems.
-
-   **texinfo**
-      Build Texinfo files that can be processed into Info files using
-      :program:`makeinfo`.
-
-   **text**
-      Build plain text files.
-
-   **gettext**
-      Build gettext-style message catalogs (``.pot`` files).
-
-   **doctest**
-      Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest`
-      extension is enabled.
-
-   **linkcheck**
-      Check the integrity of all external links.
-
-   **xml**
-     Build Docutils-native XML files.
-
-   **pseudoxml**
-     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.
-   Extensions can add their own builders.
-
-.. option:: -a
-
-   If given, always write all output files.  The default is to only write output
-   files for new and changed source files.  (This may not apply to all
-   builders.)
-
-.. option:: -E
-
-   Don't use a saved :term:`environment` (the structure caching all
-   cross-references), but rebuild it completely.  The default is to only read
-   and parse source files that are new or have changed since the last run.
-
-.. option:: -t tag
-
-   Define the tag *tag*.  This is relevant for :rst:dir:`only` directives that
-   only include their content if this tag is set.
-
-   .. versionadded:: 0.6
-
-.. option:: -d path
-
-   Since Sphinx has to read and parse all source files before it can write an
-   output file, the parsed source files are cached as "doctree pickles".
-   Normally, these files are put in a directory called :file:`.doctrees` under
-   the build directory; with this option you can select a different cache
-   directory (the doctrees can be shared between all builders).
-
-.. option:: -j N
-
-   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.
-
-   .. versionadded:: 1.2
-      This option should be considered *experimental*.
-
-.. option:: -c path
-
-   Don't look for the :file:`conf.py` in the source directory, but use the given
-   configuration directory instead.  Note that various other files and paths
-   given by configuration values are expected to be relative to the
-   configuration directory, so they will have to be present at this location
-   too.
-
-   .. versionadded:: 0.3
-
-.. option:: -C
-
-   Don't look for a configuration file; only take options via the ``-D`` option.
-
-   .. versionadded:: 0.5
-
-.. option:: -D setting=value
-
-   Override a configuration value set in the :file:`conf.py` file.  The value
-   must be a number, string, list or dictionary value.
-
-   For lists, you can separate elements with a comma like this: ``-D
-   html_theme_path=path1,path2``.
-
-   For dictionary values, supply the setting name and key like this:
-   ``-D latex_elements.docclass=scrartcl``.
-
-   For boolean values, use ``0`` or ``1`` as the value.
-
-   .. versionchanged:: 0.6
-      The value can now be a dictionary value.
-
-   .. versionchanged:: 1.3
-      The value can now also be a list value.
-
-.. option:: -A name=value
-
-   Make the *name* assigned to *value* in the HTML templates.
-
-   .. versionadded:: 0.5
-
-.. option:: -n
-
-   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".
-
-.. option:: -N
-
-   Do not emit colored output.
-
-.. option:: -v
-
-   Increase verbosity (loglevel).  This option can be given up to three times
-   to get more debug logging output.  It implies :option:`-T`.
-
-   .. versionadded:: 1.2
-
-.. option:: -q
-
-   Do not output anything on standard output, only write warnings and errors to
-   standard error.
-
-.. option:: -Q
-
-   Do not output anything on standard output, also suppress warnings.  Only
-   errors are written to standard error.
-
-.. option:: -w file
-
-   Write warnings (and errors) to the given file, in addition to standard error.
-
-.. option:: -W
-
-   Turn warnings into errors.  This means that the build stops at the first
-   warning and ``sphinx-build`` exits with exit status 1.
-
-.. option:: -T
-
-   Display the full traceback when an unhandled exception occurs.  Otherwise,
-   only a summary is displayed and the traceback information is saved to a file
-   for further analysis.
-
-   .. versionadded:: 1.2
-
-.. option:: -P
-
-   (Useful for debugging only.)  Run the Python debugger, :mod:`pdb`, if an
-   unhandled exception occurs while building.
-
-.. option:: -h, --help, --version
-
-   Display usage summary or Sphinx version.
-
-   .. versionadded:: 1.2
-
-You can also give one or more filenames on the command line after the source and
-build directories.  Sphinx will then try to build only these output files (and
-their dependencies).
-
-Environment variables
----------------------
-
-The :program:`sphinx-build` refers following environment variables:
-
-.. describe:: MAKE
-
-   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
-----------------
-
-The :file:`Makefile` and :file:`make.bat` files created by
-:program:`sphinx-quickstart` usually run :program:`sphinx-build` only with the
-:option:`-b` and :option:`-d` options.  However, they support the following
-variables to customize behavior:
-
-.. describe:: PAPER
-
-   The value for '"papersize"` key of :confval:`latex_elements`.
-
-.. describe:: SPHINXBUILD
-
-   The command to use instead of ``sphinx-build``.
-
-.. describe:: BUILDDIR
-
-   The build directory to use instead of the one chosen in
-   :program:`sphinx-quickstart`.
-
-.. describe:: SPHINXOPTS
-
-   Additional options for :program:`sphinx-build`.
-
-.. _when-deprecation-warnings-are-displayed:
-
-Deprecation Warnings
---------------------
-
-If any deprecation warning like ``RemovedInSphinxXXXWarning`` are displayed
-when building a user's document, some Sphinx extension is using deprecated
-features. In that case, please report it to author of the extension.
-
-To disable the deprecation warnings, please set ``PYTHONWARNINGS=`` environment
-variable to your environment. For example:
-
-* ``PYTHONWARNINGS= make html`` (Linux/Mac)
-* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
-* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
-* modify your Makefile/make.bat and set the environment variable
-
-
-.. _invocation-apidoc:
-
-Invocation of sphinx-apidoc
-===========================
-
-The :program:`sphinx-apidoc` generates completely automatic API documentation
-for a Python package.  It is called like this:
-
-.. code-block:: console
-
-   $ sphinx-apidoc [options] -o outputdir packagedir [pathnames]
-
-where *packagedir* is the path to the package to document, and *outputdir* is
-the directory where the generated sources are placed.  Any *pathnames* given
-are paths to be excluded ignored during generation.
-
-.. warning::
-
-   ``sphinx-apidoc`` generates reST files that use :mod:`sphinx.ext.autodoc` to
-   document all found modules.  If any modules have side effects on import,
-   these will be executed by ``autodoc`` 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.
-
-
-The :program:`sphinx-apidoc` script has several options:
-
-.. program:: sphinx-apidoc
-
-.. option:: -o outputdir
-
-   Gives the directory in which to place the generated output.
-
-.. option:: -f, --force
-
-   Normally, sphinx-apidoc does not overwrite any files.  Use this option to
-   force the overwrite of all files that it generates.
-
-.. option:: -n, --dry-run
-
-   With this option given, no files will be written at all.
-
-.. option:: -e, --separate
-
-   Put documentation for each module on its own page.
-
-   .. versionadded:: 1.2
-
-.. option:: -P, --private
-
-   Include "_private" modules.
-
-   .. versionadded:: 1.2
-
-.. option:: -s suffix
-
-   This option selects the file name suffix of output files.  By default, this
-   is ``rst``.
-
-.. option:: -d maxdepth
-
-   This sets the maximum depth of the table of contents, if one is generated.
-
-.. option:: -l, --follow-links
-
-   This option makes sphinx-apidoc follow symbolic links when recursing the
-   filesystem to discover packages and modules. You may need it if you want
-   to generate documentation from a source directory managed by
-   `collective.recipe.omelette
-   <https://pypi.python.org/pypi/collective.recipe.omelette/>`_.
-   By default, symbolic links are skipped.
-
-   .. versionadded:: 1.2
-
-.. option:: -T, --no-toc
-
-   This prevents the generation of a table-of-contents file ``modules.rst``.
-   This has no effect when :option:`--full` is given.
-
-.. option:: -E, --no-headings
-
-   Don't create headings for the module/package packages (e.g. when the
-   docstrings already contain them).
-
-   .. versionadded:: 1.2
-
-.. option:: -F, --full
-
-   This option makes sphinx-apidoc create a full Sphinx project, using the same
-   mechanism as :program:`sphinx-quickstart`.  Most configuration values are set
-   to default values, but you can influence the most important ones using the
-   following options.
-
-.. option:: --implicit-namespaces
-
-   By default sphinx-apidoc processes sys.path searching for modules only.
-   Python 3.3 introduced :pep:`420` implicit namespaces that allow module path
-   structures such as ``foo/bar/module.py`` or ``foo/bar/baz/__init__.py``
-   (notice that ``bar`` and ``foo`` are namespaces, not modules).
-
-   Specifying this option interprets paths recursively according to PEP-0420.
-
-.. option:: -M
-
-   This option makes sphinx-apidoc put module documentation before submodule
-   documentation.
-
-.. option:: -a
-
-   Append module_path to sys.path.
-
-.. option:: -H project
-
-   Sets the project name to put in generated files (see :confval:`project`).
-
-.. option:: -A author
-
-   Sets the author name(s) to put in generated files (see :confval:`copyright`).
-
-.. option:: -V version
-
-   Sets the project version to put in generated files (see :confval:`version`).
-
-.. option:: -R release
-
-   Sets the project release to put in generated files (see :confval:`release`).

doc/latex.rst

@@ -1,4 +1,4 @@
-.. highlightlang:: python
+.. highlight:: python
 
 .. _latex:
 
@@ -8,8 +8,8 @@ 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`).
+For details of the LaTeX/PDF builder command line invocation, refer to
+:py:class:`~sphinx.builders.latex.LaTeXBuilder`.
 
 .. raw:: latex
 
@@ -29,12 +29,15 @@ The *latex* target does not benefit from pre-prepared themes like the
          cautionBgColor={named}{LightCyan}}
    \relax
 
+.. _latex-basic:
 
 Basic customization
 -------------------
 
-It is achieved via usage of the
-:ref:`latex-options` as described in :doc:`config`. For example::
+The *latex* target does not benefit from prepared themes.
+
+Basic customization is obtained via usage of the :ref:`latex-options`. For
+example::
 
    # inside conf.py
    latex_engine = 'xelatex'
@@ -61,28 +64,31 @@ It is achieved via usage of the
 .. highlight:: latex
 
 If the size of the ``'preamble'`` contents becomes inconvenient, one may move
-all needed macros into some file :file:`mystyle.tex` of the project source
+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}',
+   '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 needed to set appropriately :confval:`latex_additional_files`, for
+It is then needed to set appropriately :confval:`latex_additional_files`, for
 example::
 
-   latex_additional_files = ["mystyle.tex"]
+   latex_additional_files = ["mystyle.sty"]
 
 .. _latexsphinxsetup:
 
 The LaTeX style file options
 ----------------------------
 
+Additional customization is possible via LaTeX options of the Sphinx style
+file.
+
 The sphinxsetup interface
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``'sphinxsetup'`` key of :confval:`latex_elements` provides a convenient
-interface to the package options of the Sphinx style file::
+interface::
 
    latex_elements = {
        'sphinxsetup': 'key1=value1, key2=value2, ...',
@@ -102,40 +108,39 @@ inside the document preamble, like this::
 
 .. versionadded:: 1.5
 
-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. This is what is done for this documentation, for local styling
-of this chapter in the PDF output::
+.. hint::
 
-   .. 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 in PDF is styled::
 
-      \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::
+        \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 "xcolor" package::
+   The colors used in the above are provided by the ``svgnames`` option of the
+   "xcolor" package::
 
       latex_elements = {
           'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
@@ -189,14 +194,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
-       of continuation hints (currently right aligned only) will be
-       customizable.
+    .. versionchanged:: 1.7
+       the default changed from ``false`` to ``true``.
+
+``verbatimcontinuedalign``, ``verbatimcontinuesalign``
+    default ``c``. 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 +271,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 +302,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.
 
@@ -356,10 +377,9 @@ Macros
      with LaTeX packages.
 - more text styling: ``\sphinxstyle<bar>`` with ``<bar>`` one of
   ``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
-  ``sidebartitle``, ``othertitle``, ``sidebarsubtitle``,
-  ``theadfamily``, ``emphasis``, ``literalemphasis``, ``strong``,
-  ``literalstrong``, ``abbreviation``, ``literalintitle``, ``codecontinued``,
-  ``codecontinues``.
+  ``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``theadfamily``,
+  ``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``,
+  ``abbreviation``, ``literalintitle``, ``codecontinued``, ``codecontinues``
 
   .. versionadded:: 1.5
      these macros were formerly hard-coded as non customizable ``\texttt``,
@@ -369,13 +389,6 @@ 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
   :file:`sphinxmanual.cls`) of standard ``\tableofcontents``.
@@ -384,6 +397,8 @@ Macros
      formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
 - the ``\maketitle`` command is redefined by the class files
   :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`.
+- the citation reference is typeset via ``\sphinxcite`` which is a wrapper
+  of standard ``\cite``.
 
 Environments
 ~~~~~~~~~~~~
@@ -430,6 +445,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 +471,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/index.rst

@@ -0,0 +1,22 @@
+Man Pages
+=========
+
+These are the applications provided as part of Sphinx.
+
+Core Applications
+-----------------
+
+.. toctree::
+   :maxdepth: 3
+
+   sphinx-quickstart
+   sphinx-build
+
+Additional Applications
+-----------------------
+
+.. toctree::
+   :maxdepth: 3
+
+   sphinx-apidoc
+   sphinx-autogen

doc/man/sphinx-apidoc.rst

@@ -1,23 +1,24 @@
-:orphan:
-
-sphinx-apidoc manual page
-=========================
+sphinx-apidoc
+=============
 
 Synopsis
 --------
 
-**sphinx-apidoc** [*options*] -o <*outputdir*> <*sourcedir*> [*pathnames* ...]
-
+**sphinx-apidoc** [*OPTIONS*] -o <*OUTPUT_PATH*> <*MODULE_PATH*> [*EXCLUDE_PATTERN*, ...]
 
 Description
 -----------
 
 :program:`sphinx-apidoc` is a tool for automatic generation of Sphinx sources
-that, using the autodoc extension, document a whole package in the style of
-other automatic API documentation tools.
+that, using the :rst:dir:`autodoc` extension, document a whole package in the
+style of other automatic API documentation tools.
 
-*sourcedir* must point to a Python package.  Any *pathnames* given are paths to
-be excluded from the generation.
+*MODULE_PATH* is the path to a Python package to document, and *OUTPUT_PATH* is
+the directory where the generated sources are placed. Any *EXCLUDE_PATTERN*\s
+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::
 
@@ -28,42 +29,113 @@ be excluded from the generation.
    If you document scripts (as opposed to library modules), make sure their main
    routine is protected by a ``if __name__ == '__main__'`` condition.
 
-
 Options
 -------
 
--o <outputdir>      Directory to place the output files.  If it does not exist,
-                    it is created.
--f, --force         Usually, apidoc does not overwrite files, unless this option
-                    is given.
--l, --follow-links  Follow symbolic links.
--n, --dry-run       If given, apidoc does not create any files.
--s <suffix>         Suffix for the source files generated, default is ``rst``.
--d <maxdepth>       Maximum depth for the generated table of contents file.
--T, --no-toc        Do not create a table of contents file.
--F, --full          If given, a full Sphinx project is generated (``conf.py``,
-                    ``Makefile`` etc.) using sphinx-quickstart.
--e, --separate      Put each module file in its own page.
--E, --no-headings   Don't create headings for the modules/packages
--P, --private       Include "_private" modules
+.. program:: sphinx-apidoc
 
-These options are used with ``-F``:
+.. option:: -o <OUTPUT_PATH>
 
--a              Append module_path to sys.path.
--H <project>    Project name to put into the configuration.
--A <author>     Author name(s) to put into the configuration.
--V <version>    Project version.
--R <release>    Project release.
+   Directory to place the output files. If it does not exist, it is created.
 
+.. option:: -f, --force
+
+   Force overwritting of any existing generated files.
+
+.. option:: -l, --follow-links
+
+   Follow symbolic links.
+
+.. option:: -n, --dry-run
+
+   Do not create any files.
+
+.. option:: -s <suffix>
+
+   Suffix for the source files generated. Defaults to ``rst``.
+
+.. 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
+   provided.
+
+.. option:: -F, --full
+
+   Generate a full Sphinx project (``conf.py``, ``Makefile`` etc.) using
+   the same mechanism as :program:`sphinx-quickstart`.
+
+.. option:: -e, --separate
+
+   Put documentation for each module on its own page.
+
+   .. versionadded:: 1.2
+
+.. option:: -E, --no-headings
+
+   Do not create headings for the modules/packages. This is useful, for
+   example, when docstrings already contain headings.
+
+.. option:: -P, --private
+
+   Include "_private" modules.
+
+   .. versionadded:: 1.2
+
+.. option:: --implicit-namespaces
+
+   By default sphinx-apidoc processes sys.path searching for modules only.
+   Python 3.3 introduced :pep:`420` implicit namespaces that allow module path
+   structures such as ``foo/bar/module.py`` or ``foo/bar/baz/__init__.py``
+   (notice that ``bar`` and ``foo`` are namespaces, not modules).
+
+   Interpret paths recursively according to PEP-0420.
+
+.. option:: -M, --module-first
+
+   Put module documentation before submodule documentation.
+
+These options are used when :option:`--full` is specified:
+
+.. option:: -a
+
+   Append module_path to sys.path.
+
+.. option:: -H <project>
+
+   Sets the project name to put in generated files (see :confval:`project`).
+
+.. option:: -A <author>
+
+   Sets the author name(s) to put in generated files (see
+   :confval:`copyright`).
+
+.. option:: -V <version>
+
+   Sets the project version to put in generated files (see :confval:`version`).
+
+.. option:: -R <release>
+
+   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-build(1)`, :manpage:`sphinx-autogen(1)`
 
-
-Author
-------
-
-Etienne Desautels, <etienne.desautels@gmail.com>, Georg Brandl
-<georg@python.org> et al.
+.. _fnmatch: https://docs.python.org/3/library/fnmatch.html

doc/man/sphinx-autogen.rst

@@ -0,0 +1,93 @@
+sphinx-autogen
+==============
+
+Synopsis
+--------
+
+**sphinx-autogen** [*options*] <sourcefile> ...
+
+Description
+-----------
+
+:program:`sphinx-autogen` is a tool for automatic generation of Sphinx sources
+that, using the :rst:dir:`autodoc` extension, document items included in
+:rst:dir:`autosummary` listing(s).
+
+*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:mod:`fnmatch`-style pattern.
+
+Options
+-------
+
+.. program:: sphinx-autogen
+
+.. option:: -o <outputdir>
+
+   Directory to place the output file. If it does not exist, it is created.
+   Defaults to the value passed to the ``:toctree:`` option.
+
+.. option:: -s <suffix>, --suffix <suffix>
+
+   Default suffix to use for generated files. Defaults to ``rst``.
+
+.. option:: -t <templates>, --templates <templates>
+
+   Custom template directory. Defaults to ``None``.
+
+.. option:: -i, --imported-members
+
+   Document imported members.
+
+Example
+-------
+
+Given the following directory structure::
+
+    docs
+    ├── index.rst
+    └── ...
+    foobar
+    ├── foo
+    │   └── __init__.py
+    └── bar
+        ├── __init__.py
+        └── baz
+            └── __init__.py
+
+and assuming ``docs/index.rst`` contained the following:
+
+.. code-block:: rst
+
+    Modules
+    =======
+
+    .. autosummary::
+       :toctree: modules
+
+       foobar.foo
+       foobar.bar
+       foobar.bar.baz
+
+If you run the following:
+
+.. code-block:: bash
+
+    $ PYTHONPATH=. sphinx-autodoc doc/index.rst
+
+then the following stub files will be created in ``docs``::
+
+    docs
+    ├── index.rst
+    └── modules
+        ├── foobar.bar.rst
+        ├── foobar.bar.baz.rst
+        └── foobar.foo.rst
+
+and each of those files will contain a :rst:dir:`autodoc` directive and some
+other information.
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`, :manpage:`sphinx-apidoc(1)`

doc/man/sphinx-build.rst

@@ -1,132 +1,327 @@
-:orphan:
-
-sphinx-build manual page
-========================
+sphinx-build
+============
 
 Synopsis
 --------
 
-**sphinx-build** [*options*] <*sourcedir*> <*outdir*> [*filenames* ...]
-
+**sphinx-build** [*options*] <*sourcedir*> <*outputdir*> [*filenames* ...]
 
 Description
 -----------
 
 :program:`sphinx-build` generates documentation from the files in
-``<sourcedir>`` and places it in the ``<outdir>``.
+``<sourcedir>`` and places it in the ``<outputdir>``.
 
 :program:`sphinx-build` looks for ``<sourcedir>/conf.py`` for the configuration
 settings.  :manpage:`sphinx-quickstart(1)` may be used to generate template
 files, including ``conf.py``.
 
-:program:`sphinx-build` can create documentation in different formats.  A format
-is selected by specifying the builder name on the command line; it defaults to
-HTML.  Builders can also perform other tasks related to documentation
-processing.
+:program:`sphinx-build` can create documentation in different formats.  A
+format is selected by specifying the builder name on the command line; it
+defaults to HTML.  Builders can also perform other tasks related to
+documentation processing.
 
 By default, everything that is outdated is built.  Output only for selected
 files can be built by specifying individual filenames.
 
-List of available builders:
-
-html
-   HTML file generation.  This is the default builder.
-
-dirhtml
-   HTML file generation with every HTML file named "index.html" in a separate
-   directory.
-
-singlehtml
-   HTML file generation with all content in a single HTML file.
-
-htmlhelp
-   Generates files for CHM (compiled help files) generation.
-
-qthelp
-   Generates files for Qt help collection generation.
-
-devhelp
-   Generates files for the GNOME Devhelp help viewer.
-
-latex
-   Generates LaTeX output that can be compiled to a PDF document.
-
-man
-   Generates manual pages.
-
-texinfo
-   Generates Texinfo output that can be processed by :program:`makeinfo` to
-   generate an Info document.
-
-epub
-   Generates an ePub e-book version of the HTML output.
-
-text
-   Generates a plain-text version of the documentation.
-
-gettext
-   Generates Gettext message catalogs for content translation.
-
-changes
-   Generates HTML files listing changed/added/deprecated items for
-   the current version of the documented project.
-
-linkcheck
-   Checks the integrity of all external links in the source.
-
-pickle / json
-   Generates serialized HTML files for use in web applications.
-
-xml
-   Generates Docutils-native XML files.
-
-pseudoxml
-   Generates compact pretty-printed "pseudo-XML" files displaying the
-   internal structure of the intermediate document trees.
-
+For a list of available options, refer to :option:`sphinx-build -b`.
 
 Options
 -------
 
--b <builder>          Builder to use; defaults to html. See the full list
-                      of builders above.
--a                    Generate output for all files; without this option only
-                      output for new and changed files is generated.
--E                    Ignore cached files, forces to re-read all source files
-                      from disk.
--d <path>             Path to cached files; defaults to <outdir>/.doctrees.
--j <N>                Build in parallel with N processes where possible.
--c <path>             Locate the conf.py file in the specified path instead of
-                      <sourcedir>.
--C                    Specify that no conf.py file at all is to be used.
-                      Configuration can only be set with the -D option.
--D <setting=value>    Override a setting from the configuration file.
--t <tag>              Define *tag* for use in "only" blocks.
--A <name=value>       Pass a value into the HTML templates (only for HTML
-                      builders).
--n                    Run in nit-picky mode, warn about all missing references.
--v                    Increase verbosity (can be repeated).
--N                    Prevent colored output.
--q                    Quiet operation, just print warnings and errors on stderr.
--Q                    Very quiet operation, don't print anything except for
-                      errors.
--w <file>             Write warnings and errors into the given file, in addition
-                      to stderr.
--W                    Turn warnings into errors.
--T                    Show full traceback on exception.
--P                    Run Pdb on exception.
+.. program:: sphinx-build
 
+.. option:: -b buildername
+
+   The most important option: it selects a builder.  The most common builders
+   are:
+
+   **html**
+      Build HTML pages.  This is the default builder.
+
+   **dirhtml**
+      Build HTML pages, but with a single directory per document.  Makes for
+      prettier URLs (no ``.html``) if served from a webserver.
+
+   **singlehtml**
+      Build a single HTML with the whole content.
+
+   **htmlhelp**, **qthelp**, **devhelp**, **epub**
+      Build HTML files with additional information for building a documentation
+      collection in one of these formats.
+
+   **applehelp**
+      Build an Apple Help Book.  Requires :program:`hiutil` and
+      :program:`codesign`, which are not Open Source and presently only
+      available on Mac OS X 10.6 and higher.
+
+   **latex**
+      Build LaTeX sources that can be compiled to a PDF document using
+      :program:`pdflatex`.
+
+   **man**
+      Build manual pages in groff format for UNIX systems.
+
+   **texinfo**
+      Build Texinfo files that can be processed into Info files using
+      :program:`makeinfo`.
+
+   **text**
+      Build plain text files.
+
+   **gettext**
+      Build gettext-style message catalogs (``.pot`` files).
+
+   **doctest**
+      Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest`
+      extension is enabled.
+
+   **linkcheck**
+      Check the integrity of all external links.
+
+   **xml**
+     Build Docutils-native XML files.
+
+   **pseudoxml**
+     Build compact pretty-printed "pseudo-XML" files displaying the
+     internal structure of the intermediate document trees.
+
+   See :doc:`/usage/builders/index` for a list of all builders shipped with
+   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
+
+   If given, always write all output files. The default is to only write output
+   files for new and changed source files. (This may not apply to all
+   builders.)
+
+.. option:: -E
+
+   Don't use a saved :term:`environment` (the structure caching all
+   cross-references), but rebuild it completely.  The default is to only read
+   and parse source files that are new or have changed since the last run.
+
+.. option:: -t tag
+
+   Define the tag *tag*.  This is relevant for :rst:dir:`only` directives that
+   only include their content if this tag is set.
+
+   .. versionadded:: 0.6
+
+.. option:: -d path
+
+   Since Sphinx has to read and parse all source files before it can write an
+   output file, the parsed source files are cached as "doctree pickles".
+   Normally, these files are put in a directory called :file:`.doctrees` under
+   the build directory; with this option you can select a different cache
+   directory (the doctrees can be shared between all builders).
+
+.. option:: -j N
+
+   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.  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
+   configuration directory instead.  Note that various other files and paths
+   given by configuration values are expected to be relative to the
+   configuration directory, so they will have to be present at this location
+   too.
+
+   .. versionadded:: 0.3
+
+.. option:: -C
+
+   Don't look for a configuration file; only take options via the ``-D`` option.
+
+   .. versionadded:: 0.5
+
+.. option:: -D setting=value
+
+   Override a configuration value set in the :file:`conf.py` file.  The value
+   must be a number, string, list or dictionary value.
+
+   For lists, you can separate elements with a comma like this: ``-D
+   html_theme_path=path1,path2``.
+
+   For dictionary values, supply the setting name and key like this:
+   ``-D latex_elements.docclass=scrartcl``.
+
+   For boolean values, use ``0`` or ``1`` as the value.
+
+   .. versionchanged:: 0.6
+      The value can now be a dictionary value.
+
+   .. versionchanged:: 1.3
+      The value can now also be a list value.
+
+.. option:: -A name=value
+
+   Make the *name* assigned to *value* in the HTML templates.
+
+   .. versionadded:: 0.5
+
+.. option:: -n
+
+   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".
+
+.. option:: -N
+
+   Do not emit colored output.
+
+.. option:: -v
+
+   Increase verbosity (loglevel).  This option can be given up to three times
+   to get more debug logging output.  It implies :option:`-T`.
+
+   .. versionadded:: 1.2
+
+.. option:: -q
+
+   Do not output anything on standard output, only write warnings and errors to
+   standard error.
+
+.. option:: -Q
+
+   Do not output anything on standard output, also suppress warnings.  Only
+   errors are written to standard error.
+
+.. option:: -w file
+
+   Write warnings (and errors) to the given file, in addition to standard error.
+
+.. option:: -W
+
+   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,
+   only a summary is displayed and the traceback information is saved to a file
+   for further analysis.
+
+   .. versionadded:: 1.2
+
+.. option:: -P
+
+   (Useful for debugging only.)  Run the Python debugger, :mod:`pdb`, if an
+   unhandled exception occurs while building.
+
+.. option:: -h, --help, --version
+
+   Display usage summary or Sphinx version.
+
+   .. versionadded:: 1.2
+
+You can also give one or more filenames on the command line after the source
+and build directories. Sphinx will then try to build only these output files
+(and their dependencies).
+
+Environment Variables
+---------------------
+
+The :program:`sphinx-build` refers following environment variables:
+
+.. describe:: MAKE
+
+   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
+:program:`sphinx-quickstart` usually run :program:`sphinx-build` only with the
+:option:`-b` and :option:`-d` options.  However, they support the following
+variables to customize behavior:
+
+.. describe:: PAPER
+
+   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
+
+   The command to use instead of ``sphinx-build``.
+
+.. describe:: BUILDDIR
+
+   The build directory to use instead of the one chosen in
+   :program:`sphinx-quickstart`.
+
+.. describe:: SPHINXOPTS
+
+   Additional options for :program:`sphinx-build`.
+
+.. _when-deprecation-warnings-are-displayed:
+
+Deprecation Warnings
+--------------------
+
+If any deprecation warning like ``RemovedInSphinxXXXWarning`` are displayed
+when building a user's document, some Sphinx extension is using deprecated
+features. In that case, please report it to author of the extension.
+
+To disable the deprecation warnings, please set ``PYTHONWARNINGS=`` environment
+variable to your environment. For example:
+
+* ``PYTHONWARNINGS= make html`` (Linux/Mac)
+* ``export PYTHONWARNINGS=`` and do ``make html`` (Linux/Mac)
+* ``set PYTHONWARNINGS=`` and do ``make html`` (Windows)
+* modify your Makefile/make.bat and set the environment variable
 
 See also
 --------
 
 :manpage:`sphinx-quickstart(1)`
-
-Author
-------
-
-Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
-al.
-
-This manual page was initially written by Mikhail Gusarov
-<dottedmag@dottedmag.net>, for the Debian project.

doc/man/sphinx-quickstart.rst

@@ -1,14 +1,11 @@
-:orphan:
-
-sphinx-quickstart manual page
-=============================
+sphinx-quickstart
+=================
 
 Synopsis
 --------
 
 **sphinx-quickstart**
 
-
 Description
 -----------
 
@@ -16,18 +13,157 @@ Description
 about your project and then generates a complete documentation directory and
 sample Makefile to be used with :manpage:`sphinx-build(1)`.
 
+Options
+-------
+
+.. program:: sphinx-quickstart
+
+.. option:: -q, --quiet
+
+   Quiet mode that will skip interactive wizard to specify options.
+   This option requires `-p`, `-a` and `-v` options.
+
+.. option:: -h, --help, --version
+
+   Display usage summary or Sphinx version.
+
+.. rubric:: Structure Options
+
+.. option:: --sep
+
+   If specified, separate source and build directories.
+
+.. option:: --dot=DOT
+
+   Inside the root directory, two more directories will be created;
+   "_templates" for custom HTML templates and "_static" for custom stylesheets
+   and other static files. You can enter another prefix (such as ".") to
+   replace the underscore.
+
+.. rubric:: Project Basic Options
+
+.. option:: -p PROJECT, --project=PROJECT
+
+   Project name will be set. (see :confval:`project`).
+
+.. option:: -a AUTHOR, --author=AUTHOR
+
+   Author names. (see :confval:`copyright`).
+
+.. option:: -v VERSION
+
+   Version of project. (see :confval:`version`).
+
+.. option:: -r RELEASE, --release=RELEASE
+
+   Release of project. (see :confval:`release`).
+
+.. option:: -l LANGUAGE, --language=LANGUAGE
+
+   Document language. (see :confval:`language`).
+
+.. option:: --suffix=SUFFIX
+
+   Source file suffix. (see :confval:`source_suffix`).
+
+.. option:: --master=MASTER
+
+   Master document name. (see :confval:`master_doc`).
+
+.. option:: --epub
+
+   Use epub.
+
+.. rubric:: Extension Options
+
+.. option:: --ext-autodoc
+
+   Enable `sphinx.ext.autodoc` extension.
+
+.. option:: --ext-doctest
+
+   Enable `sphinx.ext.doctest` extension.
+
+.. option:: --ext-intersphinx
+
+   Enable `sphinx.ext.intersphinx` extension.
+
+.. option:: --ext-todo
+
+   Enable `sphinx.ext.todo` extension.
+
+.. option:: --ext-coverage
+
+   Enable `sphinx.ext.coverage` extension.
+
+.. option:: --ext-imgmath
+
+   Enable `sphinx.ext.imgmath` extension.
+
+.. option:: --ext-mathjax
+
+   Enable `sphinx.ext.mathjax` extension.
+
+.. option:: --ext-ifconfig
+
+   Enable `sphinx.ext.ifconfig` extension.
+
+.. option:: --ext-viewcode
+
+   Enable `sphinx.ext.viewcode` extension.
+
+.. option:: --ext-githubpages
+
+   Enable `sphinx.ext.githubpages` extension.
+
+.. option:: --extensions=EXTENSIONS
+
+   Enable arbitrary extensions.
+
+.. rubric:: Makefile and Batchfile Creation Options
+
+.. option:: --use-make-mode (-m), --no-use-make-mode (-M)
+
+   :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.
+
+.. option:: --makefile, --no-makefile
+
+   Create (or not create) makefile.
+
+.. option:: --batchfile, --no-batchfile
+
+   Create (or not create) batchfile
+
+.. rubric:: Project templating
+
+.. versionadded:: 1.5
+   Project templating options for sphinx-quickstart
+
+.. option:: -t, --templatedir=TEMPLATEDIR
+
+   Template directory for template files.  You can modify the templates of
+   sphinx project files generated by quickstart.  Following Jinja2 template
+   files are allowed:
+
+   * ``master_doc.rst_t``
+   * ``conf.py_t``
+   * ``Makefile_t``
+   * ``Makefile.new_t``
+   * ``make.bat_t``
+   * ``make.bat.new_t``
+
+   In detail, please refer the system template files Sphinx provides.
+   (``sphinx/templates/quickstart``)
+
+.. option:: -d NAME=VALUE
+
+   Define a template variable
 
 See also
 --------
 
 :manpage:`sphinx-build(1)`
-
-
-Author
-------
-
-Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
-al.
-
-This manual page was initially written by Mikhail Gusarov
-<dottedmag@dottedmag.net>, for the Debian project.

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
-that content to show up.
+render the block's original content in the extended template -- unless you
+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
-name), containing the following:
+Themes take the form of either a directory or a zipfile (whose name is the
+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
@@ -289,21 +61,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
-called ``sphinx.html_themes`` in your setup.py file, and write a ``setup()``
+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()``
 function to register your themes using ``add_html_theme()`` API in it::
 
     # 'setup.py'
@@ -323,9 +102,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 ``add_html_theme()``
-twice or more.
+If your theme package contains two or more themes, please call
+``add_html_theme()`` twice or more.
 
 .. versionadded:: 1.2
    'sphinx_themes' entry_points feature.
@@ -336,8 +114,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 +131,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 +147,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
-:program:`msgfmt` for efficiency reasons.  If you make these files discoverable
-with :confval:`locale_dirs` for your :confval:`language`, Sphinx will pick them
-up automatically.
+*gettext* compiles them into a binary format known as **binary catalogs**
+through :program:`msgfmt` for efficiency reasons.  If you make these files
+discoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx
+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
-Spanish translations [2]_ on your hands in ``usage.po`` --- for your builds to
+*gettext* builder will put its messages into ``usage.pot``.  Imagine you have
+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.
-This section describe an easy way to translate with sphinx-intl.
+`sphinx-intl`_ is a useful tool to work with Sphinx translation flow.  This
+section describe an easy way to translate with *sphinx-intl*.
 
-#. Install `sphinx-intl`_ by :command:`pip install sphinx-intl` or
-   :command:`easy_install sphinx-intl`.
+#. 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
-   :confval:`gettext_compact` is set to `False` (the Sphinx document is
+   This case-study assumes that :confval:`locale_dirs` is set to ``locale/`` and
+   :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``
-   directory.
+   The generated pot files will be placed in the ``_build/gettext`` 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/ja/LC_MESSAGES/`
+   * ``./locale/de/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.
-
-   If you are using 1.2.x or earlier, please invoke ``sphinx-intl build`` command
-   before make command.
+   :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 :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
-and to apply differences to translated po files.
-In order to apply the updating difference of a pot file to po file,
-use the :command:`sphinx-intl update` command.
+If a document is updated, it is necessary to generate updated pot files and to
+apply differences to translated po files.  In order to apply the updates from a
+pot file to the po file, 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 tx command
+#. Create config files for :command:`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 (ex. for 'de'):
+   Get translated catalogs and build mo files. For example, to build mo files
+   for German (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.
-   Watch out! This operation overwrites translations in transifex.
+   :command:`tx push -t` command.  Watch out! This operation overwrites
+   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
-is to join the translation team on Transifex.
+The recommended way for new contributors to translate Sphinx reference is to
+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.python.org/pypi/transifex-client
-.. _`sphinx-intl`: https://pypi.python.org/pypi/sphinx-intl
+.. _`transifex-client`: https://pypi.org/project/transifex-client/
+.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
 .. _Transifex: https://www.transifex.com/
-.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc-1_3/
-.. _`Transifex Client v0.8 &mdash; Transifex documentation`: http://docs.transifex.com/developer/client/
+.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc/
+.. _`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
-       should be a string with the name of that location
-       (e.g. ``'/static_files'``).
+       If the static files should be created in a different location
+       **and not in** ``'/static'``, this should be a string with the name of
+       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
-   web/api
-   web/searchadapters
-   web/storagebackends
+   quickstart
+   api
+   searchadapters
+   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
-data in `builddir`.  The `builddir` will contain two sub-directories: one named
-"data" that contains all the data needed to display documents, search through
-documents, and add comments to documents.  The other directory will be called
-"static" and contains static files that should be served from "/static".
+This will read reStructuredText sources from ``srcdir`` and place the necessary
+data in ``builddir``.  The ``builddir`` will contain two sub-directories: one
+named "data" that contains all the data needed to display documents, search
+through documents, and add comments to documents.  The other directory will be
+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
-search results. In `Flask <http://flask.pocoo.org/>`_ that would be like this::
+the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to
+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
-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`
+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``
+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
-   not need to be overridden, but some (:meth:`~BaseSearch.add_document` and
-   :meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
-   working example, look at the built-in adapter for whoosh.
+The following methods are defined in the BaseSearch class. Some methods do not
+need to be overridden, but some (:meth:`~BaseSearch.add_document` and
+:meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
+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
-   the Qt collection generator to compile them.
+   also generates `Qt help`_ collection support files that allow the Qt
+   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
-      present in a "minimal" TeX distribution installation. For example, on
-      Ubuntu, the following packages need to be installed for successful PDF
-      builds:
+      Since 1.6, ``make latexpdf`` uses ``latexmk`` (not on Windows).  This
+      makes sure the needed number of runs is automatically executed to get
+      the cross-references, bookmarks, indices, and tables of contents right.
 
-      * 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
-      4.52b or higher (Jan 17) and ``xelatex`` is the :confval:`latex_engine`,
-      then ``LATEXMKOPTS="-xelatex"`` will speed up PDF builds.
+      reduces console output to a minimum.
 
-      To pass options directly to the
-      ``(pdf|xe|lua)latex`` executable, use variable ``LATEXOPTS`` (for example
-      ``LATEXOPTS="--interaction=nonstopmode"``).
+      Also, if ``latexmk`` is at version 4.52b or higher (January 2017)
+      ``LATEXMKOPTS="-xelatex"`` speeds up PDF builds via XeLateX in case
+      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
-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.
+name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
 
 .. _rinohtype: https://github.com/brechtm/rinohtype
-.. _rinohtype manual: http://www.mos6581.org/rinohtype/quickstart.html#sphinx-builder
-.. _rst2pdf: https://github.com/rst2pdf/rst2pdf
-.. _rst2pdf manual: http://ralsina.me/static/manual.pdf
+.. _rinohtype manual: https://www.mos6581.org/rinohtype/quickstart.html#sphinx-builder
 
 .. 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
-   to standard output and to :file:`output.txt` in the output directory.
+   ``requests``, and writes an overview which ones are broken and redirected to
+   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
-     order of the members will also be the order in ``__all__``.
+     For modules, ``__all__`` will be respected when looking for members unless
+     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
-     below) the default, see :confval:`autodoc_default_flags`.
+   * If you want to make the ``members`` option (or other options described
+     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'``.
-
-   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.
+   ``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``
+   and ``'exclude-members'``.
 
    .. 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 forcely 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
@@ -125,6 +123,9 @@ text of the form::
 If the ``-o`` option is not given, the script will place the output files in the
 directories specified in the ``:toctree:`` options.
 
+For more information, refer to the :doc:`sphinx-autogen documentation
+</man/sphinx-autogen>`
+
 
 Generating stub pages automatically
 -----------------------------------
@@ -202,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"
@@ -234,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:
 

doc/usage/extensions/doctest.rst

@@ -80,12 +80,24 @@ a comma-separated list of group names.
          .. doctest::
             :pyversion: > 3.3
 
-     The supported operands are ``<``, ``<=``, ``==``, ``>=``, ``>``, and
-     comparison is performed by `distutils.version.LooseVersion
-     <https://www.python.org/dev/peps/pep-0386/#distutils>`__.
+     The following operands are supported:
+
+     * ``~=``: Compatible release clause
+     * ``==``: Version matching clause
+     * ``!=``: Version exclusion clause
+     * ``<=``, ``>=``: Inclusive ordered comparison clause
+     * ``<``, ``>``: Exclusive ordered comparison clause
+     * ``===``: Arbitrary equality clause.
+
+     ``pyversion`` option is followed `PEP-440: Version Specifiers
+     <https://www.python.org/dev/peps/pep-0440/#version-specifiers>`__.
 
      .. versionadded:: 1.6
 
+     .. versionchanged:: 1.7
+
+        Supported PEP-440 operands and notations
+
    Note that like with standard doctests, you have to use ``<BLANKLINE>`` to
    signal a blank line in the expected output.  The ``<BLANKLINE>`` is removed
    when building presentation output (HTML, LaTeX etc.).
@@ -153,7 +165,6 @@ a comma-separated list of group names.
 
          Output text.
 
-
 The following is an example for the usage of the directives.  The test via
 :rst:dir:`doctest` and the test via :rst:dir:`testcode` and
 :rst:dir:`testoutput` are equivalent. ::
@@ -187,6 +198,81 @@ The following is an example for the usage of the directives.  The test via
       This parrot wouldn't voom if you put 3000 volts through it!
 
 
+Skipping tests conditionally
+----------------------------
+
+``skipif``, a string option, can be used to skip directives conditionally. This
+may be useful e.g. when a different set of tests should be run depending on the
+environment (hardware, network/VPN, optional dependencies or different versions
+of dependencies). The ``skipif`` option is supported by all of the doctest
+directives. Below are typical use cases for ``skipif`` when used for different
+directives:
+
+- :rst:dir:`testsetup` and :rst:dir:`testcleanup`
+
+  - conditionally skip test setup and/or cleanup
+  - customize setup/cleanup code per environment
+
+- :rst:dir:`doctest`
+
+  - conditionally skip both a test and its output verification
+
+- :rst:dir:`testcode`
+
+  - conditionally skip a test
+  - customize test code per environment
+
+- :rst:dir:`testoutput`
+
+  - conditionally skip output assertion for a skipped test
+  - expect different output depending on the environment
+
+The value of the ``skipif`` option is evaluated as a Python expression. If the
+result is a true value, the directive is omitted from the test run just as if
+it wasn't present in the file at all.
+
+Instead of repeating an expression, the :confval:`doctest_global_setup`
+configuration option can be used to assign it to a variable which can then be
+used instead.
+
+Here's an example which skips some tests if Pandas is not installed:
+
+.. code-block:: py
+   :caption: conf.py
+
+   extensions = ['sphinx.ext.doctest']
+   doctest_global_setup = '''
+   try:
+       import pandas as pd
+   except ImportError:
+       pd = None
+   '''
+
+.. code-block:: rst
+   :caption: contents.rst
+
+   .. testsetup::
+      :skipif: pd is None
+
+      data = pd.Series([42])
+
+   .. doctest::
+      :skipif: pd is None
+
+      >>> data.iloc[0]
+      42
+
+   .. testcode::
+      :skipif: pd is None
+
+      print(data.iloc[-1])
+
+   .. testoutput::
+      :skipif: pd is None
+
+      42
+
+
 Configuration
 -------------
 

doc/usage/extensions/example_google.py

@@ -29,7 +29,7 @@ Todo:
     * You have to also use ``sphinx.ext.todo`` extension
 
 .. _Google Python Style Guide:
-   http://google.github.io/styleguide/pyguide.html
+   https://google.github.io/styleguide/pyguide.html
 
 """
 
@@ -178,7 +178,7 @@ class ExampleError(Exception):
         self.code = code
 
 
-class ExampleClass(object):
+class ExampleClass:
     """The summary line for a class docstring should fit on one line.
 
     If the class has public attributes, they may be documented here

doc/usage/extensions/example_numpy.py

@@ -223,7 +223,7 @@ class ExampleError(Exception):
         self.code = code
 
 
-class ExampleClass(object):
+class ExampleClass:
     """The summary line for a class docstring should fit on one line.
 
     If the class has public attributes, they may be documented here