IntenseWebs/sphinx
3
0 Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2026-10-25 06:38:09 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into docs/extension-tutorials

Browse Source
This commit is contained in:
Arthur authored and GitHub committed 2018-11-30 10:33:20 +01:00
2 parents 8479876798 3528a68d2a
commit adc1d2b59d
914 files changed
+164720 -43568
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.appveyor.yml
+21 -13
View File
@@ -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
+3 -1
View File
@@ -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
+8
View File
@@ -0,0 +1,8 @@
coverage:
status:
project:
default:
enabled: no
patch:
default:
enabled: no
.github/ISSUE_TEMPLATE.md
+8
View File
@@ -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
+10 -1
View File
@@ -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
+43 -38
View File
@@ -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 -2
View File
@@ -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!
CHANGES
+1021 -19
View File
File diff suppressed because it is too large. Load diff
CONTRIBUTING.rst
+91 -42
View File
@@ -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
+366 -203
View File
@@ -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 -89
View File
@@ -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
+1 -3
View File
@@ -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
+32 -50
View File
@@ -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
+88 -52
View File
@@ -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
+2 -1
View File
@@ -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/more.png → doc/_static/more.png
Vendored
View File
File renamed without changes.
doc/themes/agogo.png → doc/_static/themes/agogo.png
Vendored
View File
File renamed without changes.
doc/themes/alabaster.png → doc/_static/themes/alabaster.png
Vendored
View File
File renamed without changes.
doc/themes/bizstyle.png → doc/_static/themes/bizstyle.png
Vendored
View File
File renamed without changes.
doc/themes/classic.png → doc/_static/themes/classic.png
Vendored
View File
File renamed without changes.
doc/themes/fullsize/agogo.png → doc/_static/themes/fullsize/agogo.png
Vendored
View File
File renamed without changes.
doc/themes/fullsize/alabaster.png → doc/_static/themes/fullsize/alabaster.png
Vendored
View File
File renamed without changes.
doc/themes/fullsize/bizstyle.png → doc/_static/themes/fullsize/bizstyle.png
Vendored
View File
File renamed without changes.
doc/themes/fullsize/classic.png → doc/_static/themes/fullsize/classic.png
Vendored
View File
File renamed without changes.
doc/themes/fullsize/haiku.png → doc/_static/themes/fullsize/haiku.png
Vendored
View File
File renamed without changes.
doc/themes/fullsize/nature.png → doc/_static/themes/fullsize/nature.png
Vendored
View File
File renamed without changes.
doc/themes/fullsize/pyramid.png → doc/_static/themes/fullsize/pyramid.png
Vendored
View File
File renamed without changes.
doc/themes/fullsize/scrolls.png → doc/_static/themes/fullsize/scrolls.png
Vendored
View File
File renamed without changes.
doc/themes/fullsize/sphinx_rtd_theme.png → doc/_static/themes/fullsize/sphinx_rtd_theme.png
Vendored
View File
File renamed without changes.
doc/themes/fullsize/sphinxdoc.png → doc/_static/themes/fullsize/sphinxdoc.png
Vendored
View File
File renamed without changes.
doc/themes/fullsize/traditional.png → doc/_static/themes/fullsize/traditional.png
Vendored
View File
File renamed without changes.
doc/themes/haiku.png → doc/_static/themes/haiku.png
Vendored
View File
File renamed without changes.
doc/themes/nature.png → doc/_static/themes/nature.png
Vendored
View File
File renamed without changes.
doc/themes/pyramid.png → doc/_static/themes/pyramid.png
Vendored
View File
File renamed without changes.
doc/themes/scrolls.png → doc/_static/themes/scrolls.png
Vendored
View File
File renamed without changes.
doc/themes/sphinx_rtd_theme.png → doc/_static/themes/sphinx_rtd_theme.png
Vendored
View File
File renamed without changes.
doc/themes/sphinxdoc.png → doc/_static/themes/sphinxdoc.png
Vendored
View File
File renamed without changes.
doc/themes/traditional.png → doc/_static/themes/traditional.png
Vendored
View File
File renamed without changes.
doc/translation.png → doc/_static/translation.png
Vendored
View File
File renamed without changes.
doc/_templates/index.html
Vendored
+5 -8
View File
@@ -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
Vendored
+11 -19
View File
@@ -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
Vendored
+8 -3
View File
@@ -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
Vendored
+37 -3
View File
@@ -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
+29 -4
View File
@@ -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
+14 -12
View File
@@ -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
+17 -17
View File
@@ -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
-25
View File
@@ -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
-35
View File
@@ -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
-64
View File
@@ -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
+76 -422
View File
@@ -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
+4
View File
@@ -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
+4 -8
View File
@@ -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
+17
View File
@@ -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
+602
View File
@@ -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
+21 -32
View File
@@ -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
+20 -10
View File
@@ -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
+29
View File
@@ -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
+9
View File
@@ -0,0 +1,9 @@
.. _project-api:
Project API
===========
.. currentmodule:: sphinx.project
.. autoclass:: Project
:members:
doc/extdev/utils.rst
+22
View File
@@ -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
-16
View File
@@ -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
+9 -12
View File
@@ -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
+17 -5
View File
@@ -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
-155
View File
@@ -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/installpython.jpg
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 25 KiB

doc/intro.rst
+13 -16
View File
@@ -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
-566
View File
@@ -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
+76 -57
View File
@@ -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
+1 -1
View File
@@ -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
+22
View File
@@ -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
+110 -38
View File
@@ -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
+93
View File
@@ -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
+299 -104
View File
@@ -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
+151 -15
View File
@@ -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
-45
View File
@@ -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
-268
View File
@@ -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
-19
View File
@@ -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
-339
View File
@@ -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
-253
View File
@@ -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
-242
View File
@@ -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/pythonorg.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 146 KiB

doc/templating.rst
+10 -3
View File
@@ -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
+26 -274
View File
@@ -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/intl.rst → doc/usage/advanced/intl.rst
+108 -94
View File
@@ -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/setuptools.rst → doc/usage/advanced/setuptools.rst
+24 -6
View File
@@ -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/web/api.rst → doc/usage/advanced/websupport/api.rst
+12 -4
View File
@@ -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/websupport.rst → doc/usage/advanced/websupport/index.rst
+4 -4
View File
@@ -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/web/quickstart.rst → doc/usage/advanced/websupport/quickstart.rst
+19 -18
View File
@@ -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/web/searchadapters.rst → doc/usage/advanced/websupport/searchadapters.rst
+6 -6
View File
@@ -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/web/storagebackends.rst → doc/usage/advanced/websupport/storagebackends.rst
+2 -2
View File
@@ -27,8 +27,8 @@ documentation of the :class:`StorageBackend` class below.
sphinx.websupport.storage.
StorageBackend Methods
~~~~~~~~~~~~~~~~~~~~~~
Methods
-------
.. automethod:: StorageBackend.pre_build
doc/builders.rst → doc/usage/builders/index.rst
+67 -51
View File
@@ -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/config.rst → doc/usage/configuration.rst
+782 -228
View File
File diff suppressed because it is too large. Load diff
doc/ext/autodoc.rst → doc/usage/extensions/autodoc.rst
+82 -17
View File
@@ -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/ext/autosectionlabel.rst → doc/usage/extensions/autosectionlabel.rst
+1
View File
@@ -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/ext/autosummary.rst → doc/usage/extensions/autosummary.rst
+11 -3
View File
@@ -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/ext/coverage.rst → doc/usage/extensions/coverage.rst
-2
View File
@@ -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/ext/doctest.rst → doc/usage/extensions/doctest.rst
+90 -4
View File
@@ -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/ext/example_google.py → doc/usage/extensions/example_google.py
+2 -2
View File
@@ -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/ext/example_google.rst → doc/usage/extensions/example_google.rst
View File
File renamed without changes.
doc/ext/example_numpy.py → doc/usage/extensions/example_numpy.py
+1 -1
View File
@@ -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
doc/ext/example_numpy.rst → doc/usage/extensions/example_numpy.rst
View File
File renamed without changes.
Loaded 100 of 914 files, more files were not shown because too many files have changed in this diff. Show more