IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into HEAD

Browse Source
This commit is contained in:
Takeshi KOMIYA 2016-08-22 19:03:27 +09:00
commit c4c4ce53c8
724 changed files with 78672 additions and 16670 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -1,6 +1,7 @@
*.pyc
*.egg
*.so
*.swp
.dir-locals.el
.ropeproject/

24
.travis.yml
View File

@ -1,16 +1,36 @@
language: python
sudo: false
cache:
directories:
- $HOME/.cache/pip
python:
- "2.6"
- "2.7"
- "3.3"
- "3.4"
- "3.5"
- "3.5-dev"
- "pypy"
env:
global:
- TEST='-v --with-timer --timer-top-n 25'
matrix:
- DOCUTILS=0.11
- DOCUTILS=0.12
addons:
apt:
packages:
- graphviz
- texlive-latex-recommended
- texlive-latex-extra
- texlive-fonts-recommended
- texlive-fonts-extra
install:
- pip install -U pip setuptools
- pip install docutils==$DOCUTILS
- pip install -r test-reqs.txt
before_script: flake8
script: make test
before_script:
- if [[ $TRAVIS_PYTHON_VERSION != '2.6' ]]; then flake8; fi
script:
- if [[ $TRAVIS_PYTHON_VERSION == '3.5' ]]; then make style-check test-async; fi
- if [[ $TRAVIS_PYTHON_VERSION != '3.5' ]]; then make test; fi

7
AUTHORS
View File

@ -24,10 +24,12 @@ Other contributors, listed alphabetically, are:
* Charles Duffy -- original graphviz extension
* Kevin Dunn -- MathJax extension
* Josip Dzolonga -- coverage builder
* Buck Evan -- dummy builder
* Hernan Grecco -- search improvements
* Horst Gutmann -- internationalization support
* Martin Hans -- autodoc improvements
* Doug Hellmann -- graphviz improvements
* Timotheus Kampik - JS theme & search enhancements
* Takeshi Komiya -- numref feature
* Dave Kuhlman -- original LaTeX writer
* Blaise Laflamme -- pyramid theme
@ -39,6 +41,7 @@ Other contributors, listed alphabetically, are:
* Martin Mahner -- nature theme
* Will Maier -- directory HTML builder
* Jacob Mason -- websupport library (GSOC project)
* Glenn Matthews -- python domain signature improvements
* Roland Meister -- epub builder
* Ezio Melotti -- collapsible sidebar JavaScript
* Daniel Neuhäuser -- JavaScript domain, Python 3 support (GSOC)
@ -50,14 +53,18 @@ Other contributors, listed alphabetically, are:
* Stefan Seefeld -- toctree improvements
* Gregory Szorc -- performance improvements
* Shibukawa Yoshiki -- pluggable search API and Japanese search
* Taku Shimizu -- epub3 builder
* Antonio Valentino -- qthelp builder
* Filip Vavera -- napoleon todo directive
* Pauli Virtanen -- autodoc improvements, autosummary extension
* 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
* Joel Wurtz -- cellspanning support in LaTeX
* Hong Xu -- svg support in imgmath extension and various bug fixes
Many thanks for all contributions!

720
CHANGES
View File

@ -1,12 +1,102 @@
Release 1.4 (in development)
Release 1.5 (in development)
============================
Incompatible changes
--------------------
* latex, package fancybox is not longer a dependency of sphinx.sty
* Use ``'locales'`` as a default value of `locale_dirs`
* latex, package ifthen is not any longer a dependency of sphinx.sty
* latex, style file does not modify fancyvrb's Verbatim (also available as
OriginalVerbatim) but uses sphinxVerbatim for name of custom wrapper.
* latex, package newfloat is no longer a dependency of sphinx.sty (ref #2660;
it was shipped with Sphinx since 1.3.4).
* latex, literal blocks in tables do not use OriginalVerbatim but
sphinxVerbatimintable which handles captions and wraps lines(ref #2704).
* latex, replace ``pt`` by TeX equivalent ``bp`` if found in ``width`` or
``height`` attribute of an image.
* latex, if ``width`` or ``height`` attribute of an image is given with no unit,
use ``px`` rather than ignore it.
* latex: Separate stylesheets of pygments to independent .sty file
* #2454: The filename of sourcelink is now changed. The value of
`html_sourcelink_suffix` will be appended to the original filename (like
``index.rst.txt``).
* ``sphinx.util.copy_static_entry()`` is now deprecated.
Use ``sphinx.util.fileutil.copy_asset()`` instead.
* ``sphinx.util.osutil.filecopy()`` skips copying if the file has not been changed
(ref: #2510, #2753)
* Internet Explorer 6-8, Opera 12.1x or Safari 5.1+ support is dropped
because jQuery version is updated from 1.11.0 to 3.1.0 (ref: #2634, #2773)
* QtHelpBuilder doens't generate search page (ref: #2352)
* QtHelpBuilder uses ``nonav`` theme instead of default one
to improve readability.
* latex: To provide good default settings to Japanese docs, Sphinx uses ``jsbooks``
as a docclass by default if the ``language`` is ``ja``.
* latex: To provide good default settings to Japanese docs, Sphinx uses
``jreport`` and ``jsbooks`` as a docclass by default if the ``language`` is
``ja``.
* ``sphinx-quickstart`` now allows a project version is empty
* Fix :download: role on epub/qthelp builder. They ignore the role because they don't support it.
* ``sphinx.ext.viewcode`` doesn't work on epub building by default. ``viewcode_enable_epub`` option
* ``sphinx.ext.viewcode`` disabled on singlehtml builder.
* Use make-mode of ``sphinx-quickstart`` by default. To disable this, use
``-M`` option
* Fix ``genindex.html`` to satisfy xhtml standard.
Features added
--------------
* Add ``:caption:`` option for sphinx.ext.inheritance_diagram.
* #2471: Add config variable for default doctest flags.
* Convert linkcheck builder to requests for better encoding handling
* #2463, #2516: Add keywords of "meta" directive to search index
* ``:maxdepth:`` option of toctree affects ``secnumdepth`` (ref: #2547)
* #2575: Now ``sphinx.ext.graphviz`` allows ``:align:`` option
* Show warnings if unknown key is specified to `latex_elements`
* Show warnings if no domains match with `primary_domain` (ref: #2001)
* C++, show warnings when the kind of role is misleading for the kind
of target it refers to (e.g., using the `class` role for a function).
* latex, writer abstracts more of text styling into customizable macros, e.g.
the ``visit_emphasis`` will output ``\sphinxstyleemphasis`` rather than
``\emph`` (which may be in use elsewhere or in an added LaTeX package). See
list at end of ``sphinx.sty`` (ref: #2686)
* latex, public names for environments and parameters used by note, warning,
and other admonition types, allowing full customizability from the
``'preamble'`` key or an input file (ref: feature request #2674, #2685)
* latex, better computes column widths of some tables (as a result, there will
be slight changes as tables now correctly fill the line width; ref: #2708)
* latex, sphinxVerbatim environment is more easily customizable (ref: #2704).
In addition to already existing VerbatimColor and VerbatimBorderColor:
- two lengths ``\sphinxverbatimsep`` and ``\sphinxverbatimborder``,
- booleans ``\ifsphinxverbatimwithframe`` and ``\ifsphinxverbatimwrapslines``.
* latex, captions for literal blocks inside tables are handled, and long code
lines wrapped to fit table cell (ref: #2704)
* #2597: Show warning messages as darkred
* latex, allow image dimensions using px unit (default is 96px=1in)
* Show warnings if invalid dimension units found
* #2650: Add ``--pdb`` option to setup.py command
* latex, make the use of ``\small`` for code listings customizable (ref #2721)
* #2663: Add ``--warning-is-error`` option to setup.py command
* Show warnings if deprecated latex options are used
* Add sphinx.config.ENUM to check the config values is in candidates
* math: Add hyperlink marker to each equations in HTML output
* Add new theme ``nonav`` that doesn't include any navigation links.
This is for any help generator like qthelp.
* #2680: `sphinx.ext.todo` now emits warnings if `todo_emit_warnings` enabled.
Also, it emits an additional event named `todo-defined` to handle the TODO
entries in 3rd party extensions.
* Python domain signature parser now uses the xref mixin for 'exceptions',
allowing exception classes to be autolinked.
* #2513: Add `latex_engine` to switch the LaTeX engine by conf.py
* #2682: C++, basic support for attributes (C++11 style and GNU style).
The new configuration variables 'cpp_id_attributes' and 'cpp_paren_attributes'
can be used to introduce custom attributes.
* #1958: C++, add configuration variable 'cpp_index_common_prefix' for removing
prefixes from the index text of C++ objects.
* C++, added concept directive. Thanks to mickk-on-cpp.
* C++, added support for template introduction syntax. Thanks to mickk-on-cpp.
* apidoc now avoids invalidating cached files by not writing to files whose
content doesn't change. This can lead to significant performance wins if
apidoc is run frequently.
@ -14,15 +104,616 @@ Features added
Bugs fixed
----------
* #1789: ``:pyobject:`` option of ``literalinclude`` directive includes following
lines after class definitions
* #1790: ``literalinclude`` strips empty lines at the head and tail
* #1913: C++, fix assert bug for enumerators in next-to-global and global scope.
* #2707: (latex) the column width is badly computed for tabular
* #2799: Sphinx installs roles and directives automatically on importing sphinx
module. Now Sphinx installs them on running application.
* `sphinx.ext.autodoc` crashes if target code imports * from mock modules
by `autodoc_mock_imports`.
* #1953: ``Sphinx.add_node`` does not add handlers the translator installed by
`html_translator_class`
* #1797: text builder inserts blank line on top
Documentation
-------------
Release 1.4.6 (in development)
==============================
Bugs fixed
----------
Release 1.4.6 (released Aug 20, 2016)
=====================================
Incompatible changes
--------------------
* #2867: linkcheck builder crashes with six-1.4. Now Sphinx depends on six-1.5 or
later
Bugs fixed
----------
* applehelp: Sphinx crashes if ``hiutil`` or ``codesign`` commands not found
* Fix ``make clean`` abort issue when build dir contains regular files like ``DS_Store``.
* Reduce epubcheck warnings/errors:
* Fix DOCTYPE to html5
* Change extension from .html to .xhtml.
* Disable search page on epub results
* #2778: Fix autodoc crashes if obj.__dict__ is a property method and raises exception
* Fix duplicated toc in epub3 output.
* #2775: Fix failing linkcheck with servers not supporting identidy encoding
* #2833: Fix formatting instance annotations in ext.autodoc.
* #1911: ``-D`` option of ``sphinx-build`` does not override the ``extensions`` variable
* #2789: `sphinx.ext.intersphinx` generates wrong hyperlinks if the inventory is given
* parsing errors for caption of code-blocks are displayed in document (ref: #2845)
* #2846: ``singlehtml`` builder does not include figure numbers
* #2816: Fix data from builds cluttering the ``Domain.initial_data`` class attributes
Release 1.4.5 (released Jul 13, 2016)
=====================================
Incompatible changes
--------------------
* latex, inclusion of non-inline images from image directive resulted in
non-coherent whitespaces depending on original image width; new behaviour
by necessity differs from earlier one in some cases. (ref: #2672)
* latex, use of ``\includegraphics`` to refer to Sphinx custom variant is
deprecated; in future it will revert to original LaTeX macro, custom one
already has alternative name ``\sphinxincludegraphics``.
Features added
--------------
* new config option ``latex_keep_old_macro_names``, defaults to True. If False,
lets macros (for text styling) be defined only with ``\sphinx``-prefixed names.
* latex writer allows user customization of "shadowed" boxes (topics), via
three length variables.
* woff-format web font files now supported by the epub builder.
Bugs fixed
----------
* jsdump fix for python 3: fixes the HTML search on python > 3
* #2676: (latex) Error with verbatim text in captions since Sphinx 1.4.4
* #2629: memoir class crashes LaTeX. Fixed ``by latex_keep_old_macro_names=False`` (ref 2675)
* #2684: `sphinx.ext.intersphinx` crashes with six-1.4.1
* #2679: ``float`` package needed for ``'figure_align': 'H'`` latex option
* #2671: image directive may lead to inconsistent spacing in pdf
* #2705: ``toctree`` generates empty bullet_list if ``:titlesonly:`` specified
* #2479: `sphinx.ext.viewcode` uses python2 highlighter by default
* #2700: HtmlHelp builder has hard coded index.html
* latex, since 1.4.4 inline literal text is followed by spurious space
* #2722: C++, fix id generation for var/member declarations to include namespaces.
* latex, images (from image directive) in lists or quoted blocks did not obey
indentation (fixed together with #2671)
* #2733: since Sphinx-1.4.4 ``make latexpdf`` generates lots of hyperref warnings
* #2731: `sphinx.ext.autodoc` does not access propertymethods which raises any
exceptions
* #2666: C++, properly look up nested names involving constructors.
* #2579: Could not refer a label including both spaces and colons via
`sphinx.ext.intersphinx`
* #2718: Sphinx crashes if the document file is not readable
* #2699: hyperlinks in help HTMLs are broken if `html_file_suffix` is set
* #2723: extra spaces in latex pdf output from multirow cell
* #2735: latexpdf ``Underfull \hbox (badness 10000)`` warnings from title page
* #2667: latex crashes if resized images appeared in section title
* #2763: (html) Provide default value for required ``alt`` attribute for image
tags of SVG source, required to validate and now consistent w/ other formats.
Release 1.4.4 (released Jun 12, 2016)
=====================================
Bugs fixed
----------
* #2630: Latex sphinx.sty Notice Enviroment formatting problem
* #2632: Warning directives fail in quote environment latex build
* #2633: Sphinx crashes with old styled indices
* Fix a ``\begin{\minipage}`` typo in sphinx.sty from 1.4.2 (ref: 68becb1)
* #2622: Latex produces empty pages after title and table of contents
* #2640: 1.4.2 LaTeX crashes if code-block inside warning directive
* Let LaTeX use straight quotes also in inline code (ref #2627)
* #2351: latex crashes if enumerated lists are placed on footnotes
* #2646: latex crashes if math contains twice empty lines
* #2480: `sphinx.ext.autodoc`: memory addresses were shown
* latex: allow code-blocks appearing inside lists and quotes at maximal nesting
depth (ref #777, #2624, #2651)
* #2635: Latex code directives produce inconsistent frames based on viewing
resolution
* #2639: Sphinx now bundles iftex.sty
* Failed to build PDF with framed.sty 0.95
* Sphinx now bundles needspace.sty
Release 1.4.3 (released Jun 5, 2016)
====================================
Bugs fixed
----------
* #2530: got "Counter too large" error on building PDF if large numbered
footnotes existed in admonitions
* ``width`` option of figure directive does not work if ``align`` option specified at same time (ref: #2595)
* #2590: The ``inputenc`` package breaks compiling under lualatex and xelatex
* #2540: date on latex front page use different font
* Suppress "document isn't included in any toctree" warning if the document is included (ref: #2603)
* #2614: Some tables in PDF output will end up shifted if user sets non zero
\parindent in preamble
* #2602: URL redirection breaks the hyperlinks generated by `sphinx.ext.intersphinx`
* #2613: Show warnings if merged extensions are loaded
* #2619: make sure amstext LaTeX package always loaded (ref: d657225, 488ee52,
9d82cad and #2615)
* #2593: latex crashes if any figures in the table
Release 1.4.2 (released May 29, 2016)
=====================================
Features added
--------------
* Now :confval:`suppress_warnings` accepts following configurations (ref: #2451, #2466):
- ``app.add_node``
- ``app.add_directive``
- ``app.add_role``
- ``app.add_generic_role``
- ``app.add_source_parser``
- ``image.data_uri``
- ``image.nonlocal_uri``
* #2453: LaTeX writer allows page breaks in topic contents; and their
horizontal extent now fits in the line width (with shadow in margin). Also
warning-type admonitions allow page breaks and their vertical spacing has
been made more coherent with the one for hint-type notices (ref #2446).
* #2459: the framing of literal code-blocks in LaTeX output (and not only the
code lines themselves) obey the indentation in lists or quoted blocks.
* #2343: the long source lines in code-blocks are wrapped (without modifying
the line numbering) in LaTeX output (ref #1534, #2304).
Bugs fixed
----------
* #2370: the equations are slightly misaligned in LaTeX writer
* #1817, #2077: suppress pep8 warnings on conf.py generated by sphinx-quickstart
* #2407: building docs crash if document includes large data image URIs
* #2436: Sphinx does not check version by :confval:`needs_sphinx` if loading extensions failed
* #2397: Setup shorthandoff for turkish documents
* #2447: VerbatimBorderColor wrongly used also for captions of PDF
* #2456: C++, fix crash related to document merging (e.g., singlehtml and Latex builders).
* #2446: latex(pdf) sets local tables of contents (or more generally topic
nodes) in unbreakable boxes, causes overflow at bottom
* #2476: Omit MathJax markers if :nowrap: is given
* #2465: latex builder fails in case no caption option is provided to toctree directive
* Sphinx crashes if self referenced toctree found
* #2481: spelling mistake for mecab search splitter. Thanks to Naoki Sato.
* #2309: Fix could not refer "indirect hyperlink targets" by ref-role
* intersphinx fails if mapping URL contains any port
* #2088: intersphinx crashes if the mapping URL requires basic auth
* #2304: auto line breaks in latexpdf codeblocks
* #1534: Word wrap long lines in Latex verbatim blocks
* #2460: too much white space on top of captioned literal blocks in PDF output
* Show error reason when multiple math extensions are loaded (ref: #2499)
* #2483: any figure number was not assigned if figure title contains only non text objects
* #2501: Unicode subscript numbers are normalized in LaTeX
* #2492: Figure directive with :figwidth: generates incorrect Latex-code
* The caption of figure is always put on center even if ``:align:`` was specified
* #2526: LaTeX writer crashes if the section having only images
* #2522: Sphinx touches mo files under installed directory that caused permission error.
* #2536: C++, fix crash when an immediately nested scope has the same name as the current scope.
* #2555: Fix crash on any-references with unicode.
* #2517: wrong bookmark encoding in PDF if using LuaLaTeX
* #2521: generated Makefile causes BSD make crashed if sphinx-build not found
* #2470: ``typing`` backport package causes autodoc errors with python 2.7
* ``sphinx.ext.intersphinx`` crashes if non-string value is used for key of `intersphinx_mapping`
* #2518: `intersphinx_mapping` disallows non alphanumeric keys
* #2558: unpack error on devhelp builder
* #2561: Info builder crashes when a footnote contains a link
* #2565: The descriptions of objects generated by ``sphinx.ext.autosummary`` overflow lines at LaTeX writer
* Extend pdflatex config in sphinx.sty to subparagraphs (ref: #2551)
* #2445: `rst_prolog` and `rst_epilog` affect to non reST sources
* #2576: ``sphinx.ext.imgmath`` crashes if subprocess raises error
* #2577: ``sphinx.ext.imgmath``: Invalid argument are passed to dvisvgm
* #2556: Xapian search does not work with Python 3
* #2581: The search doesn't work if language="es" (spanish)
* #2382: Adjust spacing after abbreviations on figure numbers in LaTeX writer
* #2383: The generated footnote by `latex_show_urls` overflows lines
* #2497, #2552: The label of search button does not fit for the button itself
Release 1.4.1 (released Apr 12, 2016)
=====================================
Incompatible changes
--------------------
* The default format of `today_fmt` and `html_last_updated_fmt` is back to
strftime format again. Locale Date Markup Language is also supported for
backward compatibility until Sphinx-1.5.
Translations
------------
* Added Welsh translation, thanks to Geraint Palmer.
* Added Greek translation, thanks to Stelios Vitalis.
* Added Esperanto translation, thanks to Dinu Gherman.
* Added Hindi translation, thanks to Purnank H. Ghumalia.
* Added Romanian translation, thanks to Razvan Stefanescu.
Bugs fixed
----------
* C++, added support for ``extern`` and ``thread_local``.
* C++, type declarations are now using the prefixes ``typedef``, ``using``, and ``type``,
depending on the style of declaration.
* #2413: C++, fix crash on duplicate declarations
* #2394: Sphinx crashes when html_last_updated_fmt is invalid
* #2408: dummy builder not available in Makefile and make.bat
* #2412: hyperlink targets are broken in LaTeX builder
* figure directive crashes if non paragraph item is given as caption
* #2418: time formats no longer allowed in today_fmt
* #2395: Sphinx crashes if unicode character in image filename
* #2396: "too many values to unpack" in genindex-single
* #2405: numref link in PDF jumps to the wrong location
* #2414: missing number in PDF hyperlinks to code listings
* #2440: wrong import for gmtime. Thanks to Uwe L. Korn.
Release 1.4 (released Mar 28, 2016)
===================================
Incompatible changes
--------------------
* Drop ``PorterStemmer`` package support. Use ``PyStemmer`` instead of ``PorterStemmer``
to accelerate stemming.
* sphinx_rtd_theme has become optional. Please install it manually.
Refs #2087, #2086, #1845 and #2097. Thanks to Victor Zverovich.
* #2231: Use DUrole instead of DUspan for custom roles in LaTeX writer. It enables to take
title of roles as an argument of custom macros.
* #2022: 'Thumbs.db' and '.DS_Store' are added to `exclude_patterns` default values in
conf.py that will be provided on sphinx-quickstart.
* #2027, #2208: The ``html_title`` accepts string values only. And The None value cannot be
accepted.
* ``sphinx.ext.graphviz``: show graph image in inline by default
* #2060, #2224: The ``manpage`` role now generate ``sphinx.addnodes.manpage`` node instead
of ``sphinx.addnodes.literal_emphasis`` node.
* #2022: :confval:`html_extra_path` also copies dotfiles in the extra directory, and
refers to :confval:`exclude_patterns` to exclude extra files and directories.
* #2300: enhance autoclass:: to use the docstring of __new__ if __init__ method's is missing
of empty
* #2251: Previously, under glossary directives, multiple terms for one definition are
converted into single ``term`` node and the each terms in the term node are separated
by ``termsep`` node. In new implementation, each terms are converted into individual
``term`` nodes and ``termsep`` node is removed.
By this change, output layout of every builders are changed a bit.
* The default highlight language is now Python 3. This means that source code
is highlighted as Python 3 (which is mostly a superset of Python 2), and no
parsing is attempted to distinguish valid code. To get the old behavior back,
add ``highlight_language = "python"`` to conf.py.
* `Locale Date Markup Language
<http://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns>`_ like
``"MMMM dd, YYYY"`` is default format for `today_fmt` and `html_last_updated_fmt`.
However strftime format like ``"%B %d, %Y"`` is also supported for backward
compatibility until Sphinx-1.5. Later format will be disabled from Sphinx-1.5.
* #2327: `latex_use_parts` is deprecated now. Use `latex_toplevel_sectioning` instead.
* #2337: Use ``\url{URL}`` macro instead of ``\href{URL}{URL}`` in LaTeX writer.
* #1498: manpage writer: don't make whole of item in definition list bold if it includes strong node.
* #582: Remove hint message from quick search box for html output.
* #2378: Sphinx now bundles newfloat.sty
Features added
--------------
* #2092: add todo directive support in napoleon package.
* #1962: when adding directives, roles or nodes from an extension, warn if such
an element is already present (built-in or added by another extension).
* #1909: Add "doc" references to Intersphinx inventories.
* C++ type alias support (e.g., ``.. type:: T = int``).
* C++ template support for classes, functions, type aliases, and variables (#1729, #1314).
* C++, added new scope management directives ``namespace-push`` and ``namespace-pop``.
* #1970: Keyboard shortcuts to navigate Next and Previous topics
* Intersphinx: Added support for fetching Intersphinx inventories with URLs
using HTTP basic auth.
* C++, added support for template parameter in function info field lists.
* C++, added support for pointers to member (function).
* #2113: Allow ``:class:`` option to code-block directive.
* #2192: Imgmath (pngmath with svg support).
* #2200: Support XeTeX and LuaTeX for the LaTeX builder.
* #1906: Use xcolor over color for \fcolorbox where available for LaTeX output.
* #2216: Texinputs makefile improvements.
* #2170: Support for Chinese language search index.
* #2214: Add sphinx.ext.githubpages to publish the docs on GitHub Pages
* #1030: Make page reference names for latex_show_pagerefs translatable
* #2162: Add Sphinx.add_source_parser() to add source_suffix and source_parsers from extension
* #2207: Add sphinx.parsers.Parser class; a base class for new parsers
* #656: Add ``graphviz_dot`` option to graphviz directives to switch the ``dot`` command
* #1939: Added the ``dummy`` builder: syntax check without output.
* #2230: Add ``math_number_all`` option to number all displayed math in math extensions
* #2235: ``needs_sphinx`` supports micro version comparison
* #2282: Add "language" attribute to html tag in the "basic" theme
* #1779: Add EPUB 3 builder
* #1751: Add :confval:`todo_link_only` to avoid file path and line indication on
:rst:dir:`todolist`. Thanks to Francesco Montesano.
* #2199: Use ``imagesize`` package to obtain size of images.
* #1099: Add configurable retries to the linkcheck builder. Thanks to Alex Gaynor.
Also don't check anchors starting with ``!``.
* #2300: enhance autoclass:: to use the docstring of __new__ if __init__ method's is missing
of empty
* #1858: Add Sphinx.add_enumerable_node() to add enumerable nodes for numfig feature
* #1286, #2099: Add ``sphinx.ext.autosectionlabel`` extension to allow reference
sections using its title. Thanks to Tadhg O'Higgins.
* #1854: Allow to choose Janome for Japanese splitter.
* #1853: support custom text splitter on html search with ``language='ja'``.
* #2320: classifier of glossary terms can be used for index entries grouping key.
The classifier also be used for translation. See also :ref:`glossary-directive`.
* #2308: Define ``\tablecontinued`` macro to redefine the style of continued label for
longtables.
* Select an image by similarity if multiple images are globbed by ``.. image:: filename.*``
* #1921: Support figure substitutions by :confval:`language` and :confval:`figure_language_filename`
* #2245: Add ``latex_elements["passoptionstopackages"]`` option to call PassOptionsToPackages
in early stage of preambles.
* #2340: Math extension: support alignment of multiple equations for MathJAX.
* #2338: Define ``\titleref`` macro to redefine the style of ``title-reference`` roles.
* Define ``\menuselection`` and ``\accelerator`` macros to redefine the style of `menuselection` roles.
* Define ``\crossref`` macro to redefine the style of references
* #2301: Texts in the classic html theme should be hyphenated.
* #2355: Define ``\termref`` macro to redefine the style of ``term`` roles.
* Add :confval:`suppress_warnings` to suppress arbitrary warning message (experimental)
* #2229: Fix no warning is given for unknown options
* #2327: Add `latex_toplevel_sectioning` to switch the top level sectioning of LaTeX document.
Bugs fixed
----------
* #1913: C++, fix assert bug for enumerators in next-to-global and global scope.
* C++, fix parsing of 'signed char' and 'unsigned char' as types.
* C++, add missing support for 'friend' functions.
* C++, add missing support for virtual base classes (thanks to Rapptz).
* C++, add support for final classes.
* C++, fix parsing of types prefixed with 'enum'.
* #2023: Dutch search support uses Danish stemming info.
* C++, add support for user-defined literals.
* #1804: Now html output wraps overflowed long-line-text in the sidebar. Thanks to
Hassen ben tanfous.
* #2183: Fix porterstemmer causes ``make json`` to fail.
* #1899: Ensure list is sent to OptParse.
* #2164: Fix wrong check for pdftex inside sphinx.sty (for graphicx package option).
* #2165, #2218: Remove faulty and non-need conditional from sphinx.sty.
* Fix broken LaTeX code is generated if unknown language is given
* #1944: Fix rst_prolog breaks file-wide metadata
* #2074: make gettext should use canonical relative paths for .pot. Thanks to
anatoly techtonik.
* #2311: Fix sphinx.ext.inheritance_diagram raises AttributeError
* #2251: Line breaks in .rst files are transferred to .pot files in a wrong way.
* #794: Fix date formatting in latex output is not localized
* Remove ``image/gif`` from supported_image_types of LaTeX writer (#2272)
* Fix ValueError is raised if LANGUAGE is empty string
* Fix unpack warning is shown when the directives generated from ``Sphinx.add_crossref_type`` is used
* The default highlight language is now ``default``. This means that source code
is highlighted as Python 3 (which is mostly a superset of Python 2) if possible.
To get the old behavior back, add ``highlight_language = "python"`` to conf.py.
* #2329: Refresh environment forcely if source directory has changed.
* #2331: Fix code-blocks are filled by block in dvi; remove ``xcdraw`` option from
xcolor package
* Fix the confval type checker emits warnings if unicode is given to confvals which expects string value
* #2360: Fix numref in LaTeX output is broken
* #2361: Fix additional paragraphs inside the "compound" directive are indented
* #2364: Fix KeyError 'rootSymbol' on Sphinx upgrade from older version.
* #2348: Move amsmath and amssymb to before fontpkg on LaTeX writer.
* #2368: Ignore emacs lock files like ``.#foo.rst`` by default.
* #2262: literal_block and its caption has been separated by pagebreak in LaTeX output.
* #2319: Fix table counter is overrided by code-block's in LaTeX. Thanks to jfbu.
* Fix unpack warning if combinated with 3rd party domain extensions.
* #1153: Fix figures in sidebar causes latex build error.
* #2358: Fix user-preamble could not override the tocdepth definition.
* #2358: Redece tocdepth if ``part`` or ``chapter`` is used for top_sectionlevel.
* #2351: Fix footnote spacing
* #2363: Fix ``toctree()`` in templates generates broken links in SingleHTMLBuilder.
* #2366: Fix empty hyperref is generated on toctree in HTML builder.
Documentation
-------------
* #1757: Fix for usage of :confval:`html_last_updated_fmt`. Thanks to Ralf Hemmecke.
Release 1.3.6 (released Feb 29, 2016)
=====================================
Features added
--------------
* #1873, #1876, #2278: Add ``page_source_suffix`` html context variable. This should be
introduced with :confval:`source_parsers` feature. Thanks for Eric Holscher.
Bugs fixed
----------
* #2265: Fix babel is used in spite of disabling it on ``latex_elements``
* #2295: Avoid mutating dictionary errors while enumerating members in autodoc
with Python 3
* #2291: Fix pdflatex "Counter too large" error from footnotes inside tables of contents
* #2292: Fix some footnotes disappear from LaTeX output
* #2287: ``sphinx.transforms.Locale`` always uses rst parser. Sphinx i18n feature should
support parsers that specified source_parsers.
* #2290: Fix ``sphinx.ext.mathbase`` use of amsfonts may break user choice of math fonts
* #2324: Print a hint how to increase the recursion limit when it is hit.
* #1565, #2229: Revert new warning; the new warning will be triggered from version 1.4 on.
* #2329: Refresh environment forcely if source directory has changed.
* #2019: Fix the domain objects in search result are not escaped
Release 1.3.5 (released Jan 24, 2016)
=====================================
Bugs fixed
----------
* Fix line numbers was not shown on warnings in LaTeX and texinfo builders
* Fix filenames were not shown on warnings of citations
* Fix line numbers was not shown on warnings in LaTeX and texinfo builders
* Fix line numbers was not shown on warnings of indices
* #2026: Fix LaTeX builder raises error if parsed-literal includes links
* #2243: Ignore strange docstring types for classes, do not crash
* #2247: Fix #2205 breaks make html for definition list with classifiers
that contains regular-expression like string
* #1565: Sphinx will now emit a warning that highlighting was skipped if the syntax
is incorrect for `code-block`, `literalinclude` and so on.
* #2211: Fix paragraphs in table cell doesn't work in Latex output
* #2253: ``:pyobject:`` option of ``literalinclude`` directive can't detect indented
body block when the block starts with blank or comment lines.
* Fix TOC is not shown when no ``:maxdepth:`` for toctrees (ref: #771)
* Fix warning message for ``:numref:`` if target is in orphaned doc (ref: #2244)
Release 1.3.4 (released Jan 12, 2016)
=====================================
Bugs fixed
----------
* #2134: Fix figure caption with reference causes latex build error
* #2094: Fix rubric with reference not working in Latex
* #2147: Fix literalinclude code in latex does not break in pages
* #1833: Fix email addresses is showed again if latex_show_urls is not None
* #2176: sphinx.ext.graphviz: use <object> instead of <img> to embed svg
* #967: Fix SVG inheritance diagram is not hyperlinked (clickable)
* #1237: Fix footnotes not working in definition list in LaTeX
* #2168: Fix raw directive does not work for text writer
* #2171: Fix cannot linkcheck url with unicode
* #2182: LaTeX: support image file names with more than 1 dots
* #2189: Fix previous sibling link for first file in subdirectory uses last file, not
intended previous from root toctree
* #2003: Fix decode error under python2 (only) when ``make linkcheck`` is run
* #2186: Fix LaTeX output of \mathbb in math
* #1480, #2188: LaTeX: Support math in section titles
* #2071: Fix same footnote in more than two section titles => LaTeX/PDF Bug
* #2040: Fix UnicodeDecodeError in sphinx-apidoc when author contains non-ascii characters
* #2193: Fix shutil.SameFileError if source directory and destination directory are same
* #2178: Fix unparseable C++ cross-reference when referencing a function with :cpp:any:
* #2206: Fix Sphinx latex doc build failed due to a footnotes
* #2201: Fix wrong table caption for tables with over 30 rows
* #2213: Set <blockquote> in the classic theme to fit with <p>
* #1815: Fix linkcheck does not raise an exception if warniserror set to true and link is
broken
* #2197: Fix slightly cryptic error message for missing index.rst file
* #1894: Unlisted phony targets in quickstart Makefile
* #2125: Fix unifies behavior of collapsed fields (``GroupedField`` and ``TypedField``)
* #1408: Check latex_logo validity before copying
* #771: Fix latex output doesn't set tocdepth
* #1820: On Windows, console coloring is broken with colorama version 0.3.3.
Now sphinx use colorama>=0.3.5 to avoid this problem.
* #2072: Fix footnotes in chapter-titles do not appear in PDF output
* #1580: Fix paragraphs in longtable don't work in Latex output
* #1366: Fix centered image not centered in latex
* #1860: Fix man page using ``:samp:`` with braces - font doesn't reset
* #1610: Sphinx crashes in japanese indexing in some systems
* Fix Sphinx crashes if mecab initialization failed
* #2160: Fix broken TOC of PDFs if section includes an image
* #2172: Fix dysfunctional admonition \py@lightbox in sphinx.sty. Thanks to jfbu.
* #2198,#2205: ``make gettext`` generate broken msgid for definition lists.
* #2062: Escape characters in doctests are treated incorrectly with Python 2.
* #2225: Fix if the option does not begin with dash, linking is not performed
* #2226: Fix math is not HTML-encoded when :nowrap: is given (jsmath, mathjax)
* #1601, #2220: 'any' role breaks extended domains behavior. Affected extensions doesn't
support resolve_any_xref and resolve_xref returns problematic node instead of None.
sphinxcontrib-httpdomain is one of them.
* #2229: Fix no warning is given for unknown options
Release 1.3.3 (released Dec 2, 2015)
====================================
Bugs fixed
----------
* #2177: Fix parallel hangs
* #2012: Fix exception occurred if ``numfig_format`` is invalid
* #2142: Provide non-minified JS code in ``sphinx/search/non-minified-js/*.js`` for
source distribution on PyPI.
* #2148: Error while building devhelp target with non-ASCII document.
Release 1.3.2 (released Nov 29, 2015)
=====================================
Features added
--------------
* #1935: Make "numfig_format" overridable in latex_elements.
Bugs fixed
----------
* #1976: Avoid "2.0" version of Babel because it doesn't work with Windows environment.
* Add a "default.css" stylesheet (which imports "classic.css") for compatibility.
* #1788: graphviz extension raises exception when caption option is present.
* #1789: ``:pyobject:`` option of ``literalinclude`` directive includes following
lines after class definitions
* #1790: ``literalinclude`` strips empty lines at the head and tail
* #1802: load plugin themes automatically when theme.conf use it as 'inherit'. Thanks to
Takayuki Hirai.
* #1794: custom theme extended from alabaster or sphinx_rtd_theme can't find base theme.
* #1834: compatibility for docutils-0.13: handle_io_errors keyword argument for
docutils.io.FileInput cause TypeError.
* #1823: '.' as <module_path> for sphinx-apidoc cause an unfriendly error. Now '.'
is converted to absolute path automatically.
* Fix a crash when setting up extensions which do not support metadata.
* #1784: Provide non-minified JS code in ``sphinx/search/non-minified-js/*.js``
* #1822, #1892: Fix regression for #1061. autosummary can't generate doc for imported
members since sphinx-1.3b3. Thanks to Eric Larson.
* #1793, #1819: "see also" misses a linebreak in text output. Thanks to Takayuki Hirai.
* #1780, #1866: "make text" shows "class" keyword twice. Thanks to Takayuki
Hirai.
* #1871: Fix for LaTeX output of tables with one column and multirows.
* Work around the lack of the HTMLParserError exception in Python 3.5.
* #1949: Use ``safe_getattr`` in the coverage builder to avoid aborting with
descriptors that have custom behavior.
* #1915: Do not generate smart quotes in doc field type annotations.
* #1796: On py3, automated .mo building caused UnicodeDecodeError.
* #1923: Use babel features only if the babel latex element is nonempty.
* #1942: Fix a KeyError in websupport.
* #1903: Fix strange id generation for glossary terms.
* ``make text`` will crush if a definition list item has more than 1 classifiers as:
``term : classifier1 : classifier2``.
* #1855: make gettext generates broken po file for definition lists with classifier.
* #1869: Fix problems when dealing with files containing non-ASCII characters. Thanks to
Marvin Schmidt.
* #1798: Fix building LaTeX with references in titles.
* #1725: On py2 environment, doctest with using non-ASCII characters causes
``'ascii' codec can't decode byte`` exception.
* #1540: Fix RuntimeError with circular referenced toctree
* #1983: i18n translation feature breaks references which uses section name.
* #1990: Use caption of toctree to title of \tableofcontents in LaTeX
* #1987: Fix ampersand is ignored in ``:menuselection:`` and ``:guilabel:`` on LaTeX builder
* #1994: More supporting non-standard parser (like recommonmark parser) for Translation and
WebSupport feature. Now node.rawsource is fall backed to node.astext() during docutils
transforming.
* #1989: "make blahblah" on Windows indicate help messages for sphinx-build every time.
It was caused by wrong make.bat that generated by Sphinx-1.3.0/1.3.1.
* On Py2 environment, conf.py that is generated by sphinx-quickstart should have u prefixed
config value for 'version' and 'release'.
* #2102: On Windows + Py3, using ``|today|`` and non-ASCII date format will raise
UnicodeEncodeError.
* #1974: UnboundLocalError: local variable 'domain' referenced before assignment when
using `any` role and `sphinx.ext.intersphinx` in same time.
* #2121: multiple words search doesn't find pages when words across on the page title and
the page content.
* #1884, #1885: plug-in html themes cannot inherit another plug-in theme. Thanks to
Suzumizaki.
* #1818: `sphinx.ext.todo` directive generates broken html class attribute as
'admonition-' when :confval:`language` is specified with non-ASCII linguistic area like
'ru' or 'ja'. To fix this, now ``todo`` directive can use ``:class:`` option.
* #2140: Fix footnotes in table has broken in LaTeX
* #2127: MecabBinder for html searching feature doesn't work with Python 3.
Thanks to Tomoko Uchida.
Release 1.3.1 (released Mar 17, 2015)
=====================================
@ -43,6 +734,7 @@ Bugs fixed
Thanks to Jens Hedegaard Nielsen.
* #1781: Setting `html_domain_indices` to a list raises a type check warnings.
Release 1.3 (released Mar 10, 2015)
===================================
@ -91,6 +783,7 @@ Documentation
* #1651: Add ``vartype`` field descritpion for python domain.
Release 1.3b3 (released Feb 24, 2015)
=====================================
@ -100,7 +793,7 @@ Incompatible changes
* Dependency requirement updates: docutils 0.11, Pygments 2.0
* The ``gettext_enables`` config value has been renamed to
`gettext_additional_targets`.
* #1735: Use https://doc.python.org/ instead of ``http`` protocol.
* #1735: Use https://docs.python.org/ instead of ``http`` protocol.
It was used for `sphinx.ext.intersphinx` and some documentation.
Features added
@ -495,7 +1188,7 @@ Bugs fixed
if they contain uppercase letters.
* #923: Take the entire LaTeX document into account when caching
pngmath-generated images. This rebuilds them correctly when
`pngmath_latex_preamble` changes.
``pngmath_latex_preamble`` changes.
* #901: Emit a warning when using docutils' new "math" markup without a Sphinx
math extension active.
* #845: In code blocks, when the selected lexer fails, display line numbers
@ -824,13 +1517,12 @@ Features added
* Command-line interfaces:
- PR#75: Added ``--follow-links`` option to sphinx-apidoc.
- #869: sphinx-build now has the option :option:`-T` for printing the full
- #869: sphinx-build now has the option ``-T`` for printing the full
traceback after an unhandled exception.
- sphinx-build now supports the standard :option:`--help` and
:option:`--version` options.
- sphinx-build now supports the standard ``--help`` and ``--version`` options.
- sphinx-build now provides more specific error messages when called with
invalid options or arguments.
- sphinx-build now has a verbose option :option:`-v` which can be repeated for
- sphinx-build now has a verbose option ``-v`` which can be repeated for
greater effect. A single occurrence provides a slightly more verbose output
than normal. Two or more occurrences of this option provides more detailed
output which may be useful for debugging.
@ -852,7 +1544,7 @@ Features added
stemming routines. Saves about 20 seconds when building the Python
documentation.
- PR#108: Add experimental support for parallel building with a new
:option:`-j` option.
:option:`sphinx-build -j` option.
Documentation
-------------
@ -1114,7 +1806,7 @@ Features added
indicators.
- #367: Added automatic exclusion of hidden members in inheritance
diagrams, and an option to selectively enable it.
- Added `pngmath_add_tooltips`.
- Added ``pngmath_add_tooltips``.
- The math extension displaymath directives now support ``name`` in
addition to ``label`` for giving the equation label, for compatibility
with Docutils.
@ -1442,7 +2134,7 @@ Features added
* General:
- Added a "nitpicky" mode that emits warnings for all missing
references. It is activated by the :option:`-n` command-line switch
references. It is activated by the :option:`sphinx-build -n` command-line switch
or the `nitpicky` config value.
- Added ``latexpdf`` target in quickstart Makefile.

77
EXAMPLES
View File

@ -4,22 +4,27 @@ Projects using Sphinx
This is an (incomplete) alphabetic list of projects that use Sphinx or
are experimenting with using it for their documentation. If you like to
be included, please mail to `the Google group
<https://groups.google.com/group/sphinx-users>`_.
<https://groups.google.com/forum/#!forum/sphinx-users>`_.
I've grouped the list into sections to make it easier to find
interesting examples.
Documentation using the default theme
Documentation using the alabaster theme
---------------------------------------
* PyLangAcq: http://pylangacq.org/
Documentation using the classic theme
-------------------------------------
* APSW: http://apidoc.apsw.googlecode.com/hg/index.html
* ASE: https://wiki.fysik.dtu.dk/ase/
* Calibre: http://manual.calibre-ebook.com/
* CodePy: http://documen.tician.de/codepy/
* CodePy: https://documen.tician.de/codepy/
* Cython: http://docs.cython.org/
* Cormoran: http://cormoran.nhopkg.org/docs/
* Director: http://pythonhosted.org/director/
* Dirigible: http://www.projectdirigible.com/documentation/
* Dirigible: http://www.projectdirigible.com/
* F2py: http://f2py.sourceforge.net/docs/
* GeoDjango: https://docs.djangoproject.com/en/dev/ref/contrib/gis/
* Genomedata:
@ -31,10 +36,10 @@ Documentation using the default theme
* Heapkeeper: http://heapkeeper.org/
* Hands-on Python Tutorial:
http://anh.cs.luc.edu/python/hands-on/3.1/handsonHtml/
* Hedge: http://documen.tician.de/hedge/
* Hedge: https://documen.tician.de/hedge/
* Leo: http://leoeditor.com/
* Lino: http://lino.saffre-rumma.net/
* MeshPy: http://documen.tician.de/meshpy/
* Lino: http://www.lino-framework.org/
* MeshPy: https://documen.tician.de/meshpy/
* mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html
* OpenEXR: http://excamera.com/articles/26/doc/index.html
* OpenGDA: http://www.opengda.org/gdadoc/html/
@ -42,19 +47,21 @@ Documentation using the default theme
* Paste: http://pythonpaste.org/script/
* Paver: http://paver.github.io/paver/
* Pioneers and Prominent Men of Utah: http://pioneers.rstebbing.com/
* PyCantonese: http://pycantonese.github.io/
* PyCantonese: http://pycantonese.org/
* Pyccuracy: https://github.com/heynemann/pyccuracy/wiki/
* PyCuda: http://documen.tician.de/pycuda/
* PyCuda: https://documen.tician.de/pycuda/
* Pyevolve: http://pyevolve.sourceforge.net/
* Pylo: http://documen.tician.de/pylo/
* Pylo: https://documen.tician.de/pylo/
* PyMQI: http://pythonhosted.org/pymqi/
* PyPubSub: http://pubsub.sourceforge.net/
* pySPACE: http://pyspace.github.io/pyspace/
* Python: https://docs.python.org/
* Python: https://docs.python.org/3/
* python-apt: http://apt.alioth.debian.org/python-apt-doc/
* PyUblas: http://documen.tician.de/pyublas/
* PyUblas: https://documen.tician.de/pyublas/
* Quex: http://quex.sourceforge.net/doc/html/main.html
* Ring programming language: http://ring-lang.sourceforge.net/doc/index.html
* Scapy: http://www.secdev.org/projects/scapy/doc/
* Seaborn: https://stanford.edu/~mwaskom/software/seaborn/
* Segway: http://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html
* SimPy: http://simpy.readthedocs.org/en/latest/
* SymPy: http://docs.sympy.org/
@ -62,11 +69,12 @@ Documentation using the default theme
* z3c: http://www.ibiblio.org/paulcarduner/z3ctutorial/
Documentation using a customized version of the default theme
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/
@ -78,7 +86,6 @@ Documentation using a customized version of the default theme
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/
* IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
* Kaa: http://api.freevo.org/kaa-base/
* LEPL: http://www.acooke.org/lepl/
* Mayavi: http://docs.enthought.com/mayavi/mayavi/
@ -87,11 +94,11 @@ Documentation using a customized version of the default theme
* NumPy: http://docs.scipy.org/doc/numpy/reference/
* OpenCV: http://docs.opencv.org/
* Peach^3: http://peach3.nl/doc/latest/userdoc/
* Sage: http://sagemath.org/doc/
* 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.org/2.0/docs/
* 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
@ -114,18 +121,19 @@ Documentation using the sphinxdoc theme
* Python Wild Magic: http://vmlaker.github.io/pythonwildmagic/
* Reteisi: http://www.reteisi.org/contents.html
* Sqlkit: http://sqlkit.argolinux.org/
* Tau: http://www.tango-controls.org/static/tau/latest/doc/html/index.html
* Turbulenz: http://docs.turbulenz.com/
* WebFaction: http://docs.webfaction.com/
* WebFaction: https://docs.webfaction.com/
Documentation using another builtin 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)
* MPipe: http://vmlaker.github.io/mpipe/ (sphinx13)
* pip: https://pip.pypa.io/en/latest/ (sphinx_rtd_theme)
* Pyramid web framework:
@ -145,12 +153,12 @@ Documentation using another builtin theme
Documentation using a custom theme/integrated in a site
-------------------------------------------------------
* Blender: http://www.blender.org/documentation/250PythonDoc/
* Blender: https://www.blender.org/api/250PythonDoc/
* Blinker: http://discorporate.us/projects/Blinker/docs/
* Ceph: http://ceph.com/docs/master/
* 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: http://docs.djangoproject.com/
* 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/
@ -159,34 +167,33 @@ Documentation using a custom theme/integrated in a site
* Flask-OpenID: http://pythonhosted.org/Flask-OpenID/
* Gameduino: http://excamera.com/sphinx/gameduino/
* GeoServer: http://docs.geoserver.org/
* GHC - Glasgow Haskell Compiler: http://downloads.haskell.org/~ghc/master/users-guide/
* Glashammer: http://glashammer.org/
* Istihza (Turkish Python documentation project):
http://www.istihza.com/py2/icindekiler_python.html
* 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://notex.ch/overview/
* NoTex: https://www.notex.ch/overview/
* ObjectListView: http://objectlistview.sourceforge.net/python/
* Open ERP: http://doc.openerp.com/
* Open ERP: https://doc.odoo.com/
* OpenCV: http://docs.opencv.org/
* Open Dylan: http://opendylan.org/documentation/ and also provides a
`dylan domain <https://github.com/dylan-lang/sphinx-extensions/blob/master/dylandomain/reference.rst>`__
* 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://sirius.chem.vt.edu/psi4manual/latest/index.html
* PSI4: http://www.psicode.org/psi4manual/master/index.html
* Pylons: http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/
* PyMOTW: http://pymotw.com/2/
* 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/
* Selenium: http://docs.seleniumhq.org/docs/
* Self: http://selflanguage.org/
* 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/
@ -201,14 +208,12 @@ Documentation using a custom theme/integrated in a site
Homepages and other non-documentation sites
-------------------------------------------
* Applied Mathematics at the Stellenbosch University: http://dip.sun.ac.za/
* A personal page: http://www.dehlia.in/
* Benoit Boissinot: http://bboissin.appspot.com/
* lunarsite: http://lunaryorn.de/
* Red Hot Chili Python: http://redhotchilipython.com/
* The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
* UC Berkeley Advanced Control Systems course:
http://www.me.berkeley.edu/ME233/sp14/
http://msc.berkeley.edu/tomizuka/me233spring13/
* VOR: http://www.vor-cycling.be/
@ -217,11 +222,11 @@ 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://theoretical-physics.net/
* 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":
http://www.packtpub.com/expert-python-programming/book
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):
@ -231,7 +236,7 @@ Books produced using Sphinx
* "Die Wahrheit des Sehens. Der DEKALOG von Krzysztof Kieślowski":
http://www.hasecke.eu/Dekalog/
* The "Varnish Book":
https://www.varnish-software.com/static/book/
http://book.varnish-software.com/4.0/
* "Learning Sphinx" (in Japanese):
http://www.oreilly.co.jp/books/9784873116488/
* "LassoGuide":

2
LICENSE
View File

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

5
MANIFEST.in
View File

@ -13,14 +13,15 @@ include sphinx-build.py
include sphinx-quickstart.py
include sphinx-apidoc.py
recursive-include sphinx/templates *
recursive-include sphinx/texinputs *
recursive-include sphinx/themes *
recursive-include sphinx/locale *
recursive-include sphinx/search/non-minified-js *.js
recursive-include sphinx/ext/autosummary/templates *
recursive-include tests *
recursive-include utils *
include sphinx/pycode/Grammar-py2.txt
include sphinx/pycode/Grammar-py3.txt
include sphinx/pycode/Grammar-py*
recursive-include doc *
prune doc/_build

44
Makefile
View File

@ -1,12 +1,17 @@
PYTHON ?= python
.PHONY: all check clean clean-pyc clean-patchfiles clean-backupfiles \
clean-generated pylint reindent test covertest build convert-utils
.PHONY: all style-check clean clean-pyc clean-patchfiles clean-backupfiles \
clean-generated pylint reindent test covertest build
DONT_CHECK = -i build -i dist -i sphinx/style/jquery.js \
-i sphinx/pycode/pgen2 -i sphinx/util/smartypants.py \
-i .ropeproject -i doc/_build -i tests/path.py \
-i tests/coverage.py -i env -i utils/convert.py \
-i tests/coverage.py -i utils/convert.py \
-i tests/typing_test_data.py \
-i tests/test_autodoc_py35.py \
-i tests/roots/test-warnings/undecodable.rst \
-i tests/build \
-i tests/roots/test-warnings/undecodable.rst \
-i sphinx/search/da.py \
-i sphinx/search/de.py \
-i sphinx/search/en.py \
@ -23,24 +28,22 @@ DONT_CHECK = -i build -i dist -i sphinx/style/jquery.js \
-i sphinx/search/ru.py \
-i sphinx/search/sv.py \
-i sphinx/search/tr.py \
-i utils/reindent3.py -i utils/check_sources3.py -i .tox
-i .tox
all: clean-pyc clean-backupfiles check test
all: clean-pyc clean-backupfiles style-check test
ifeq ($(PYTHON), python3)
check: convert-utils
@$(PYTHON) utils/check_sources3.py $(DONT_CHECK) .
else
check:
style-check:
@$(PYTHON) utils/check_sources.py $(DONT_CHECK) .
endif
clean: clean-pyc clean-patchfiles clean-backupfiles clean-generated
clean: clean-pyc clean-pycache clean-patchfiles clean-backupfiles clean-generated clean-testfiles
clean-pyc:
find . -name '*.pyc' -exec rm -f {} +
find . -name '*.pyo' -exec rm -f {} +
clean-pycache:
find . -name __pycache__ -exec rm -rf {} +
clean-patchfiles:
find . -name '*.orig' -exec rm -f {} +
find . -name '*.rej' -exec rm -f {} +
@ -52,18 +55,20 @@ clean-backupfiles:
clean-generated:
rm -f utils/*3.py*
clean-testfiles:
rm -rf tests/build
rm -rf .tox/
pylint:
@pylint --rcfile utils/pylintrc sphinx
ifeq ($(PYTHON), python3)
reindent: convert-utils
@$(PYTHON) utils/reindent3.py -r -n .
else
reindent:
@$(PYTHON) utils/reindent.py -r -n .
endif
test:
@cd tests; $(PYTHON) run.py -I py35 -d -m '^[tT]est' $(TEST)
test-async:
@cd tests; $(PYTHON) run.py -d -m '^[tT]est' $(TEST)
covertest:
@ -72,8 +77,3 @@ covertest:
build:
@$(PYTHON) setup.py build
ifeq ($(PYTHON), python3)
convert-utils:
@python3 utils/convert.py -i utils/convert.py utils/
endif

6
README.rst
View File

@ -33,6 +33,12 @@ Install from cloned source as editable::
pip install -e .
Release signatures
==================
Releases are signed with `498D6B9E <https://pgp.mit.edu/pks/lookup?op=vindex&search=0x102C2C17498D6B9E>`_
Reading the docs
================

BIN
doc/_static/bookcover.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 27 KiB

BIN
doc/_static/pocoo.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.0 KiB

After

Width:  |  Height:  |  Size: 1.5 KiB

BIN
doc/_static/sphinx.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 33 KiB

21
doc/_templates/index.html vendored
View File

@ -5,17 +5,16 @@
<div class="quotebar">
<p><em>{%trans%}What users say:{%endtrans%}</em></p>
<p>{%trans%}&ldquo;Cheers for a great tool that actually makes programmers <b>want</b>
to write documentation!&rdquo;{%endtrans%}</p>
<p>{%trans%}&#8220;Cheers for a great tool that actually makes programmers <b>want</b>
to write documentation!&#8220;{%endtrans%}</p>
</div>
<p>{%trans%}
Sphinx is a tool that makes it easy to create intelligent and beautiful
documentation, written by Georg Brandl and licensed under the BSD license.{%endtrans%}</p>
<p>{%trans%}It was originally created for <a href="https://docs.python.org/">the
new Python documentation</a>, and it has excellent facilities for the
documentation of Python projects, but C/C++ is already supported as well,
and it is planned to add special support for other languages as well. Of
Python documentation</a>, and it has excellent facilities for the
documentation of software projects in a range of languages. Of
course, this site is also created from reStructuredText sources using
Sphinx! The following features should be highlighted:{%endtrans%}
</p>
@ -39,10 +38,10 @@
in a second repository; most of them installable from PyPI{%endtrans%}</li>
</ul>
<p>{%trans%}
Sphinx uses <a href="http://docutils.sf.net/rst.html">reStructuredText</a>
Sphinx uses <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>
as its markup language, and many of its strengths come from the power and
straightforwardness of reStructuredText and its parsing and translating
suite, the <a href="http://docutils.sf.net/">Docutils</a>.{%endtrans%}
suite, the <a href="http://docutils.sourceforge.net/">Docutils</a>.{%endtrans%}
</p>
<h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>
@ -62,11 +61,11 @@
</table>
<p>{%trans%}
You can also download PDF versions of the Sphinx documentation:
a <a href="http://sphinx-doc.org/sphinx.pdf">version</a> generated from
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://sphinx-doc.org/sphinx-rst2pdf.pdf">version</a> generated
by rst2pdf.{%endtrans%}
a <a href="http://readthedocs.org/projects/sphinx/downloads/epub/stable/">EPUB version</a>.
{%endtrans%}
</p>
<h2>{%trans%}Examples{%endtrans%}</h2>

10
doc/_templates/indexsidebar.html vendored
View File

@ -14,20 +14,12 @@
<p>{%trans%}Current version: <b>{{ version }}</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>
{% if version.split('b')|length > 1 %}
<pre>pip install Sphinx=={{ version }}</pre>
<p>{%trans%}<a href="http://sphinx-doc.org/">Stable version docs</a>
are also available.{%endtrans%}</p>
{% else %}
<pre>pip install -U Sphinx</pre>
<p>{%trans%}Latest <a href="http://sphinx-doc.org/latest/">development version docs</a>
are also available.{%endtrans%}</p>
{% endif %}
{% endif %}
<h3>{%trans%}Questions? Suggestions?{%endtrans%}</h3>
<p>{%trans%}Join the <a href="http://groups.google.com/group/sphinx-users">Google group</a>:{%endtrans%}</p>
<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"

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

@ -4,7 +4,7 @@
Sphinx layout template for the sphinxdoc theme.
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
#}
{%- extends "basic/layout.html" %}
@ -57,8 +57,8 @@
{% endblock %}
{% block rootrellink %}
<li><a href="{{ pathto('index') }}">Sphinx home</a>&nbsp;|</li>
<li><a href="{{ pathto('contents') }}">Documentation</a> &raquo;</li>
<li><a href="{{ pathto('index') }}">Sphinx home</a>&#160;|</li>
<li><a href="{{ pathto('contents') }}">Documentation</a> &#187;</li>
{% endblock %}
{% block header %}

BIN
doc/_themes/sphinx13/static/bodybg.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 513 B

After

Width:  |  Height:  |  Size: 429 B

BIN
doc/_themes/sphinx13/static/footerbg.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 220 B

After

Width:  |  Height:  |  Size: 180 B

BIN
doc/_themes/sphinx13/static/headerbg.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 230 B

After

Width:  |  Height:  |  Size: 189 B

BIN
doc/_themes/sphinx13/static/listitem.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 207 B

After

Width:  |  Height:  |  Size: 149 B

BIN
doc/_themes/sphinx13/static/relbg.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 223 B

After

Width:  |  Height:  |  Size: 183 B

2
doc/_themes/sphinx13/static/sphinx13.css vendored
View File

@ -4,7 +4,7 @@
*
* Sphinx stylesheet -- sphinx13 theme.
*
* :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
* :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/

BIN
doc/_themes/sphinx13/static/sphinxheader.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 11 KiB

76
doc/builders.rst
View File

@ -23,6 +23,8 @@ The builder's "name" must be given to the **-b** command-line option of
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. class:: DirectoryHTMLBuilder
@ -36,6 +38,8 @@ The builder's "name" must be given to the **-b** command-line option of
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. versionadded:: 0.6
@ -48,6 +52,8 @@ The builder's "name" must be given to the **-b** command-line option of
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. versionadded:: 1.0
@ -61,6 +67,8 @@ The builder's "name" must be given to the **-b** command-line option of
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. module:: sphinx.builders.qthelp
@ -72,9 +80,11 @@ The builder's "name" must be given to the **-b** command-line option of
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. _Qt help: http://qt-project.org/doc/qt-4.8/qthelp-framework.html
.. _Qt help: http://doc.qt.io/qt-4.8/qthelp-framework.html
.. module:: sphinx.builders.applehelp
.. class:: AppleHelpBuilder
@ -96,6 +106,8 @@ The builder's "name" must be given to the **-b** command-line option of
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. versionadded:: 1.3
@ -109,6 +121,8 @@ The builder's "name" must be given to the **-b** command-line option of
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. module:: sphinx.builders.epub
@ -117,13 +131,35 @@ The builder's "name" must be given to the **-b** command-line option of
This builder produces the same output as the standalone HTML builder, but
also generates an *epub* file for ebook readers. See :ref:`epub-faq` for
details about it. For definition of the epub format, have a look at
`<http://idpf.org/epub>`_ or `<http://en.wikipedia.org/wiki/EPUB>`_.
`<http://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_.
The builder creates *EPUB 2* files.
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. module:: sphinx.builders.epub3
.. class:: Epub3Builder
This builder produces the same output as the standalone HTML builder, but
also generates an *epub* file for ebook readers. See :ref:`epub-faq` for
details about it. For definition of the epub format, have a look at
`<http://idpf.org/epub>`_ or `<https://en.wikipedia.org/wiki/EPUB>`_.
The builder creates *EPUB 3* files.
This builder is still *experimental* because it can't generate valid EPUB 3
files.
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. versionadded:: 1.4
.. module:: sphinx.builders.latex
.. class:: LaTeXBuilder
@ -145,10 +181,12 @@ The builder's "name" must be given to the **-b** command-line option of
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
Note that a direct PDF builder using ReportLab is available in `rst2pdf
<http://rst2pdf.googlecode.com>`_ version 0.12 or greater. You need to add
<https://github.com/rst2pdf/rst2pdf>`_ version 0.12 or greater. You need to add
``'rst2pdf.pdfbuilder'`` to your :confval:`extensions` to enable it, its name is
``pdf``. Refer to the `rst2pdf manual <http://ralsina.me/static/manual.pdf>`_
for details.
@ -162,6 +200,8 @@ for details.
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. versionadded:: 0.4
@ -175,6 +215,8 @@ for details.
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. versionadded:: 1.0
@ -196,6 +238,8 @@ for details.
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. versionadded:: 1.1
@ -261,6 +305,8 @@ for details.
The old name ``web`` still works as well.
.. autoattribute:: format
.. autoattribute:: supported_image_types
The file suffix is ``.fpickle``. The global context is called
@ -276,6 +322,8 @@ for details.
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
The file suffix is ``.fjson``. The global context is called
@ -293,6 +341,8 @@ for details.
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. versionadded:: 1.1
@ -307,8 +357,22 @@ for details.
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. module:: sphinx.builders.dummy
.. class:: DummyBuilder
This builder produces no output. The input is only parsed and checked for
consistency. This is useful for linting purposes.
.. autoattribute:: name
.. autoattribute:: supported_image_types
.. versionadded:: 1.4
.. module:: sphinx.builders.linkcheck
.. class:: CheckExternalLinksBuilder
@ -318,6 +382,8 @@ for details.
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. module:: sphinx.builders.xml
@ -329,6 +395,8 @@ for details.
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. versionadded:: 1.2
@ -343,6 +411,8 @@ for details.
.. autoattribute:: name
.. autoattribute:: format
.. autoattribute:: supported_image_types
.. versionadded:: 1.2

11
doc/conf.py
View File

@ -15,7 +15,7 @@ templates_path = ['_templates']
exclude_patterns = ['_build']
project = 'Sphinx'
copyright = '2007-2015, Georg Brandl and the Sphinx team'
copyright = '2007-2016, Georg Brandl and the Sphinx team'
version = sphinx.__released__
release = version
show_authors = True
@ -36,9 +36,9 @@ epub_author = 'Georg Brandl'
epub_publisher = 'http://sphinx-doc.org/'
epub_scheme = 'url'
epub_identifier = epub_publisher
epub_pre_files = [('index.html', 'Welcome')]
epub_post_files = [('install.html', 'Installing Sphinx'),
('develop.html', 'Sphinx development')]
epub_pre_files = [('index.xhtml', 'Welcome')]
epub_post_files = [('install.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',
@ -47,7 +47,8 @@ epub_fix_images = False
epub_max_image_width = 0
epub_show_urls = 'inline'
epub_use_index = False
epub_guide = (('toc', 'contents.html', u'Table of Contents'),)
epub_guide = (('toc', 'contents.xhtml', u'Table of Contents'),)
epub3_description = 'Sphinx documentation generator system manual'
latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
'Georg Brandl', 'manual', 1)]

344
doc/config.rst
View File

@ -56,7 +56,7 @@ General configuration
.. confval:: extensions
A list of strings that are module names of Sphinx extensions. These can be
A list of strings that are module names of :ref:`extensions`. These can be
extensions coming with Sphinx (named ``sphinx.ext.*``) or custom ones.
Note that you can extend :data:`sys.path` within the conf file if your
@ -96,8 +96,11 @@ General configuration
If given, a dictionary of parser classes for different source suffices. The
keys are the suffix, the values can be either a class or a string giving a
fully-qualified name of a parser class. Files with a suffix that is not in
the dictionary will be parsed with the default reStructuredText parser.
fully-qualified name of a parser class. The parser class can be either
``docutils.parsers.Parser`` or :class:`sphinx.parsers.Parser`. Files with a
suffix that is not in the dictionary will be parsed with the default
reStructuredText parser.
For example::
@ -128,7 +131,7 @@ General configuration
:confval:`exclude_dirnames`)
:confval:`exclude_patterns` is also consulted when looking for static files
in :confval:`html_static_path`.
in :confval:`html_static_path` and :confval:`html_extra_path`.
.. versionadded:: 1.0
@ -209,6 +212,33 @@ General configuration
.. versionadded:: 0.5
.. confval:: suppress_warnings
A list of warning types to suppress arbitrary warning messages.
Sphinx supports following warning types:
* app.add_node
* app.add_directive
* app.add_role
* app.add_generic_role
* app.add_source_parser
* image.data_uri
* image.nonlocal_uri
* ref.term
* ref.ref
* ref.numref
* ref.keyword
* ref.option
* ref.citation
* ref.doc
You can choose from these types.
Now, this option should be considered *experimental*.
.. versionadded:: 1.4
.. confval:: needs_sphinx
If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
@ -217,6 +247,9 @@ General configuration
.. versionadded:: 1.0
.. versionchanged:: 1.4
also accepts micro version string
.. confval:: needs_extensions
This value can be a dictionary specifying version requirements for extensions
@ -234,7 +267,7 @@ General configuration
If true, Sphinx will warn about *all* references where the target cannot be
found. Default is ``False``. You can activate this mode temporarily using
the :option:`-n` command-line switch.
the :option:`-n <sphinx-build -n>` command-line switch.
.. versionadded:: 1.0
@ -250,7 +283,12 @@ General configuration
.. confval:: numfig
If true, figures, tables and code-blocks are automatically numbered if they
has caption. For now, it works only with the HTML builder. Default is ``False``.
have a caption. At same time, the `numref` role is enabled. For now, it
works only with the HTML builder and LaTeX builder. Default is ``False``.
.. note::
LaTeX builder always assign numbers whether this option is enabled or not.
.. versionadded:: 1.3
@ -309,16 +347,35 @@ Project information
The default is no :confval:`today` and a :confval:`today_fmt` of ``'%B %d,
%Y'`` (or, if translation is enabled with :confval:`language`, an equivalent
%format for the selected locale).
format for the selected locale).
.. versionchanged:: 1.4
Format specification was changed from strftime to Locale Data Markup
Language. strftime format is also supported for backward compatibility
until Sphinx-1.5.
.. versionchanged:: 1.4.1
Format specification was changed again from Locale Data Markup Language
to strftime. LDML format is also supported for backward compatibility
until Sphinx-1.5.
.. confval:: highlight_language
The default language to highlight source code in. The default is
``'python'``. The value should be a valid Pygments lexer name, see
``'python3'``. The value should be a valid Pygments lexer name, see
:ref:`code-examples` for more details.
.. versionadded:: 0.5
.. versionchanged:: 1.4
The default is now ``'default'``. It is similar to ``'python3'``;
it is mostly a superset of ``'python'``. but it fallbacks to
``'none'`` without warning if failed. ``'python3'`` and other
languages will emit warning if failed. If you prefer Python 2
only highlighting, you can set it back to ``'python'``.
.. confval:: highlight_options
A dictionary of options that modify how the lexer specified by
@ -397,12 +454,18 @@ documentation on :ref:`intl` for details.
The code for the language the docs are written in. Any text automatically
generated by Sphinx will be in that language. Also, Sphinx will try to
substitute individual paragraphs from your documents with the translation
sets obtained from :confval:`locale_dirs`. In the LaTeX builder, a suitable
language will be selected as an option for the *Babel* package. Default is
``None``, which means that no translation will be done.
sets obtained from :confval:`locale_dirs`. Sphinx will search
language-specific figures named by `figure_language_filename` and substitute
them for original figures. In the LaTeX builder, a suitable language will
be selected as an option for the *Babel* package. Default is ``None``,
which means that no translation will be done.
.. versionadded:: 0.5
.. versionchanged:: 1.4
Support figure substitution
Currently supported languages by Sphinx are:
* ``bn`` -- Bengali
@ -453,12 +516,15 @@ documentation on :ref:`intl` for details.
this path are searched by the standard :mod:`gettext` module.
Internal messages are fetched from a text domain of ``sphinx``; so if you
add the directory :file:`./locale` to this settting, the message catalogs
add the directory :file:`./locale` to this setting, the message catalogs
(compiled from ``.po`` format using :program:`msgfmt`) must be in
:file:`./locale/{language}/LC_MESSAGES/sphinx.mo`. The text domain of
individual documents depends on :confval:`gettext_compact`.
The default is ``[]``.
The default is ``['locales']``.
.. versionchanged:: 1.5
Use ``locales`` directory as a default value
.. confval:: gettext_compact
@ -521,6 +587,14 @@ documentation on :ref:`intl` for details.
.. versionadded:: 1.3
.. confval:: figure_language_filename
The filename format for language-specific figures. The default value is
``{root}.{language}{ext}``. It will be expanded to
``dirname/filename.en.png`` from ``.. image:: dirname/filename.png``.
.. versionadded:: 1.4
.. _html-options:
Options for HTML output
@ -565,8 +639,7 @@ that use Sphinx's HTMLWriter class.
The "title" for HTML documentation generated with Sphinx's own templates.
This is appended to the ``<title>`` tag of individual pages, and used in the
navigation bar as the "topmost" element. It defaults to :samp:`'{<project>}
v{<revision>} documentation'` (with the values coming from the config
values).
v{<revision>} documentation'`.
.. confval:: html_short_title
@ -580,7 +653,7 @@ that use Sphinx's HTMLWriter class.
A dictionary of values to pass into the template engine's context for all
pages. Single values can also be put in this dictionary using the
:option:`-A` command-line option of ``sphinx-build``.
:option:`-A <sphinx-build -A>` command-line option of ``sphinx-build``.
.. versionadded:: 0.5
@ -635,11 +708,30 @@ that use Sphinx's HTMLWriter class.
.. versionadded:: 1.2
.. versionchanged:: 1.4
The dotfiles in the extra directory will be copied to the output directory.
And it refers :confval:`exclude_patterns` on copying extra files and
directories, and ignores if path matches to patterns.
.. confval:: html_last_updated_fmt
If this is not the empty string, a 'Last updated on:' timestamp is inserted
at every page bottom, using the given :func:`strftime` format. Default is
``'%b %d, %Y'`` (or a locale-dependent equivalent).
If this is not None, a 'Last updated on:' timestamp is inserted
at every page bottom, using the given :func:`strftime` format.
The empty string is equivalent to ``'%b %d, %Y'`` (or a
locale-dependent equivalent).
.. versionchanged:: 1.4
Format specification was changed from strftime to Locale Data Markup
Language. strftime format is also supported for backward compatibility
until Sphinx-1.5.
.. versionchanged:: 1.4.1
Format specification was changed again from Locale Data Markup Language
to strftime. LDML format is also supported for backward compatibility
until Sphinx-1.5.
.. confval:: html_use_smartypants
@ -778,9 +870,16 @@ that use Sphinx's HTMLWriter class.
.. versionadded:: 0.6
.. confval:: html_sourcelink_suffix
Suffix to be appended to source links (see :confval:`html_show_sourcelink`),
unless they have this suffix already. Default is ``'.txt'``.
.. versionadded:: 1.5
.. confval:: html_use_opensearch
If nonempty, an `OpenSearch <http://opensearch.org>`_ description file will be
If nonempty, an `OpenSearch <http://www.opensearch.org/Home>`_ description file will be
output, and all pages will contain a ``<link>`` tag referring to it. Since
OpenSearch doesn't support relative URLs for its search page location, the
value of this option must be the base URL from which these documents are
@ -867,12 +966,13 @@ that use Sphinx's HTMLWriter class.
* ``it`` -- Italian
* ``ja`` -- Japanese
* ``no`` -- Norwegian
* ``pr`` -- Portuguese
* ``pt`` -- Portuguese
* ``ro`` -- Romanian
* ``ru`` -- Russian
* ``es`` -- Spanish
* ``sv`` -- Swedish
* ``tr`` -- Turkish
* ``zh`` -- Chinese
.. admonition:: Accelerating build speed
@ -898,15 +998,65 @@ that use Sphinx's HTMLWriter class.
The Japanese support has these options:
* ``type`` -- ``'mecab'`` or ``'default'`` (selects either MeCab or
TinySegmenter word splitter algorithm)
* ``dic_enc`` -- the encoding for the MeCab algorithm
* ``dict`` -- the dictionary to use for the MeCab algorithm
* ``lib`` -- the library name for finding the MeCab library via ctypes if the
Python binding is not installed
:type:
_`type` is dotted module path string to specify Splitter implementation which
should be derived from :class:`sphinx.search.ja.BaseSplitter`.
If not specified or None is specified, ``'sphinx.search.ja.DefaultSplitter'`` will
be used.
You can choose from these modules:
:'sphinx.search.ja.DefaultSplitter':
TinySegmenter algorithm. This is default splitter.
:'sphinx.search.ja.MeCabSplitter':
MeCab binding. To use this splitter, 'mecab' python binding or dynamic link
library ('libmecab.so' for linux, 'libmecab.dll' for windows) is required.
:'sphinx.search.ja.JanomeSplitter':
Janome binding. To use this splitter,
`Janome <https://pypi.python.org/pypi/Janome>`_ is required.
To keep compatibility, ``'mecab'``, ``'janome'`` and ``'default'`` are also
acceptable. However it will be deprecated in Sphinx-1.6.
Other option values depend on splitter value which you choose.
Options for ``'mecab'``:
:dic_enc:
_`dic_enc option` is the encoding for the MeCab algorithm.
:dict:
_`dict option` is the dictionary to use for the MeCab algorithm.
:lib:
_`lib option` is the library name for finding the MeCab library via ctypes if
the Python binding is not installed.
For example::
html_search_options = {
'type': 'mecab',
'dic_enc': 'utf-8',
'dict': '/path/to/mecab.dic',
'lib': '/path/to/libmecab.so',
}
Options for ``'janome'``:
:user_dic: _`user_dic option` is the user dictionary file path for Janome.
:user_dic_enc:
_`user_dic_enc option` is the encoding for the user dictionary file specified by
``user_dic`` option. Default is 'utf8'.
.. versionadded:: 1.1
.. versionchanged:: 1.4
html_search_options for Japanese is re-organized and any custom splitter can be
used by `type`_ settings.
The Chinese support has these options:
* ``dict`` -- the ``jieba`` dictionary path if want to use
custom dictionary.
.. confval:: html_search_scorer
The name of a JavaScript file (relative to the configuration directory) that
@ -1127,11 +1277,25 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
The title of the document. It defaults to the :confval:`html_title` option
but can be set independently for epub creation.
.. confval:: epub3_description
The description of the document. The default value is ``''``.
.. versionadded:: 1.4
.. confval:: epub_author
The author of the document. This is put in the Dublin Core metadata. The
default value is ``'unknown'``.
.. confval:: epub3_contributor
The name of a person, organization, etc. that played a secondary role in
the creation of the content of an EPUB Publication. The default value is
``'unknown'``.
.. versionadded:: 1.4
.. confval:: epub_language
The language of the document. This is put in the Dublin Core metadata. The
@ -1234,6 +1398,10 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
a chapter, but can be confusing because it mixes entries of different
depth in one list. The default value is ``True``.
.. note::
``epub3`` builder ignores ``epub_tocdup`` option(always ``False``)
.. confval:: epub_tocscope
This setting control the scope of the epub table of contents. The setting
@ -1287,12 +1455,33 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
.. versionadded:: 1.2
.. confval:: epub3_page_progression_direction
The global direction in which the content flows.
Allowed values are ``'ltr'`` (left-to-right), ``'rtl'`` (right-to-left) and
``'default'``. The default value is ``'ltr'``.
When the ``'default'`` value is specified, the Author is expressing no
preference and the Reading System may chose the rendering direction.
.. versionadded:: 1.4
.. _latex-options:
Options for LaTeX output
------------------------
These options influence LaTeX output.
These options influence LaTeX output. See further :doc:`latex`.
.. confval:: latex_engine
The LaTeX engine to build the docs. The setting can have the following
values:
* pdflatex -- PDFLaTeX (default)
* xelatex -- XeLaTeX
* lualatex -- LuaLaTeX
* platex -- pLaTeX (default if `language` is 'ja')
.. confval:: latex_documents
@ -1337,6 +1526,15 @@ These options influence LaTeX output.
configuration directory) that is the logo of the docs. It is placed at the
top of the title page. Default: ``None``.
.. confval:: latex_toplevel_sectioning
This value determines the topmost sectioning unit. It should be chosen from
``part``, ``chapter`` or ``section``. The default is ``None``; the topmost
sectioning unit is switched by documentclass. ``section`` is used if
documentclass will be ``howto``, otherwise ``chapter`` will be used.
.. versionadded:: 1.4
.. confval:: latex_use_parts
If true, the topmost sectioning unit is parts, else it is chapters. Default:
@ -1344,6 +1542,9 @@ These options influence LaTeX output.
.. versionadded:: 0.3
.. deprecated:: 1.4
Use :confval:`latex_toplevel_sectioning`.
.. confval:: latex_appendices
A list of document names to append as an appendix to all manuals.
@ -1388,6 +1589,21 @@ These options influence LaTeX output.
value selected the ``'inline'`` display. For backwards compatibility,
``True`` is still accepted.
.. confval:: latex_keep_old_macro_names
If ``True`` (default) the ``\strong``, ``\code``, ``\bfcode``, ``\email``,
``\tablecontinued``, ``\titleref``, ``\menuselection``, ``\accelerator``,
``\crossref``, ``\termref``, and ``\optional`` text styling macros are
pre-defined by Sphinx and may be user-customized by some
``\renewcommand``'s inserted either via ``'preamble'`` key or :dudir:`raw
<raw-data-pass-through>` directive. If ``False``, only ``\sphinxstrong``,
etc... macros are defined (and may be redefined by user). Setting to
``False`` may help solve macro name conflicts caused by user-added latex
packages.
.. versionadded:: 1.4.5
.. confval:: latex_elements
.. versionadded:: 0.5
@ -1406,6 +1622,15 @@ These options influence LaTeX output.
``'pointsize'``
Point size option of the document class (``'10pt'``, ``'11pt'`` or
``'12pt'``), default ``'10pt'``.
``'pxunit'``
the value of the ``px`` when used in image attributes ``width`` and
``height``. The default value is ``'49336sp'`` which achieves
``96px=1in`` (``1in = 72.27*65536 = 4736286.72sp``, and all dimensions
in TeX are internally integer multiples of ``sp``). To obtain for
example ``100px=1in``, one can use ``'0.01in'`` but it is more precise
to use ``'47363sp'``. To obtain ``72px=1in``, use ``'1bp'``.
.. versionadded:: 1.5
``'babel'``
"babel" package inclusion, default ``'\\usepackage{babel}'``.
``'fontpkg'``
@ -1423,22 +1648,33 @@ These options influence LaTeX output.
the "Bjarne" style uses numbers spelled out in English). Other
"fncychap" styles you can try include "Lenny", "Glenn", "Conny" and
"Rejne". You can also set this to ``''`` to disable fncychap.
``'passoptionstopackages'``
"PassOptionsToPackage" call, default empty.
.. versionadded:: 1.4
``'preamble'``
Additional preamble content, default empty.
Additional preamble content, default empty. See :doc:`latex`.
``'figure_align'``
Latex figure float alignment, default 'htbp' (here, top, bottom, page).
Whenever an image doesn't fit into the current page, it will be
'floated' into the next page but may be preceded by any other text.
If you don't like this behavior, use 'H' which will disable floating
and position figures strictly in the order they appear in the source.
.. versionadded:: 1.3
``'footer'``
Additional footer content (before the indices), default empty.
* Keys that don't need be overridden unless in special cases are:
``'inputenc'``
"inputenc" package inclusion, default
``'\\usepackage[utf8]{inputenc}'``.
"inputenc" package inclusion, defaults to
``'\\usepackage[utf8]{inputenc}'`` when using pdflatex.
Otherwise unset.
.. versionchanged:: 1.4.3
Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
compilers.
``'cmappkg'``
"cmap" package inclusion, default ``'\\usepackage{cmap}'``.
@ -1448,6 +1684,9 @@ These options influence LaTeX output.
``'maketitle'``
"maketitle" call, default ``'\\maketitle'``. Override if you want to
generate a differently-styled title page.
``'releasename'``
value that prefixes ``'release'`` element on title page, default
``'Release'``.
``'tableofcontents'``
"tableofcontents" call, default ``'\\tableofcontents'``. Override if
you want to generate a different table of contents or put content
@ -1473,7 +1712,6 @@ These options influence LaTeX output.
``'release'``
``'author'``
``'logo'``
``'releasename'``
``'makeindex'``
``'shorthandoff'``
@ -1485,6 +1723,11 @@ These options influence LaTeX output.
.. versionadded:: 1.0
.. versionchanged:: 1.5
In Japanese docs(`language` is ``ja``), ``'jreport'`` is used for
``'howto'`` and ``'jsbooks'`` is used for ``'manual'`` by default.
.. confval:: latex_additional_files
A list of file names, relative to the configuration directory, to copy to the
@ -1713,6 +1956,13 @@ Options for the linkcheck builder
.. versionadded:: 1.1
.. confval:: linkcheck_retries
The number of times the linkcheck builder will attempt to check a URL before
declaring it broken. Defaults to 1 attempt.
.. versionadded:: 1.4
.. confval:: linkcheck_timeout
A timeout value, in seconds, for the linkcheck builder. **Only works in
@ -1753,3 +2003,33 @@ Options for the XML builder
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.
.. _cpp-config:
Options for the C++ domain
--------------------------
.. confval:: cpp_index_common_prefix
A list of prefixes that will be ignored when sorting C++ objects in the global index.
For example ``['awesome_lib::']``.
.. versionadded:: 1.5
.. confval:: cpp_id_attributes
A list of strings that the parser additionally should accept as attributes.
This can for example be used when attributes have been ``#define`` d for portability.
.. versionadded:: 1.5
.. confval:: cpp_paren_attributes
A list of strings that the parser additionally should accept as attributes with one argument.
That is, if ``my_align_as`` is in the list, then ``my_align_as(X)`` is parsed as an attribute
for all strings ``X`` that have balanced brances (``()``, ``[]``, and ``{}``).
This can for example be used when attributes have been ``#define`` d for portability.
.. versionadded:: 1.5

2
doc/contents.rst
View File

@ -1,3 +1,4 @@
.. _contents:
Sphinx documentation contents
@ -17,6 +18,7 @@ Sphinx documentation contents
intl
theming
templating
latex
extensions
extdev/index
websupport

26
doc/develop.rst
View File

@ -10,7 +10,7 @@ Sphinx is a maintained by a group of volunteers. We value every contribution!
* Issues and feature requests should be raised in the `tracker
<https://github.com/sphinx-doc/sphinx/issues>`_.
* The mailing list for development is at `Google Groups
<https://groups.google.com/group/sphinx-dev/>`_.
<https://groups.google.com/forum/#!forum/sphinx-dev>`_.
* There is also the #sphinx-doc IRC channel on `freenode
<http://freenode.net/>`_.
@ -21,7 +21,7 @@ Extensions
To learn how to write your own extension, see :ref:`dev-extensions`.
The `sphinx-contrib <http://bitbucket.org/birkenfeld/sphinx-contrib/>`_
The `sphinx-contrib <https://bitbucket.org/birkenfeld/sphinx-contrib/>`_
repository contains many contributed extensions. Some of them have their own
releases on PyPI, others you can install from a checkout.
@ -96,14 +96,14 @@ own extensions.
.. _aafigure: https://launchpad.net/aafigure
.. _gnuplot: http://www.gnuplot.info/
.. _paver: http://www.blueskyonmars.com/projects/paver/
.. _paver: http://paver.github.io/paver/
.. _Sword: http://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/
.. _PlantUML: http://plantuml.sourceforge.net/
.. _PlantUML: http://plantuml.com/
.. _PyEnchant: http://www.rfk.id.au/software/pyenchant/
.. _sadisplay: https://bitbucket.org/estin/sadisplay/wiki/Home
.. _blockdiag: http://blockdiag.com/en/
@ -112,24 +112,24 @@ own extensions.
.. _nwdiag: http://blockdiag.com/en/
.. _Google Analytics: http://www.google.com/analytics/
.. _Google Chart: https://developers.google.com/chart/
.. _Google Maps: https://maps.google.com/
.. _Google Maps: https://www.google.com/maps
.. _Google style: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
.. _NumPy style: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
.. _hyphenator: http://code.google.com/p/hyphenator/
.. _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/
.. _TikZ/PGF LaTeX package: http://sourceforge.net/projects/pgf/
.. _TikZ/PGF LaTeX package: https://sourceforge.net/projects/pgf/
.. _MATLAB: http://www.mathworks.com/products/matlab/
.. _swf: http://bitbucket.org/klorenz/sphinxcontrib-swf
.. _findanything: http://bitbucket.org/klorenz/sphinxcontrib-findanything
.. _cmakedomain: http://bitbucket.org/klorenz/sphinxcontrib-cmakedomain
.. _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/
.. _makedomain: http://bitbucket.org/klorenz/sphinxcontrib-makedomain
.. _makedomain: https://bitbucket.org/klorenz/sphinxcontrib-makedomain
.. _inlinesyntaxhighlight: http://sphinxcontrib-inlinesyntaxhighlight.readthedocs.org
.. _CMake: http://cmake.org
.. _domaintools: http://bitbucket.org/klorenz/sphinxcontrib-domaintools
.. _CMake: https://cmake.org
.. _domaintools: https://bitbucket.org/klorenz/sphinxcontrib-domaintools
.. _restbuilder: https://pypi.python.org/pypi/sphinxcontrib-restbuilder
.. _Lasso: http://www.lassosoft.com/

2
doc/devguide.rst
View File

@ -111,7 +111,7 @@ These are the basic steps needed to start developing on Sphinx.
* Run the unit tests::
pip install nose mock
pip install -r test-reqs.txt
make test
* Build the documentation and check the output for different builders::

410
doc/domains.rst
View File

@ -359,6 +359,18 @@ single word, like this::
:param int priority: The priority of the message, can be a number 1-5
.. versionadded:: 1.5
Container types such as lists and dictionaries can be linked automatically
using the following syntax::
:type priorities: list(int)
:type priorities: list[int]
:type mapping: dict(str, int)
:type mapping: dict[str, int]
:type point: tuple(float, float)
:type point: tuple[float, float]
.. _python-roles:
Cross-referencing Python objects
@ -528,60 +540,128 @@ a visibility statement (``public``, ``private`` or ``protected``).
Describe a class/struct, possibly with specification of inheritance, e.g.,::
.. cpp:class:: SomeName::SomeClass : public MyBase, MyOtherBase
.. cpp:class:: MyClass : public MyBase, MyOtherBase
.. rst:directive:: .. cpp:function:: (member-)function prototype
The class can be directly declared inside a nested scope, e.g.,::
.. cpp:class:: OuterScope::MyClass : public MyBase, MyOtherBase
A template class can be declared::
.. cpp:class:: template<typename T, std::size_t N> std::array
or with a line break::
.. cpp:class:: template<typename T, std::size_t N> \
std::array
Full and partial template specialisations can be declared::
.. cpp:class:: template<> \
std::array<bool, 256>
.. cpp:class:: template<typename T> \
std::array<T, 42>
.. rst:directive:: .. cpp:function:: (member) function prototype
Describe a function or member function, e.g.,::
.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)
.. cpp:function:: bool myMethod(int arg1, std::string arg2)
Describes a method with parameters and types.
A function with parameters and types.
.. cpp:function:: bool namespaced::theclass::method(T1, T2)
.. cpp:function:: bool myMethod(int, double)
Describes a method with unnamed parameters.
A function with unnamed parameters.
.. cpp:function:: const T &array<T>::operator[]() const
.. cpp:function:: const T &MyClass::operator[](std::size_t i) const
Describes the constant indexing operator of a templated array.
An overload for the indexing operator.
.. cpp:function:: operator bool() const
Describe a casting operator here.
A casting operator.
.. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
Describe a constexpr function here.
A constexpr function.
.. cpp:function:: MyClass::MyClass(const MyClass&) = default
Describe a copy constructor with default implementation.
A copy constructor with default implementation.
.. rst:directive:: .. cpp:member:: (member-)variable declaration
.. cpp:var:: (member-)variable declaration
Function templates can also be described::
Describe a varible or member variable, e.g.,::
.. cpp:function:: template<typename U> \
void print(U &&u)
.. cpp:member:: std::string theclass::name
and function template specialisations::
.. cpp:member:: std::string theclass::name[N][M]
.. cpp:function:: template<> \
void print(int i)
.. rst:directive:: .. cpp:member:: (member) variable declaration
.. cpp:var:: (member) variable declaration
Describe a variable or member variable, e.g.,::
.. cpp:member:: std::string MyClass::myMember
.. cpp:var:: std::string MyClass::myOtherMember[N][M]
.. cpp:member:: int a = 42
.. rst:directive:: .. cpp:type:: typedef-like declaration
.. cpp:type:: name
Variable templates can also be described::
Describe a type as in a typedef declaration, or the name of a type with unspecified type, e.g.,::
.. cpp:member:: template<class T> \
constexpr T pi = T(3.1415926535897932385)
.. rst:directive:: .. cpp:type:: typedef declaration
.. cpp:type:: name
.. cpp:type:: type alias declaration
Describe a type as in a typedef declaration, a type alias declaration,
or simply the name of a type with unspecified type, e.g.,::
.. cpp:type:: std::vector<int> MyList
A typedef-like declaration of a type.
.. cpp:type:: theclass::const_iterator
.. cpp:type:: MyContainer::const_iterator
Declaration of a type alias with unspecified type.
.. cpp:type:: MyType = std::unordered_map<int, std::string>
Declaration of a type alias.
A type alias can also be templated::
.. cpp:type:: template<typename T> \
MyContainer = std::vector<T>
The example are rendered as follows.
.. cpp:type:: std::vector<int> MyList
A typedef-like declaration of a type.
.. cpp:type:: MyContainer::const_iterator
Declaration of a type alias with unspecified type.
.. cpp:type:: MyType = std::unordered_map<int, std::string>
Declaration of a type alias.
.. cpp:type:: template<typename T> \
MyContainer = std::vector<T>
.. rst:directive:: .. cpp:enum:: unscoped enum declaration
.. cpp:enum-struct:: scoped enum declaration
.. cpp:enum-class:: scoped enum declaration
@ -610,25 +690,194 @@ a visibility statement (``public``, ``private`` or ``protected``).
.. rst:directive:: .. cpp:enumerator:: name
.. cpp:enumerator:: name = constant
Describe an enumerator, optionally with its value defined.
Describe an enumerator, optionally with its value defined, e.g.,::
.. rst:directive:: .. cpp:namespace:: namespace
.. cpp:enumerator:: MyEnum::myEnumerator
Select the current namespace for the subsequent objects. Note that the namespace
does not need to correspond to C++ namespaces, but can end in names of classes, e.g.,::
.. cpp:enumerator:: MyEnum::myOtherEnumerator = 42
.. rst:directive:: .. cpp:concept:: template-parameter-list name
.. cpp:concept:: template-parameter-list name()
.. warning:: The support for concepts is experimental. It is based on the
Concepts Technical Specification, and the features may change as the TS evolves.
Describe a variable concept or a function concept. Both must have exactly 1
template parameter list. The name may be a nested name. Examples::
.. cpp:concept:: template<typename It> std::Iterator
Proxy to an element of a notional sequence that can be compared,
indirected, or incremented.
.. cpp:concept:: template<typename Cont> std::Container()
Holder of elements, to which it can provide access via
:cpp:concept:`Iterator` s.
They will render as follows:
.. cpp:concept:: template<typename It> std::Iterator
Proxy to an element of a notional sequence that can be compared,
indirected, or incremented.
.. cpp:concept:: template<typename Cont> std::Container()
Holder of elements, to which it can provide access via
:cpp:concept:`Iterator` s.
Constrained Templates
~~~~~~~~~~~~~~~~~~~~~
.. warning:: The support for constrained templates is experimental. It is based on the
Concepts Technical Specification, and the features may change as the TS evolves.
.. note:: Sphinx does not currently support ``requires`` clauses.
Placeholders
............
Declarations may use the name of a concept to introduce constrained template
parameters, or the keyword ``auto`` to introduce unconstrained template parameters::
.. cpp:function:: void f(auto &&arg)
A function template with a single unconstrained template parameter.
.. cpp:function:: void f(std::Iterator it)
A function template with a single template parameter, constrained by the
Iterator concept.
Template Introductions
......................
Simple constrained function or class templates can be declared with a
`template introduction` instead of a template parameter list::
.. cpp:function:: std::Iterator{It} void advance(It &it)
A function template with a template parameter constrained to be an Iterator.
.. cpp:class:: std::LessThanComparable{T} MySortedContainer
A class template with a template parameter constrained to be LessThanComparable.
They are rendered as follows.
.. cpp:function:: std::Iterator{It} void advance(It &it)
A function template with a template parameter constrained to be an Iterator.
.. cpp:class:: std::LessThanComparable{T} MySortedContainer
A class template with a template parameter constrained to be LessThanComparable.
Note however that no checking is performed with respect to parameter
compatibility. E.g., ``Iterator{A, B, C}`` will be accepted as an introduction
even though it would not be valid C++.
Namespacing
~~~~~~~~~~~~~~~~~
Declarations in the C++ domain are as default placed in global scope.
The current scope can be changed using three namespace directives.
They manage a stack declarations where ``cpp:namespace`` resets the stack and
changes a given scope.
The ``cpp:namespace-push`` directive changes the scope to a given inner scope
of the current one.
The ``cpp:namespace-pop`` directive undos the most recent ``cpp:namespace-push``
directive.
.. rst:directive:: .. cpp:namespace:: scope specification
Changes the current scope for the subsequent objects to the given scope,
and resets the namespace directive stack.
Note that the namespace does not need to correspond to C++ namespaces,
but can end in names of classes, e.g.,::
.. cpp:namespace:: Namespace1::Namespace2::SomeClass::AnInnerClass
All subsequent objects will be defined as if their name were declared with the namespace
prepended. The subsequent cross-references will be searched for by both their specified name
and with the namespace prepended.
All subsequent objects will be defined as if their name were declared with the scope
prepended. The subsequent cross-references will be searched for starting in the current scope.
Using ``NULL``, ``0``, or ``nullptr`` as the namespace will reset it to the global namespace.
Using ``NULL``, ``0``, or ``nullptr`` as the scope will change to global scope.
A namespace declaration can also be templated, e.g.,::
.. cpp:class:: template<typename T> \
std::vector
.. cpp:namespace:: template<typename T> std::vector
.. cpp:function:: std::size_t size() const
declares ``size`` as a member function of the template class ``std::vector``.
Equivalently this could have been declared using::
.. cpp:class:: template<typename T> \
std::vector
.. cpp:function:: std::size_t size() const
or:::
.. cpp:class:: template<typename T> \
std::vector
.. rst:directive:: .. cpp:namespace-push:: scope specification
Change the scope relatively to the current scope. For example, after::
.. cpp:namespace:: A::B
.. cpp:namespace-push:: C::D
the current scope will be ``A::B::C::D``.
.. rst:directive:: .. cpp:namespace-pop::
Undo the previous ``cpp:namespace-push`` directive (*not* just pop a scope).
For example, after::
.. cpp:namespace:: A::B
.. cpp:namespace-push:: C::D
.. cpp:namespace-pop::
the current scope will be ``A::B`` (*not* ``A::B::C``).
If no previous ``cpp:namespace-push`` directive has been used, but only a ``cpp:namespace``
directive, then the current scope will be reset to global scope.
That is, ``.. cpp:namespace:: A::B`` is equivalent to::
.. cpp:namespace:: nullptr
.. cpp:namespace-push:: A::B
Info field lists
~~~~~~~~~~~~~~~~~
The C++ directives support the following info fields (see also :ref:`info-field-lists`):
* `param`, `parameter`, `arg`, `argument`: Description of a parameter.
* `tparam`: Description of a template parameter.
* `returns`, `return`: Description of a return value.
* `throws`, `throw`, `exception`: Description of a possibly thrown exception.
.. _cpp-roles:
These roles link to the given object types:
Cross-referencing
~~~~~~~~~~~~~~~~~
These roles link to the given declaration types:
.. rst:role:: cpp:any
cpp:class
@ -636,22 +885,23 @@ These roles link to the given object types:
cpp:member
cpp:var
cpp:type
cpp:concept
cpp:enum
cpp:enumerator
Reference a C++ object by name. The name must be properly qualified relative to the
position of the link.
Reference a C++ declaration by name (see below for details).
The name must be properly qualified relative to the position of the link.
.. note::
.. admonition:: Note on References with Templates Parameters/Arguments
Sphinx's syntax to give references a custom title can interfere with
linking to template classes, if nothing follows the closing angle
bracket, i.e. if the link looks like this: ``:cpp:class:`MyClass<T>```.
This is interpreted as a link to ``T`` with a title of ``MyClass``.
bracket, i.e. if the link looks like this: ``:cpp:class:`MyClass<int>```.
This is interpreted as a link to ``int`` with a title of ``MyClass``.
In this case, please escape the opening angle bracket with a backslash,
like this: ``:cpp:class:`MyClass\<T>```.
like this: ``:cpp:class:`MyClass\<int>```.
.. admonition:: Note on References
.. admonition:: Note on References to Overloaded Functions
It is currently impossible to link to a specific version of an
overloaded method. Currently the C++ domain is the first domain
@ -660,11 +910,84 @@ These roles link to the given object types:
specific overload. Currently Sphinx will link to the first overloaded
version of the method / function.
.. admonition:: Note on Template Delcarations
Declarations without template parameters and template arguments
.................................................................
The C++ domain currently does not support template classes/functions/aliases/variables
(e.g., ``template<typename T> MyClass``), only template instantiations
(e.g., ``MyClass<T>``).
For linking to non-templated declarations the name must be a nested name,
e.g., ``f`` or ``MyClass::f``.
Templated declarations
......................
Assume the following declarations.
.. cpp:class:: Wrapper
.. cpp:class:: template<typename TOuter> \
Outer
.. cpp:class:: template<typename TInner> \
Inner
In general the reference must include the template paraemter declarations, e.g.,
``template\<typename TOuter> Wrapper::Outer`` (:cpp:class:`template\<typename TOuter> Wrapper::Outer`).
Currently the lookup only succeed if the template parameter identifiers are equal strings. That is,
``template\<typename UOuter> Wrapper::Outer`` will not work.
The inner template class can not be directly referenced, unless the current namespace
is changed or the following shorthand is used.
If a template parameter list is omitted, then the lookup will assume either a template or a non-template,
but not a partial template specialisation.
This means the following references work.
- ``Wrapper::Outer`` (:cpp:class:`Wrapper::Outer`)
- ``Wrapper::Outer::Inner`` (:cpp:class:`Wrapper::Outer::Inner`)
- ``template\<typename TInner> Wrapper::Outer::Inner`` (:cpp:class:`template\<typename TInner> Wrapper::Outer::Inner`)
(Full) Template Specialisations
................................
Assume the following declarations.
.. cpp:class:: template<typename TOuter> \
Outer
.. cpp:class:: template<typename TInner> \
Inner
.. cpp:class:: template<> \
Outer<int>
.. cpp:class:: template<typename TInner> \
Inner
.. cpp:class:: template<> \
Inner<bool>
In general the reference must include a template parameter list for each template argument list.
The full specialisation above can therefore be referenced with ``template\<> Outer\<int>`` (:cpp:class:`template\<> Outer\<int>`)
and ``template\<> template\<> Outer\<int>::Inner\<bool>`` (:cpp:class:`template\<> template\<> Outer\<int>::Inner\<bool>`).
As a shorthand the empty template parameter list can be omitted, e.g., ``Outer\<int>`` (:cpp:class:`Outer\<int>`)
and ``Outer\<int>::Inner\<bool>`` (:cpp:class:`Outer\<int>::Inner\<bool>`).
Partial Template Specialisations
.................................
Assume the following declaration.
.. cpp:class:: template<typename T> \
Outer<T*>
References to partial specialisations must always include the template parameter lists, e.g.,
``template\<typename T> Outer\<T*>`` (:cpp:class:`template\<typename T> Outer\<T*>`).
Currently the lookup only succeed if the template parameter identifiers are equal strings.
Configuration Variables
~~~~~~~~~~~~~~~~~~~~~~~
See :ref:`cpp-config`.
The Standard Domain
@ -696,6 +1019,8 @@ There is a set of directives allowing documenting command-line programs:
referencable by :rst:role:`option` (in the example case, you'd use something
like ``:option:`dest_dir```, ``:option:`-m```, or ``:option:`--module```).
``cmdoption`` directive is a deprecated alias for the ``option`` directive.
.. rst:directive:: .. envvar:: name
Describes an environment variable that the documented code or program uses or
@ -875,13 +1200,14 @@ More domains
The sphinx-contrib_ repository contains more domains available as extensions;
currently Ada_, CoffeeScript_, Erlang_, HTTP_, Lasso_, MATLAB_, PHP_, and Ruby_
domains. Also available are domains for `Common Lisp`_, dqn_, Go_, Jinja_,
Operation_, and Scala_.
domains. Also available are domains for `Chapel`_, `Common Lisp`_, dqn_, Go_,
Jinja_, Operation_, and Scala_.
.. _sphinx-contrib: https://bitbucket.org/birkenfeld/sphinx-contrib/
.. _Ada: https://pypi.python.org/pypi/sphinxcontrib-adadomain
.. _Chapel: https://pypi.python.org/pypi/sphinxcontrib-chapeldomain
.. _CoffeeScript: https://pypi.python.org/pypi/sphinxcontrib-coffee
.. _Common Lisp: https://pypi.python.org/pypi/sphinxcontrib-cldomain
.. _dqn: https://pypi.python.org/pypi/sphinxcontrib-dqndomain

8
doc/ext/autodoc.rst
View File

@ -41,7 +41,7 @@ you can also enable the :mod:`napoleon <sphinx.ext.napoleon>` extension.
docstrings to correct reStructuredText before :mod:`autodoc` processes them.
.. _Google:
http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments
https://google.github.io/styleguide/pyguide.html#Comments
.. _NumPy:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
@ -314,6 +314,12 @@ There are also new config values that you can set:
.. versionadded:: 0.3
If the class has no ``__init__`` method or if the ``__init__`` method's
docstring is empty, but the class has a ``__new__`` method's docstring,
it is used instead.
.. versionadded:: 1.4
.. confval:: autodoc_member_order
This value selects if automatically documented members are sorted

25
doc/ext/autosectionlabel.rst Normal file
View File

@ -0,0 +1,25 @@
.. highlight:: rest
:mod:`sphinx.ext.autosectionlabel` -- Allow reference sections using its title
==============================================================================
.. module:: sphinx.ext.autosectionlabel
:synopsis: Allow reference section its title.
.. versionadded:: 1.4
This extension allows you to refer sections its title. This affects to the
reference role (:rst:role:`ref`).
For example::
A Plain Title
-------------
This is the text of the section.
It refers to the section title, see :ref:`A Plain Title`.
Internally, this extension generates the labels for each section. If same
section names are used in whole of document, any one is used for a target.

41
doc/ext/doctest.rst
View File

@ -33,11 +33,14 @@ There are two kinds of test blocks:
* *code-output-style* blocks consist of an ordinary piece of Python code, and
optionally, a piece of output for that code.
The doctest extension provides four directives. The *group* argument is
interpreted as follows: if it is empty, the block is assigned to the group named
``default``. If it is ``*``, the block is assigned to all groups (including the
``default`` group). Otherwise, it must be a comma-separated list of group
names.
Directives
----------
The *group* argument below is interpreted as follows: if it is empty, the block
is assigned to the group named ``default``. If it is ``*``, the block is
assigned to all groups (including the ``default`` group). Otherwise, it must be
a comma-separated list of group names.
.. rst:directive:: .. testsetup:: [group]
@ -56,12 +59,9 @@ names.
.. rst:directive:: .. doctest:: [group]
A doctest-style code block. You can use standard :mod:`doctest` flags for
controlling how actual output is compared with what you give as output. By
default, these options are enabled: ``ELLIPSIS`` (allowing you to put
ellipses in the expected output that match anything in the actual output),
``IGNORE_EXCEPTION_DETAIL`` (not comparing tracebacks),
``DONT_ACCEPT_TRUE_FOR_1`` (by default, doctest accepts "True" in the output
where "1" is given -- this is a relic of pre-Python 2.2 times).
controlling how actual output is compared with what you give as output. The
default set of flags is specified by the :confval:`doctest_default_flags`
configuration variable.
This directive supports two options:
@ -174,7 +174,24 @@ 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!
There are also these config values for customizing the doctest extension:
Configuration
-------------
The doctest extension uses the following configuration values:
.. confval:: doctest_default_flags
By default, these options are enabled:
- ``ELLIPSIS``, allowing you to put ellipses in the expected output that
match anything in the actual output;
- ``IGNORE_EXCEPTION_DETAIL``, causing everything following the leftmost
colon and any module information in the exception name to be ignored;
- ``DONT_ACCEPT_TRUE_FOR_1``, rejecting "True" in the output where "1" is
given -- the default behavior of accepting this substitution is a relic of
pre-Python 2.2 times.
.. versionadded:: 1.5
.. confval:: doctest_path

126
doc/ext/example_google.py
View File

@ -12,11 +12,11 @@ Example:
$ python example_google.py
Section breaks are created by simply resuming unindented text. Section breaks
Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
Attributes:
module_level_variable (int): Module level variables may be documented in
module_level_variable1 (int): Module level variables may be documented in
either the ``Attributes`` section of the module docstring, or in an
inline docstring immediately following the variable.
@ -24,12 +24,56 @@ Attributes:
one convention to document module level variables and be consistent
with it.
Todo:
* For module TODOs
* You have to also use ``sphinx.ext.todo`` extension
.. _Google Python Style Guide:
http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
http://google.github.io/styleguide/pyguide.html
"""
module_level_variable = 12345
module_level_variable1 = 12345
module_level_variable2 = 98765
"""int: Module level variable documented inline.
The docstring may span multiple lines. The type may optionally be specified
on the first line, separated by a colon.
"""
def function_with_types_in_docstring(param1, param2):
"""Example function with types documented in the docstring.
`PEP 484`_ type annotations are supported. If attribute, parameter, and
return types are annotated according to `PEP 484`_, they do not need to be
included in the docstring:
Args:
param1 (int): The first parameter.
param2 (str): The second parameter.
Returns:
bool: The return value. True for success, False otherwise.
.. _PEP 484:
https://www.python.org/dev/peps/pep-0484/
"""
def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
"""Example function with PEP 484 type annotations.
Args:
param1: The first parameter.
param2: The second parameter.
Returns:
The return value. True for success, False otherwise.
"""
def module_level_function(param1, param2=None, *args, **kwargs):
@ -39,22 +83,21 @@ def module_level_function(param1, param2=None, *args, **kwargs):
of each parameter is required. The type and description of each parameter
is optional, but should be included if not obvious.
If the parameter itself is optional, it should be noted by adding
", optional" to the type. If \*args or \*\*kwargs are accepted, they
should be listed as \*args and \*\*kwargs.
If \*args or \*\*kwargs are accepted,
they should be listed as ``*args`` and ``**kwargs``.
The format for a parameter is::
name (type): description
The description may span multiple lines. Following
lines should be indented.
lines should be indented. The "(type)" is optional.
Multiple paragraphs are supported in parameter
descriptions.
Args:
param1 (int): The first parameter.
param2 (str, optional): The second parameter. Defaults to None.
param2 (:obj:`str`, optional): The second parameter. Defaults to None.
Second line of description should be indented.
*args: Variable length argument list.
**kwargs: Arbitrary keyword arguments.
@ -91,16 +134,16 @@ def example_generator(n):
"""Generators have a ``Yields`` section instead of a ``Returns`` section.
Args:
n (int): The upper limit of the range to generate, from 0 to `n` - 1
n (int): The upper limit of the range to generate, from 0 to `n` - 1.
Yields:
int: The next number in the range of 0 to `n` - 1
int: The next number in the range of 0 to `n` - 1.
Examples:
Examples should be written in doctest format, and should illustrate how
to use the function.
>>> print [i for i in example_generator(4)]
>>> print([i for i in example_generator(4)])
[0, 1, 2, 3]
"""
@ -122,14 +165,15 @@ class ExampleError(Exception):
Args:
msg (str): Human readable string describing the exception.
code (int, optional): Error code, defaults to 2.
code (:obj:`int`, optional): Error code.
Attributes:
msg (str): Human readable string describing the exception.
code (int): Exception error code.
"""
def __init__(self, msg, code=2):
def __init__(self, msg, code):
self.msg = msg
self.code = code
@ -137,17 +181,21 @@ class ExampleError(Exception):
class ExampleClass(object):
"""The summary line for a class docstring should fit on one line.
If the class has public attributes, they should be documented here
If the class has public attributes, they may be documented here
in an ``Attributes`` section and follow the same formatting as a
function's ``Args`` section.
function's ``Args`` section. Alternatively, attributes may be documented
inline with the attribute's declaration (see __init__ method below).
Properties created with the ``@property`` decorator should be documented
in the property's getter method.
Attributes:
attr1 (str): Description of `attr1`.
attr2 (list of str): Description of `attr2`.
attr3 (int): Description of `attr3`.
attr2 (:obj:`int`, optional): Description of `attr2`.
"""
def __init__(self, param1, param2, param3=0):
def __init__(self, param1, param2, param3):
"""Example of docstring on the __init__ method.
The __init__ method may be documented in either the class level
@ -161,14 +209,39 @@ class ExampleClass(object):
Args:
param1 (str): Description of `param1`.
param2 (list of str): Description of `param2`. Multiple
param2 (:obj:`int`, optional): Description of `param2`. Multiple
lines are supported.
param3 (int, optional): Description of `param3`, defaults to 0.
param3 (list(str)): Description of `param3`.
"""
self.attr1 = param1
self.attr2 = param2
self.attr3 = param3
self.attr3 = param3 #: Doc comment *inline* with attribute
#: list(str): Doc comment *before* attribute, with type specified
self.attr4 = ['attr4']
self.attr5 = None
"""str: Docstring *after* attribute, with type specified."""
@property
def readonly_property(self):
"""str: Properties should be documented in their getter method."""
return 'readonly_property'
@property
def readwrite_property(self):
"""list(str): Properties with both a getter and setter
should only be documented in their getter method.
If the setter method contains notable behavior, it should be
mentioned here.
"""
return ['readwrite_property']
@readwrite_property.setter
def readwrite_property(self, value):
value
def example_method(self, param1, param2):
"""Class methods are similar to regular functions.
@ -187,16 +260,17 @@ class ExampleClass(object):
return True
def __special__(self):
"""By default special members with docstrings are included.
"""By default special members with docstrings are not included.
Special members are any methods or attributes that start with and
end with a double underscore. Any special member with a docstring
will be included in the output.
will be included in the output, if
``napoleon_include_special_with_doc`` is set to True.
This behavior can be disabled by changing the following setting in
This behavior can be enabled by changing the following setting in
Sphinx's conf.py::
napoleon_include_special_with_doc = False
napoleon_include_special_with_doc = True
"""
pass

2
doc/ext/example_google.rst
View File

@ -9,6 +9,8 @@ Example Google Style Python Docstrings
:ref:`example_numpy`
.. only:: builder_html
Download: :download:`example_google.py <example_google.py>`
.. literalinclude:: example_google.py

142
doc/ext/example_numpy.py
View File

@ -23,12 +23,12 @@ Notes
This is an example of an indented section. It's like any other section,
but the body is indented to help it stand out from surrounding text.
If a section is indented, then a section break is created simply by
If a section is indented, then a section break is created by
resuming unindented text.
Attributes
----------
module_level_variable : int
module_level_variable1 : int
Module level variables may be documented in either the ``Attributes``
section of the module docstring, or in an inline docstring immediately
following the variable.
@ -37,12 +37,66 @@ module_level_variable : int
one convention to document module level variables and be consistent
with it.
.. _NumPy Documentation HOWTO:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
"""
module_level_variable = 12345
module_level_variable1 = 12345
module_level_variable2 = 98765
"""int: Module level variable documented inline.
The docstring may span multiple lines. The type may optionally be specified
on the first line, separated by a colon.
"""
def function_with_types_in_docstring(param1, param2):
"""Example function with types documented in the docstring.
`PEP 484`_ type annotations are supported. If attribute, parameter, and
return types are annotated according to `PEP 484`_, they do not need to be
included in the docstring:
Parameters
----------
param1 : int
The first parameter.
param2 : str
The second parameter.
Returns
-------
bool
True if successful, False otherwise.
.. _PEP 484:
https://www.python.org/dev/peps/pep-0484/
"""
def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
"""Example function with PEP 484 type annotations.
The return type must be duplicated in the docstring to comply
with the NumPy docstring style.
Parameters
----------
param1
The first parameter.
param2
The second parameter.
Returns
-------
bool
True if successful, False otherwise.
"""
def module_level_function(param1, param2=None, *args, **kwargs):
@ -52,9 +106,8 @@ def module_level_function(param1, param2=None, *args, **kwargs):
The name of each parameter is required. The type and description of each
parameter is optional, but should be included if not obvious.
If the parameter itself is optional, it should be noted by adding
", optional" to the type. If \*args or \*\*kwargs are accepted, they
should be listed as \*args and \*\*kwargs.
If \*args or \*\*kwargs are accepted,
they should be listed as ``*args`` and ``**kwargs``.
The format for a parameter is::
@ -63,6 +116,7 @@ def module_level_function(param1, param2=None, *args, **kwargs):
The description may span multiple lines. Following lines
should be indented to match the first line of the description.
The ": type" is optional.
Multiple paragraphs are supported in parameter
descriptions.
@ -71,8 +125,8 @@ def module_level_function(param1, param2=None, *args, **kwargs):
----------
param1 : int
The first parameter.
param2 : str, optional
The second parameter, defaults to None.
param2 : :obj:`str`, optional
The second parameter.
*args
Variable length argument list.
**kwargs
@ -115,19 +169,19 @@ def example_generator(n):
Parameters
----------
n : int
The upper limit of the range to generate, from 0 to `n` - 1
The upper limit of the range to generate, from 0 to `n` - 1.
Yields
------
int
The next number in the range of 0 to `n` - 1
The next number in the range of 0 to `n` - 1.
Examples
--------
Examples should be written in doctest format, and should illustrate how
to use the function.
>>> print [i for i in example_generator(4)]
>>> print([i for i in example_generator(4)])
[0, 1, 2, 3]
"""
@ -152,18 +206,19 @@ class ExampleError(Exception):
----------
msg : str
Human readable string describing the exception.
code : int, optional
Error code, defaults to 2.
code : :obj:`int`, optional
Numeric error code.
Attributes
----------
msg : str
Human readable string describing the exception.
code : int
Exception error code.
Numeric error code.
"""
def __init__(self, msg, code=2):
def __init__(self, msg, code):
self.msg = msg
self.code = code
@ -171,21 +226,24 @@ class ExampleError(Exception):
class ExampleClass(object):
"""The summary line for a class docstring should fit on one line.
If the class has public attributes, they should be documented here
If the class has public attributes, they may be documented here
in an ``Attributes`` section and follow the same formatting as a
function's ``Parameters`` section.
function's ``Args`` section. Alternatively, attributes may be documented
inline with the attribute's declaration (see __init__ method below).
Properties created with the ``@property`` decorator should be documented
in the property's getter method.
Attributes
----------
attr1 : str
Description of `attr1`.
attr2 : list of str
attr2 : :obj:`int`, optional
Description of `attr2`.
attr3 : int
Description of `attr3`.
"""
def __init__(self, param1, param2, param3=0):
def __init__(self, param1, param2, param3):
"""Example of docstring on the __init__ method.
The __init__ method may be documented in either the class level
@ -202,16 +260,41 @@ class ExampleClass(object):
----------
param1 : str
Description of `param1`.
param2 : list of str
param2 : list(str)
Description of `param2`. Multiple
lines are supported.
param3 : int, optional
Description of `param3`, defaults to 0.
param3 : :obj:`int`, optional
Description of `param3`.
"""
self.attr1 = param1
self.attr2 = param2
self.attr3 = param3
self.attr3 = param3 #: Doc comment *inline* with attribute
#: list(str): Doc comment *before* attribute, with type specified
self.attr4 = ["attr4"]
self.attr5 = None
"""str: Docstring *after* attribute, with type specified."""
@property
def readonly_property(self):
"""str: Properties should be documented in their getter method."""
return "readonly_property"
@property
def readwrite_property(self):
"""list(str): Properties with both a getter and setter
should only be documented in their getter method.
If the setter method contains notable behavior, it should be
mentioned here.
"""
return ["readwrite_property"]
@readwrite_property.setter
def readwrite_property(self, value):
value
def example_method(self, param1, param2):
"""Class methods are similar to regular functions.
@ -236,16 +319,17 @@ class ExampleClass(object):
return True
def __special__(self):
"""By default special members with docstrings are included.
"""By default special members with docstrings are not included.
Special members are any methods or attributes that start with and
end with a double underscore. Any special member with a docstring
will be included in the output.
will be included in the output, if
``napoleon_include_special_with_doc`` is set to True.
This behavior can be disabled by changing the following setting in
This behavior can be enabled by changing the following setting in
Sphinx's conf.py::
napoleon_include_special_with_doc = False
napoleon_include_special_with_doc = True
"""
pass

2
doc/ext/example_numpy.rst
View File

@ -9,6 +9,8 @@ Example NumPy Style Python Docstrings
:ref:`example_google`
.. only:: builder_html
Download: :download:`example_numpy.py <example_numpy.py>`
.. literalinclude:: example_numpy.py

12
doc/ext/githubpages.rst Normal file
View File

@ -0,0 +1,12 @@
.. highlight:: rest
:mod:`sphinx.ext.githubpages` -- Publish HTML docs in GitHub Pages
==================================================================
.. module:: sphinx.ext.githubpages
:synopsis: Publish HTML docs in GitHub Pages
.. versionadded:: 1.4
This extension creates ``.nojekyll`` file on generated HTML directory to publish
the document on GitHub Pages.

34
doc/ext/graphviz.rst
View File

@ -53,6 +53,10 @@ It adds these directives:
"bar" -- "baz";
.. note:: The graph name is passed unchanged to Graphviz. If it contains
non-alphanumeric characters (e.g. a dash), you will have to double-quote
it.
.. rst:directive:: digraph
@ -83,6 +87,19 @@ It adds these directives:
caption to the diagram. Naturally, diagrams marked as "inline" cannot have a
caption.
.. deprecated:: 1.4
``inline`` option is deprecated.
All three directives generate inline node by default. If ``caption`` is given,
these generate block node instead.
.. versionchanged:: 1.4
All three directives support a ``graphviz_dot`` option that can be switch the
``dot`` command within the directive.
.. versionadded:: 1.5
All three directives support a ``align`` option to align the graph horizontal.
The values "left", "center", "right" are allowed.
There are also these new config values:
.. confval:: graphviz_dot
@ -93,8 +110,8 @@ There are also these new config values:
Since this setting is not portable from system to system, it is normally not
useful to set it in ``conf.py``; rather, giving it on the
:program:`sphinx-build` command line via the :option:`-D` option should be
preferable, like this::
:program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
option should be preferable, like this::
sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
@ -107,7 +124,18 @@ There are also these new config values:
.. confval:: graphviz_output_format
The output format for Graphviz when building HTML files. This must be either
``'png'`` or ``'svg'``; the default is ``'png'``.
``'png'`` or ``'svg'``; the default is ``'png'``. If ``'svg'`` is used, in
order to make the URL links work properly, an appropriate ``target``
attribute must be set, such as ``"_top"`` and ``"_blank"``. For example, the
link in the following graph should work in the svg output: ::
.. graphviz::
digraph example {
a [label="sphinx", href="http://sphinx-doc.org", target="_top"];
b [label="other"];
a -> b;
}
.. versionadded:: 1.0
Previously, output always was PNG.

4
doc/ext/ifconfig.rst
View File

@ -26,8 +26,8 @@ This extension is quite simple, and features only one directive:
:file:`conf.py`, e.g.::
def setup(app):
app.add_config_value('releaselevel', '', True)
app.add_config_value('releaselevel', '', 'env')
The second argument is the default value, the third should always be ``True``
The second argument is the default value, the third should always be ``'env'``
for such values (it selects if Sphinx re-reads the documents if the value
changes).

5
doc/ext/inheritance.rst
View File

@ -33,10 +33,15 @@ It adds this directive:
It also supports a ``private-bases`` flag option; if given, private base
classes (those whose name starts with ``_``) will be included.
You can use ``caption`` option to give a caption to the diagram.
.. versionchanged:: 1.1
Added ``private-bases`` option; previously, all bases were always
included.
.. versionchanged:: 1.5
Added ``caption`` option
New config values are:

90
doc/ext/math.rst
View File

@ -4,7 +4,7 @@ Math support in Sphinx
======================
.. module:: sphinx.ext.mathbase
:synopsis: Common math support for pngmath and mathjax / jsmath.
:synopsis: Common math support for imgmath and mathjax / jsmath.
.. versionadded:: 0.5
@ -17,7 +17,7 @@ support extensions should, if possible, reuse that support too.
.. note::
:mod:`.mathbase` is not meant to be added to the :confval:`extensions` config
value, instead, use either :mod:`sphinx.ext.pngmath` or
value, instead, use either :mod:`sphinx.ext.imgmath` or
:mod:`sphinx.ext.mathjax` as described below.
The input language for mathematics is LaTeX markup. This is the de-facto
@ -28,6 +28,13 @@ Keep in mind that when you put math markup in **Python docstrings** read by
:mod:`autodoc <sphinx.ext.autodoc>`, you either have to double all backslashes,
or use Python raw strings (``r"raw"``).
:mod:`.mathbase` provides the following config values:
.. confval:: math_number_all
Set this option to ``True`` if you want all displayed math to be numbered.
The default is ``False``.
:mod:`.mathbase` defines these new markup elements:
.. rst:role:: math
@ -96,20 +103,27 @@ or use Python raw strings (``r"raw"``).
beautiful mathematical formulas.
:mod:`sphinx.ext.pngmath` -- Render math as PNG images
------------------------------------------------------
:mod:`sphinx.ext.imgmath` -- Render math as images
--------------------------------------------------
.. module:: sphinx.ext.pngmath
:synopsis: Render math as PNG images.
.. module:: sphinx.ext.imgmath
:synopsis: Render math as PNG or SVG images.
This extension renders math via LaTeX and dvipng_ into PNG images. This of
course means that the computer where the docs are built must have both programs
available.
.. versionadded:: 1.4
This extension renders math via LaTeX and dvipng_ or dvisvgm_ into PNG or SVG
images. This of course means that the computer where the docs are built must
have both programs available.
There are various config values you can set to influence how the images are
built:
.. confval:: pngmath_latex
.. confval:: imgmath_image_format
The output image format. The default is ``'png'``. It should be either
``'png'`` or ``'svg'``.
.. confval:: imgmath_latex
The command name with which to invoke LaTeX. The default is ``'latex'``; you
may need to set this to a full path if ``latex`` is not in the executable
@ -117,45 +131,54 @@ built:
Since this setting is not portable from system to system, it is normally not
useful to set it in ``conf.py``; rather, giving it on the
:program:`sphinx-build` command line via the :option:`-D` option should be
preferable, like this::
:program:`sphinx-build` command line via the :option:`-D <sphinx-build -D>`
option should be preferable, like this::
sphinx-build -b html -D pngmath_latex=C:\tex\latex.exe . _build/html
sphinx-build -b html -D imgmath_latex=C:\tex\latex.exe . _build/html
.. versionchanged:: 0.5.1
This value should only contain the path to the latex executable, not
further arguments; use :confval:`pngmath_latex_args` for that purpose.
This value should only contain the path to the latex executable, not further
arguments; use :confval:`imgmath_latex_args` for that purpose.
.. confval:: pngmath_dvipng
.. confval:: imgmath_dvipng
The command name with which to invoke ``dvipng``. The default is
``'dvipng'``; you may need to set this to a full path if ``dvipng`` is not in
the executable search path.
the executable search path. This option is only used when
``imgmath_image_format`` is set to ``'png'``.
.. confval:: pngmath_latex_args
.. confval:: imgmath_dvisvgm
The command name with which to invoke ``dvisvgm``. The default is
``'dvisvgm'``; you may need to set this to a full path if ``dvisvgm`` is not
in the executable search path. This option is only used when
``imgmath_image_format`` is ``'svg'``.
.. confval:: imgmath_latex_args
Additional arguments to give to latex, as a list. The default is an empty
list.
.. versionadded:: 0.5.1
.. confval:: pngmath_latex_preamble
.. confval:: imgmath_latex_preamble
Additional LaTeX code to put into the preamble of the short LaTeX files that
are used to translate the math snippets. This is empty by default. Use it
e.g. to add more packages whose commands you want to use in the math.
.. confval:: pngmath_dvipng_args
.. confval:: imgmath_dvipng_args
Additional arguments to give to dvipng, as a list. The default value is
``['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']`` which makes the
image a bit darker and larger then it is by default, and produces PNGs with a
transparent background.
transparent background. This option is used only when
``imgmath_image_format`` is ``'png'``.
.. versionchanged:: 1.2
Now includes ``-bg Transparent`` by default.
.. confval:: imgmath_dvisvgm_args
.. confval:: pngmath_use_preview
Additional arguments to give to dvisvgm, as a list. The default value is
``['--no-fonts']``. This option is used only when ``imgmath_image_format``
is ``'svg'``.
.. confval:: imgmath_use_preview
``dvipng`` has the ability to determine the "depth" of the rendered text: for
example, when typesetting a fraction inline, the baseline of surrounding text
@ -167,12 +190,18 @@ built:
Unfortunately, this only works when the `preview-latex package`_ is
installed. Therefore, the default for this option is ``False``.
.. confval:: pngmath_add_tooltips
Currently this option is only used when ``imgmath_image_format`` is
``'png'``.
.. confval:: imgmath_add_tooltips
Default: ``True``. If false, do not add the LaTeX code as an "alt" attribute
for math images.
.. versionadded:: 1.1
.. confval:: imgmath_font_size
The font size (in ``pt``) of the displayed math. The default value is
``12``. It must be a positive integer.
:mod:`sphinx.ext.mathjax` -- Render math via JavaScript
@ -235,7 +264,8 @@ package jsMath_. It provides this config value:
.. _dvipng: http://savannah.nongnu.org/projects/dvipng/
.. _MathJax: http://www.mathjax.org/
.. _dvisvgm: http://dvisvgm.bplaced.net/
.. _MathJax: https://www.mathjax.org/
.. _jsMath: http://www.math.union.edu/~dpvc/jsmath/
.. _preview-latex package: http://www.gnu.org/software/auctex/preview-latex.html
.. _AmSMath LaTeX package: http://www.ams.org/publications/authors/tex/amslatex

106
doc/ext/napoleon.rst
View File

@ -11,6 +11,8 @@
Napoleon - *Marching toward legible docstrings*
===============================================
.. highlight:: text
Are you tired of writing docstrings that look like this::
:param path: The path of the file to wrap
@ -48,11 +50,11 @@ the documentation, so it doesn't modify any of the docstrings in your actual
source code files.
.. _ReStructuredText: http://docutils.sourceforge.net/rst.html
.. _docstrings: http://www.python.org/dev/peps/pep-0287/
.. _docstrings: https://www.python.org/dev/peps/pep-0287/
.. _Google Python Style Guide:
http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
http://google.github.io/styleguide/pyguide.html
.. _Google:
http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments
http://google.github.io/styleguide/pyguide.html#Comments
.. _NumPy:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
.. _Khan Academy:
@ -110,9 +112,11 @@ All of the following section headers are supported:
* ``Raises``
* ``References``
* ``See Also``
* ``Todo``
* ``Warning``
* ``Warnings`` *(alias of Warning)*
* ``Warns``
* ``Yield`` *(alias of Yields)*
* ``Yields``
Google vs NumPy
@ -122,7 +126,9 @@ Napoleon supports two styles of docstrings: `Google`_ and `NumPy`_. The
main difference between the two styles is that Google uses indention to
separate sections, whereas NumPy uses underlines.
Google style::
Google style:
.. code-block:: python3
def func(arg1, arg2):
"""Summary line.
@ -139,7 +145,9 @@ Google style::
"""
return True
NumPy style::
NumPy style:
.. code-block:: python3
def func(arg1, arg2):
"""Summary line.
@ -179,6 +187,60 @@ not be mixed. Choose one style for your project and be consistent with it.
* :ref:`example_numpy`
Type Annotations
----------------
`PEP 484`_ introduced a standard way to express types in Python code.
This is an alternative to expressing types directly in docstrings.
One benefit of expressing types according to `PEP 484`_ is that
type checkers and IDEs can take advantage of them for static code
analysis.
Google style with Python 3 type annotations::
def func(arg1: int, arg2: str) -> bool:
"""Summary line.
Extended description of function.
Args:
arg1: Description of arg1
arg2: Description of arg2
Returns:
Description of return value
"""
return True
Google style with types in docstrings::
def func(arg1, arg2):
"""Summary line.
Extended description of function.
Args:
arg1 (int): Description of arg1
arg2 (str): Description of arg2
Returns:
bool: Description of return value
"""
return True
.. Note::
`Python 2/3 compatible annotations`_ aren't currently
supported by Sphinx and won't show up in the docs.
.. _PEP 484:
https://www.python.org/dev/peps/pep-0484/
.. _Python 2/3 compatible annotations:
https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code
Configuration
=============
@ -195,6 +257,7 @@ enabled in `conf.py`::
# Napoleon settings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = False
napoleon_include_private_with_doc = False
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
@ -221,6 +284,23 @@ enabled in `conf.py`::
True to parse `NumPy style`_ docstrings. False to disable support
for NumPy style docstrings. *Defaults to True.*
.. confval:: napoleon_include_init_with_doc
True to list ``__init___`` docstrings separately from the class
docstring. False to fall back to Sphinx's default behavior, which
considers the ``__init___`` docstring as part of the class
documentation. *Defaults to False.*
**If True**::
def __init__(self):
\"\"\"
This will be included in the docs because it has a docstring
\"\"\"
def __init__(self):
# This will NOT be included in the docs
.. confval:: napoleon_include_private_with_doc
True to include private members (like ``_membername``) with docstrings
@ -358,6 +438,22 @@ enabled in `conf.py`::
* **arg2** (*int, optional*) --
Description of `arg2`, defaults to 0
.. confval:: napoleon_use_keyword
True to use a ``:keyword:`` role for each function keyword argument.
False to use a single ``:keyword arguments:`` role for all the
keywords.
*Defaults to True.*
This behaves similarly to :attr:`napoleon_use_param`. Note unlike docutils,
``:keyword:`` and ``:param:`` will not be treated the same way - there will
be a separate "Keyword Arguments" section, rendered in the same fashion as
"Parameters" section (type links created if possible)
.. seealso::
:attr:`napoleon_use_param`
.. confval:: napoleon_use_rtype
True to use the ``:rtype:`` role for the return type. False to output

27
doc/ext/todo.rst
View File

@ -16,6 +16,10 @@ There are two additional directives when using this extension:
It will only show up in the output if :confval:`todo_include_todos` is
``True``.
.. versionadded:: 1.3.2
This directive supports an ``class`` option that determines the class attribute
for HTML output. If not given, the class defaults to ``admonition-todo``.
.. rst:directive:: todolist
@ -29,3 +33,26 @@ There is also an additional config value:
If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output,
else they produce nothing. The default is ``False``.
.. confval:: todo_emit_warnings
If this is ``True``, :rst:dir:`todo` emits a warning for each TODO entries.
The default is ``False``.
.. versionadded:: 1.5
.. confval:: todo_link_only
If this is ``True``, :rst:dir:`todolist` produce output without file path and line,
The default is ``False``.
.. versionadded:: 1.4
autodoc provides the following an additional event:
.. event:: todo-defined (app, node)
.. versionadded:: 1.5
Emitted when a todo is defined. *node* is the defined ``sphinx.ext.todo.todo_node``
node.

32
doc/ext/viewcode.rst
View File

@ -15,11 +15,12 @@ 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.
There are currently no configuration values for this extension; you just need to
add ``'sphinx.ext.viewcode'`` to your :confval:`extensions` value for it to
work.
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 also an additional config value:
There is an additional config value:
.. confval:: viewcode_import
@ -38,3 +39,26 @@ There is also an additional config value:
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.

30
doc/extdev/appapi.rst
View File

@ -125,6 +125,28 @@ package.
.. versionchanged:: 0.5
Added the support for keyword arguments giving visit functions.
.. method:: Sphinx.add_enumerable_node(node, figtype, title_getter=None, **kwds)
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`.
*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.
*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)
@ -155,7 +177,7 @@ package.
add_directive('literalinclude', literalinclude_directive,
content = 0, arguments = (1, 0, 0),
linenos = directives.flag,
language = direcitves.unchanged,
language = directives.unchanged,
encoding = directives.encoding)
.. versionchanged:: 0.6
@ -336,6 +358,12 @@ package.
.. versionadded:: 1.1
.. method:: Sphinx.add_source_parser(suffix, parser)
Register a parser class for specified *suffix*.
.. versionadded:: 1.4
.. method:: Sphinx.require_sphinx(version)
Compare *version* (which must be a ``major.minor`` version string,

6
doc/extdev/envapi.rst
View File

@ -17,7 +17,11 @@ Build environment API
.. attribute:: srcdir
Source directory (the directory containing ``conf.py``).
Source directory.
.. attribute:: confdir
Directory containing ``conf.py``.
.. attribute:: doctreedir

1
doc/extdev/index.rst
View File

@ -52,4 +52,5 @@ APIs used for writing extensions
builderapi
markupapi
domainapi
parserapi
nodes

2
doc/extdev/markupapi.rst
View File

@ -135,5 +135,5 @@ return ``node.children`` from the Directive.
.. seealso::
`Creating directives <http://docutils.sf.net/docs/howto/rst-directives.html>`_
`Creating directives <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_
HOWTO of the Docutils documentation

8
doc/extdev/parserapi.rst Normal file
View File

@ -0,0 +1,8 @@
.. _parser-api:
Parser API
==========
.. module:: sphinx.parsers
.. autoclass:: Parser

4
doc/extdev/tutorial.rst
View File

@ -149,7 +149,7 @@ The new elements are added in the extension's setup function. Let us create a
new Python module called :file:`todo.py` and add the setup function::
def setup(app):
app.add_config_value('todo_include_todos', False, False)
app.add_config_value('todo_include_todos', False, 'html')
app.add_node(todolist)
app.add_node(todo,
@ -171,7 +171,7 @@ the individual calls do is the following:
new *config value* ``todo_include_todos``, whose default value should be
``False`` (this also tells Sphinx that it is a boolean value).
If the third argument was ``True``, all documents would be re-read if the
If the third argument was ``'html'``, HTML documents would be full rebuild if the
config value changed its value. This is needed for config values that
influence reading (build phase 1).

20
doc/extensions.rst
View File

@ -19,19 +19,21 @@ These extensions are built in and can be activated by respective entries in the
.. toctree::
ext/autodoc
ext/autosectionlabel
ext/autosummary
ext/doctest
ext/intersphinx
ext/math
ext/graphviz
ext/inheritance
ext/ifconfig
ext/coverage
ext/todo
ext/doctest
ext/extlinks
ext/viewcode
ext/githubpages
ext/graphviz
ext/ifconfig
ext/inheritance
ext/intersphinx
ext/linkcode
ext/math
ext/napoleon
ext/todo
ext/viewcode
Third-party extensions
@ -47,7 +49,7 @@ 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/group/sphinx-dev>`_).
list (`join here <https://groups.google.com/forum/#!forum/sphinx-dev>`_).
.. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib

16
doc/faq.rst
View File

@ -10,7 +10,7 @@ How do I...
-----------
... create PDF files without LaTeX?
You can use `rst2pdf <http://rst2pdf.googlecode.com>`_ version 0.12 or
You can use `rst2pdf <https://github.com/rst2pdf/rst2pdf>`_ version 0.12 or
greater which comes with built-in Sphinx integration. See the
:ref:`builders` section for details.
@ -82,7 +82,7 @@ GitHub Pages
Sphinx HTML output properly.
MediaWiki
See https://bitbucket.org/kevindunn/sphinx-wiki, a project by Kevin Dunn.
See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a project by Kevin Dunn.
Google Analytics
You can use a custom ``layout.html`` template, like this:
@ -140,7 +140,7 @@ The following list gives some hints for the creation of epub files:
are often cut at the right margin. The default Courier font (or variant) is
quite wide and you can only display up to 60 characters on a line. If you
replace it with a narrower font, you can get more characters on a line. You
may even use `FontForge <http://fontforge.org/>`_ and create
may even use `FontForge <http://fontforge.github.io/>`_ and create
narrow variants of some free font. In my case I get up to 70 characters on a
line.
@ -149,7 +149,7 @@ The following list gives some hints for the creation of epub files:
* Test the created epubs. You can use several alternatives. The ones I am aware
of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS),
and Bookworm_. For bookworm you can download the source from
http://code.google.com/p/threepress/ and run your own local server.
https://code.google.com/archive/p/threepress and run your own local server.
* Large floating divs are not displayed properly.
If they cover more than one page, the div is only shown on the first page.
@ -167,10 +167,10 @@ The following list gives some hints for the creation of epub files:
:confval:`html_static_path` directory and reference it with its full path in
the :confval:`epub_cover` config option.
.. _Epubcheck: http://code.google.com/p/epubcheck/
.. _Epubcheck: https://code.google.com/archive/p/epubcheck
.. _Calibre: http://calibre-ebook.com/
.. _FBreader: http://fbreader.org/
.. _Bookworm: http://oreilly.com/bookworm/index.html
.. _FBreader: https://fbreader.org/
.. _Bookworm: http://www.oreilly.com/bookworm/index.html
.. _texinfo-faq:
@ -213,7 +213,7 @@ If you want Emacs to display Info files produced by Sphinx using the value
Info files, try adding the following Emacs Lisp code to your start-up file,
``~/.emacs.d/init.el``.
::
.. code-block:: elisp
(defadvice info-insert-file-contents (after
sphinx-info-insert-file-contents

8
doc/install.rst
View File

@ -72,7 +72,7 @@ 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 http://python.org, the main download site for Python. Look at the left
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
@ -114,7 +114,7 @@ as ``sphinx-build`` easily from the Command Prompt.
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
@ -139,7 +139,7 @@ install.
Installing Sphinx with pip
---------------------------
--------------------------
If you finished the installation of pip, type this line in the command prompt:
@ -147,7 +147,7 @@ If you finished the installation of pip, type this line in the command prompt:
C:\> pip install sphinx
After installation, type :command:`sphinx-build` on the command prompt. If
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.

BIN
doc/installpython.jpg
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 28 KiB

After

Width:  |  Height:  |  Size: 25 KiB

45
doc/intl.rst
View File

@ -63,7 +63,7 @@ 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`).
* Set :confval:`language` to ``es`` (also possible via :option:`-D <sphinx-build -D>`).
* Run your desired build.
@ -88,14 +88,18 @@ This section describe a easy way to translate with sphinx-intl.
:confval:`gettext_compact` is set to `False` (the Sphinx document is
already configured as such).
#. Extract document's translatable messages into pot files::
#. Extract document's translatable messages into pot files:
.. code-block:: console
$ make gettext
As a result, many pot files are generated under ``_build/locale``
directory.
#. Setup/Update your `locale_dir`::
#. Setup/Update your `locale_dir`:
.. code-block:: console
$ sphinx-intl update -p _build/locale -l de -l ja
@ -106,17 +110,25 @@ This section describe a easy way to translate with sphinx-intl.
#. Translate your po files under `./locale/<lang>/LC_MESSAGES/`.
#. Build mo files and make translated document.
#. make 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:
.. code-block:: console
$ sphinx-intl build
$ make -e SPHINXOPTS="-D language='de'" 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.
Translating
^^^^^^^^^^^
@ -157,7 +169,7 @@ 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.
.. code-block:: bash
.. code-block:: console
$ sphinx-intl update -p _build/locale
@ -176,7 +188,7 @@ easy to fetch and push translations.
You need :command:`tx` command to upload resources (pot files).
.. code-block:: bash
.. code-block:: console
$ pip install transifex-client
@ -200,7 +212,7 @@ easy to fetch and push translations.
This process will create ``.tx/config`` in the current directory, as well as
a ``~/.transifexrc`` file that includes auth information.
.. code-block:: bash
.. code-block:: console
$ tx init
Creating .tx folder...
@ -215,7 +227,7 @@ easy to fetch and push translations.
Register pot files to ``.tx/config`` file:
.. code-block:: bash
.. code-block:: console
$ cd /your/document/root
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
@ -223,7 +235,7 @@ easy to fetch and push translations.
and upload pot files:
.. code-block:: bash
.. code-block:: console
$ tx push -s
Pushing translations for resource sphinx-document-test_1_0.builders:
@ -242,7 +254,7 @@ easy to fetch and push translations.
Get translated catalogs and build mo files (ex. for 'de'):
.. code-block:: bash
.. code-block:: console
$ cd /your/document/root
$ tx pull -l de
@ -251,9 +263,10 @@ easy to fetch and push translations.
...
Done.
Build po files into mo and make html::
Invoke make html:
.. code-block:: console
$ sphinx-intl build
$ make -e SPHINXOPTS="-D language='de'" html
@ -297,5 +310,5 @@ There is `sphinx translation page`_ for Sphinx-1.3 documentation.
.. _`transifex-client`: https://pypi.python.org/pypi/transifex-client
.. _`sphinx-intl`: https://pypi.python.org/pypi/sphinx-intl
.. _Transifex: https://www.transifex.com/
.. _`sphinx translation page`: https://www.transifex.com/projects/p/sphinx-doc-1_3/
.. _`Transifex Client v0.8 &mdash; Transifex documentation`: http://help.transifex.com/features/client/index.html
.. _`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/

12
doc/intro.rst
View File

@ -9,12 +9,12 @@ 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
LaTeX file that you can compile into a PDF version of the documents, or a
PDF file directly using `rst2pdf <http://rst2pdf.googlecode.com>`_.
PDF file directly using `rst2pdf <https://github.com/rst2pdf/rst2pdf>`_.
The focus is on hand-written documentation, rather than auto-generated API docs.
Though there is support for that kind of docs as well (which is intended to be
freely mixed with hand-written content), if you need pure API docs have a look
at `Epydoc <http://epydoc.sf.net/>`_, which also understands reST.
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
@ -36,12 +36,12 @@ to reStructuredText/Sphinx from other documentation systems.
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 <http://code.google.com/p/db2rst/>`_.
markup; it is at `Google Code <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 convert different markups, `Pandoc <http://johnmacfarlane.net/pandoc/>`_ is
* To convert different markups, `Pandoc <http://pandoc.org/>`_ is
a very helpful tool.
@ -59,8 +59,8 @@ 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.
.. _reStructuredText: http://docutils.sf.net/rst.html
.. _docutils: http://docutils.sf.net/
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _docutils: http://docutils.sourceforge.net/
.. _Jinja2: http://jinja.pocoo.org/
.. _Pygments: http://pygments.org/

16
doc/invocation.rst
View File

@ -6,7 +6,9 @@ Invocation of sphinx-quickstart
===============================
The :program:`sphinx-quickstart` script generates a Sphinx documentation set.
It is called like this::
It is called like this:
.. code-block:: console
$ sphinx-quickstart [options] [projectdir]
@ -100,9 +102,9 @@ Extension options
Enable `sphinx.ext.coverage` extension.
.. option:: --ext-pngmath
.. option:: --ext-imgmath
Enable `sphinx.ext.pngmath` extension.
Enable `sphinx.ext.imgmath` extension.
.. option:: --ext-mathjax
@ -141,7 +143,9 @@ Invocation of sphinx-build
==========================
The :program:`sphinx-build` script builds a Sphinx documentation set. It is
called like this::
called like this:
.. code-block:: console
$ sphinx-build [options] sourcedir builddir [filenames]
@ -380,7 +384,9 @@ Invocation of sphinx-apidoc
===========================
The :program:`sphinx-apidoc` generates completely automatic API documentation
for a Python package. It is called like this::
for a Python package. It is called like this:
.. code-block:: console
$ sphinx-apidoc [options] -o outputdir packagedir [pathnames]

151
doc/latex.rst Normal file
View File

@ -0,0 +1,151 @@
.. highlightlang:: python
.. _latex:
LaTeX customization
===================
.. module:: latex
:synopsis: LaTeX specifics.
The *latex* target does not (yet) benefit from pre-prepared themes like the
*html* target does (see :doc:`theming`).
There are two principal means of setting up customization:
#. usage of the :ref:`latex-options` as described in :doc:`config`, particularly the
various keys of :confval:`latex_elements`, to modify the loaded packages,
for example::
'fontpkg': '\\usepackage{times}', # can load other font
'fncychap': '\\usepackage[Bjarne]{fncychap}', # can use other option
.. tip::
It is not mandatory to load *fncychap*. Naturally, without it and in
absence of further customizations, the chapter headings will revert to
LaTeX's default for the *report* class.
#. usage of LaTeX ``\renewcommand``, ``\renewenvironment``, ``\setlength``,
``\definecolor`` to modify the defaults from package file :file:`sphinx.sty`
and class files :file:`sphinxhowto.cls` and :file:`sphinxmanual.cls`. If such
definitions are few, they can be located inside the ``'preamble'`` key of
:confval:`latex_elements`. In case of many it may prove more convenient to
assemble them into a specialized file :file:`customizedmacros.tex` and use::
'preamble': '\\makeatletter\\input{customizedmacros.tex}\\makeatother',
More advanced LaTeX users will set up a style file
:file:`customizedmacros.sty`, which can then be loaded via::
'preamble': '\\usepackage{customizedmacros}',
The :ref:`build configuration file <build-config>` file will then have its variable
:confval:`latex_additional_files` appropriately configured, for example::
latex_additional_files = ["customizedmacros.sty"]
Such *LaTeX Sphinx theme* files could possibly be contributed in the
future by advanced users for wider use.
Let us illustrate here what can be modified by the second method.
- text styling commands (they have one argument): ``\sphinx<foo>`` with
``<foo>`` being one of ``strong``, ``bfcode``, ``email``, ``tablecontinued``,
``titleref``, ``menuselection``, ``accelerator``, ``crossref``, ``termref``,
``optional``. By default and for backwards compatibility the ``\sphinx<foo>``
expands to ``\<foo>`` hence the user can choose to customize rather the latter
(the non-prefixed macros will be left undefined if option
:confval:`latex_keep_old_macro_names` is set to ``False`` in :file:`conf.py`.)
.. versionchanged:: 1.4.5
use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
with user added packages. The LaTeX writer uses always the prefixed names.
- more text styling commands: ``\sphinxstyle<bar>`` with ``<bar>`` one of
``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``thead``,
``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``,
``abbreviation``, ``literalintitle``.
.. versionadded:: 1.5
earlier, the LaTeX writer used hard-coded ``\texttt``, ``\emph``, etc...
- parameters for paragraph level environments: with ``<foo>`` one of
:dudir:`warning`, :dudir:`caution`, :dudir:`attention`,
:dudir:`danger`, :dudir:`error`, the colours
*sphinx<foo>bordercolor* and *sphinx<foo>bgcolor* can be
re-defined using ``\definecolor`` command. The
``\sphinx<foo>border`` is a command (not a LaTeX length) which
specifies the thickness of the frame (default ``1pt``) and can be
``\renewcommand`` 'd. The same applies with ``<foo>`` one of
:dudir:`note`, :dudir:`hint`, :dudir:`important`, :dudir:`tip`, but
the background colour is not implemented by the default environments
and the top and bottom rule thickness default is ``0.5pt``.
.. versionchanged:: 1.5
customizability of the parameters for each type of admonition.
- paragraph level environments: for each admonition as in the previous item, the
used environment is named ``sphinx<foo>``. They may be ``\renewenvironment``
'd individually, and must then be defined with one argument (it is the heading
of the notice, for example ``Warning:`` for :dudir:`warning` directive, if
English is the document language). Their default definitions use either the
*sphinxheavybox* (for the first listed directives) or the *sphinxlightbox*
environments, configured to use the parameters (colours, border thickness)
specific to each type, as mentioned in the previous item.
.. versionchanged:: 1.5
use of public environment names, separate customizability of the parameters.
- the :dudir:`contents` directive (with ``:local:`` option) and the
:dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.
Its default definition obeys three LaTeX lengths (not commands) as parameters:
``\sphinxshadowsep`` (distance from contents), ``\sphinxshadowsize`` (width of
lateral shadow), ``\sphinxshadowrule`` (thickness of the frame).
.. versionchanged:: 1.5
use of public names for the three lengths. The environment itself was
redefined to allow page breaks at release 1.4.2.
- the literal blocks (:rst:dir:`code-block` directives, etc ...), are
implemented using ``sphinxVerbatim`` environment which is a wrapper of
``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling
of the top caption and the wrapping of long lines, and a frame which allows
pagebreaks. The LaTeX lengths (not commands) ``\sphinxverbatimsep`` and
``\sphinxverbatimborder`` customize the framing. Inside tables the used
environment is ``sphinxVerbatimintable`` (it does not draw a frame, but
allows a caption).
.. versionchanged:: 1.5
``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (meaning
which is the one of ``OriginalVerbatim`` too), and custom one is called
``sphinxVerbatim``. Also, earlier version of Sphinx used
``OriginalVerbatim`` inside tables (captions were lost, long code lines
were not wrapped), they now use ``sphinxVerbatimintable``.
.. versionadded:: 1.5
the two customizable lengths, the ``sphinxVerbatimintable``.
- by default the Sphinx style file ``sphinx.sty`` includes the command
``\fvset{fontsize=\small}`` as part of its configuration of
``fancyvrb.sty``. The user may override this for example via
``\fvset{fontsize=auto}`` which will use for listings the ambient
font size. Refer to ``fancyvrb.sty``'s documentation for further keys.
.. versionadded:: 1.5
formerly, the use of ``\small`` for code listings was not customizable.
- miscellaneous colours: *TitleColor*, *InnerLinkColor*, *OuterLinkColor*,
*VerbatimColor* (this is a background colour), *VerbatimBorderColor*.
- the ``\sphinxAtStartFootnote`` is inserted between footnote numbers and their
texts, by default it does ``\mbox{ }``.
- use ``\sphinxSetHeaderFamily`` to set the font used by headings
(default is ``\sffamily\bfseries``).
.. versionadded:: 1.5
- the section, subsection, ... headings are set using *titlesec*'s
``\titleformat`` command.
- for the ``'manual'`` class, the chapter headings can be customized using
*fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. Or, if
the loading of this package has been removed from ``'fncychap'`` key, one can
use the *titlesec* ``\titleformat`` command.
.. note::
It is impossible to revert or prevent the loading of a package that results
from a ``\usepackage`` executed from inside the :file:`sphinx.sty` style
file. Sphinx aims at loading as few packages as are really needed for its
default design.

6
doc/markup/code.rst
View File

@ -21,8 +21,8 @@ an "unused" primary prompt; this is an example of what *not* to do::
2
>>>
Syntax highlighting is done with `Pygments <http://pygments.org>`_ (if it's
installed) and handled in a smart way:
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,
@ -77,7 +77,7 @@ installed) and handled in a smart way:
Line numbers
^^^^^^^^^^^^
If installed, Pygments can generate line numbers for code blocks. For
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::

11
doc/markup/inline.rst
View File

@ -200,6 +200,12 @@ Referencing downloadable files
The ``example.py`` file will be copied to the output directory, and a
suitable link generated to it.
Not to show unavailable download links, you should wrap whole paragraphs that
have this role::
.. only:: builder_html
See :download:`this example script <../example.py>`.
Cross-referencing figures by figure number
------------------------------------------
@ -242,9 +248,8 @@ objects:
.. rst:role:: option
A command-line option to an executable program. The leading hyphen(s) must
be included. This generates a link to a :rst:dir:`option` directive, if it
exists.
A command-line option to an executable program. This generates a link to
a :rst:dir:`option` directive, if it exists.
The following role creates a cross-reference to a term in a

2
doc/markup/misc.rst
View File

@ -191,7 +191,7 @@ Including content based on tags
All tags must follow the standard Python identifier syntax as set out in
the `Identifiers and keywords
<https://docs.python.org/reference/lexical_analysis.html#identifiers>`_
<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 ``_``

20
doc/markup/para.rst
View File

@ -183,6 +183,24 @@ Glossary
(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.
@ -190,6 +208,8 @@ Glossary
.. 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
---------------------------

9
doc/markup/toctree.rst
View File

@ -85,7 +85,7 @@ tables of contents. The ``toctree`` directive is the central element.
**Additional options**
You can use ``caption`` option to provide toctree caption and you can use
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`::
@ -223,11 +223,8 @@ The special document names (and pages generated for them) are:
.. rubric:: Footnotes
.. [#] The ``maxdepth`` option does not apply to the LaTeX writer, where the
whole table of contents will always be presented at the begin of the
document, and its depth is controlled by the ``tocdepth`` counter, which
you can reset in your :confval:`latex_preamble` config value using
e.g. ``\setcounter{tocdepth}{2}``.
.. [#] 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

BIN
doc/more.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.4 KiB

After

Width:  |  Height:  |  Size: 1.3 KiB

BIN
doc/pythonorg.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 150 KiB

After

Width:  |  Height:  |  Size: 146 KiB

16
doc/rest.rst
View File

@ -196,6 +196,8 @@ Use ```Link text <http://example.com/>`_`` for inline web links. If the link
text should be the web address, you don't need special markup at all, the parser
finds links and mail addresses in ordinary text.
.. important:: There must be a space between the link text and the opening \< for the URL.
You can also separate the link and the target definition (:duref:`ref
<hyperlink-targets>`), like this::
@ -223,8 +225,10 @@ as long as the text::
=================
Normally, there are no heading levels assigned to certain characters as the
structure is determined from the succession of headings. However, for the
Python documentation, this convention is used which you may follow:
structure is determined from the succession of headings. However, this
convention is used in `Python's Style Guide for documentating
<https://docs.python.org/devguide/documenting.html#style-guide>`_ which you may
follow:
* ``#`` with overline, for parts
* ``*`` with overline, for chapters
@ -359,8 +363,9 @@ directory on building (e.g. the ``_static`` directory for HTML output.)
Interpretation of image size options (``width`` and ``height``) is as follows:
if the size has no unit or the unit is pixels, the given size will only be
respected for output channels that support pixels (i.e. not in LaTeX output).
Other units (like ``pt`` for points) will be used for HTML and LaTeX output.
respected for output channels that support pixels. Other units (like ``pt``
for points) will be used for HTML and LaTeX output (the latter replaces ``pt``
by ``bp`` as this is the TeX unit such that ``72bp=1in``).
Sphinx extends the standard docutils behavior by allowing an asterisk for the
extension::
@ -382,6 +387,9 @@ Note that image file names should not contain spaces.
.. versionchanged:: 0.6
Image paths can now be absolute.
.. versionchanged:: 1.5
latex target supports pixels (default is ``96px=1in``).
Footnotes
---------

5
doc/templating.rst
View File

@ -399,3 +399,8 @@ are in HTML form), these variables are also available:
* ``includehidden`` (``False`` by default): if true, the TOC tree will also
contain hidden entries.
.. data:: page_source_suffix
The suffix of the file that was rendered. Since we support a list of :confval:`source_suffix`,
this will allow you to properly link to the original source file.

BIN
doc/themes/agogo.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 25 KiB

BIN
doc/themes/alabaster.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 33 KiB

After

Width:  |  Height:  |  Size: 32 KiB

BIN
doc/themes/bizstyle.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 35 KiB

After

Width:  |  Height:  |  Size: 26 KiB

BIN
doc/themes/classic.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 43 KiB

After

Width:  |  Height:  |  Size: 39 KiB

BIN
doc/themes/fullsize/agogo.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 60 KiB

After

Width:  |  Height:  |  Size: 56 KiB

BIN
doc/themes/fullsize/alabaster.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 55 KiB

After

Width:  |  Height:  |  Size: 39 KiB

BIN
doc/themes/fullsize/bizstyle.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 102 KiB

After

Width:  |  Height:  |  Size: 73 KiB

BIN
doc/themes/fullsize/classic.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 77 KiB

After

Width:  |  Height:  |  Size: 71 KiB

BIN
doc/themes/fullsize/haiku.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 87 KiB

After

Width:  |  Height:  |  Size: 82 KiB

BIN
doc/themes/fullsize/nature.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 35 KiB

After

Width:  |  Height:  |  Size: 32 KiB

BIN
doc/themes/fullsize/pyramid.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 105 KiB

After

Width:  |  Height:  |  Size: 100 KiB

BIN
doc/themes/fullsize/scrolls.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 95 KiB

After

Width:  |  Height:  |  Size: 86 KiB

BIN
doc/themes/fullsize/sphinx_rtd_theme.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 56 KiB

After

Width:  |  Height:  |  Size: 38 KiB

BIN
doc/themes/fullsize/sphinxdoc.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 89 KiB

After

Width:  |  Height:  |  Size: 82 KiB

BIN
doc/themes/fullsize/traditional.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 97 KiB

After

Width:  |  Height:  |  Size: 90 KiB

BIN
doc/themes/haiku.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 42 KiB

BIN
doc/themes/nature.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 28 KiB

BIN
doc/themes/pyramid.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 39 KiB

After

Width:  |  Height:  |  Size: 38 KiB

BIN
doc/themes/scrolls.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 27 KiB

BIN
doc/themes/sphinx_rtd_theme.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 31 KiB

After

Width:  |  Height:  |  Size: 28 KiB

BIN
doc/themes/sphinxdoc.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 32 KiB

After

Width:  |  Height:  |  Size: 30 KiB

BIN
doc/themes/traditional.png vendored
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 34 KiB

After

Width:  |  Height:  |  Size: 32 KiB

16
doc/theming.rst
View File

@ -51,7 +51,7 @@ The third form provides your theme path dynamically to Sphinx if the
called ``sphinx_themes`` in your setup.py file and write a ``get_path`` function
that has to return the directory with themes in it::
// in your 'setup.py'
# 'setup.py'
setup(
...
@ -63,7 +63,7 @@ that has to return the directory with themes in it::
...
)
// in 'your_package.py'
# 'your_package.py'
from os import path
package_dir = path.abspath(path.dirname(__file__))
@ -81,7 +81,7 @@ that has to return the directory with themes in it::
Builtin themes
--------------
.. cssclass:: right
.. cssclass:: longtable
+--------------------+--------------------+
| **Theme overview** | |
@ -154,9 +154,9 @@ These themes are:
.. _Read the Docs Sphinx Theme: https://pypi.python.org/pypi/sphinx_rtd_theme
* **classic** -- This is the classic theme, which looks like `the Python
documentation <https://docs.python.org/>`_. It can be customized via these
options:
* **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``.
@ -242,7 +242,7 @@ These themes are:
*sidebarwidth*.
* **haiku** -- A theme without sidebar inspired by the `Haiku OS user guide
<http://www.haiku-os.org/docs/userguide/en/contents.html>`_. The following
<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
@ -275,7 +275,7 @@ These themes are:
.. versionchanged:: 1.3
The 'default' theme has been renamed to 'classic'. 'default' is still
available, however it will emit notice a recommendation that using new
available, however it will emit a notice that it is an alias for the new
'alabaster' theme.
Creating themes

BIN
doc/translation.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 14 KiB

18
doc/tutorial.rst
View File

@ -122,8 +122,9 @@ this::
$ sphinx-build -b html sourcedir builddir
where *sourcedir* is the :term:`source directory`, and *builddir* is the
directory in which you want to place the built documentation. The :option:`-b`
option selects a builder; in this example Sphinx will build HTML files.
directory in which you want to place the built documentation.
The :option:`-b <sphinx-build -b>` option selects a builder; in this example
Sphinx will build HTML files.
|more| See :ref:`invocation` for all options that :program:`sphinx-build`
supports.
@ -299,12 +300,17 @@ features of intersphinx.
More topics to be covered
-------------------------
- Other extensions (math, viewcode, doctest)
- :doc:`Other extensions <extensions>`:
* :doc:`ext/math`,
* :doc:`ext/viewcode`,
* :doc:`ext/doctest`,
* ...
- Static files
- Selecting a theme
- Templating
- :doc:`Selecting a theme <theming>`
- :ref:`Templating <templating>`
- Using extensions
- Writing extensions
- :ref:`Writing extensions <dev-extensions>`
.. rubric:: Footnotes

2
doc/web/quickstart.rst
View File

@ -135,7 +135,7 @@ add this data to the ``COMMENT_OPTIONS`` that are used in the template.
.. note::
This only works works if your documentation is served from your
This only works if your documentation is served from your
document root. If it is served from another directory, you will
need to prefix the url route with that directory, and give the `docroot`
keyword argument when creating the web support object::

332
ez_setup.py
View File

@ -1,332 +0,0 @@
#!/usr/bin/env python
"""Bootstrap setuptools installation
To use setuptools in your package's setup.py, include this
file in the same directory and add this to the top of your setup.py::
from ez_setup import use_setuptools
use_setuptools()
To require a specific version of setuptools, set a download
mirror, or use an alternate download directory, simply supply
the appropriate options to ``use_setuptools()``.
This file can also be run as a script to install or upgrade setuptools.
"""
import os
import shutil
import sys
import tempfile
import zipfile
import optparse
import subprocess
import platform
import textwrap
import contextlib
from distutils import log
try:
from urllib.request import urlopen
except ImportError:
from urllib2 import urlopen
try:
from site import USER_SITE
except ImportError:
USER_SITE = None
DEFAULT_VERSION = "7.0"
DEFAULT_URL = "https://pypi.python.org/packages/source/s/setuptools/"
def _python_cmd(*args):
"""
Return True if the command succeeded.
"""
args = (sys.executable,) + args
return subprocess.call(args) == 0
def _install(archive_filename, install_args=()):
with archive_context(archive_filename):
# installing
log.warn('Installing Setuptools')
if not _python_cmd('setup.py', 'install', *install_args):
log.warn('Something went wrong during the installation.')
log.warn('See the error message above.')
# exitcode will be 2
return 2
def _build_egg(egg, archive_filename, to_dir):
with archive_context(archive_filename):
# building an egg
log.warn('Building a Setuptools egg in %s', to_dir)
_python_cmd('setup.py', '-q', 'bdist_egg', '--dist-dir', to_dir)
# returning the result
log.warn(egg)
if not os.path.exists(egg):
raise IOError('Could not build the egg.')
class ContextualZipFile(zipfile.ZipFile):
"""
Supplement ZipFile class to support context manager for Python 2.6
"""
def __enter__(self):
return self
def __exit__(self, type, value, traceback):
self.close()
def __new__(cls, *args, **kwargs):
"""
Construct a ZipFile or ContextualZipFile as appropriate
"""
if hasattr(zipfile.ZipFile, '__exit__'):
return zipfile.ZipFile(*args, **kwargs)
return super(ContextualZipFile, cls).__new__(cls)
@contextlib.contextmanager
def archive_context(filename):
# extracting the archive
tmpdir = tempfile.mkdtemp()
log.warn('Extracting in %s', tmpdir)
old_wd = os.getcwd()
try:
os.chdir(tmpdir)
with ContextualZipFile(filename) as archive:
archive.extractall()
# going in the directory
subdir = os.path.join(tmpdir, os.listdir(tmpdir)[0])
os.chdir(subdir)
log.warn('Now working in %s', subdir)
yield
finally:
os.chdir(old_wd)
shutil.rmtree(tmpdir)
def _do_download(version, download_base, to_dir, download_delay):
egg = os.path.join(to_dir, 'setuptools-%s-py%d.%d.egg'
% (version, sys.version_info[0], sys.version_info[1]))
if not os.path.exists(egg):
archive = download_setuptools(version, download_base,
to_dir, download_delay)
_build_egg(egg, archive, to_dir)
sys.path.insert(0, egg)
# Remove previously-imported pkg_resources if present (see
# https://bitbucket.org/pypa/setuptools/pull-request/7/ for details).
if 'pkg_resources' in sys.modules:
del sys.modules['pkg_resources']
import setuptools
setuptools.bootstrap_install_from = egg
def use_setuptools(version=DEFAULT_VERSION, download_base=DEFAULT_URL,
to_dir=os.curdir, download_delay=15):
to_dir = os.path.abspath(to_dir)
rep_modules = 'pkg_resources', 'setuptools'
imported = set(sys.modules).intersection(rep_modules)
try:
import pkg_resources
except ImportError:
return _do_download(version, download_base, to_dir, download_delay)
try:
pkg_resources.require("setuptools>=" + version)
return
except pkg_resources.DistributionNotFound:
return _do_download(version, download_base, to_dir, download_delay)
except pkg_resources.VersionConflict as VC_err:
if imported:
msg = textwrap.dedent("""
The required version of setuptools (>={version}) is not available,
and can't be installed while this script is running. Please
install a more recent version first, using
'easy_install -U setuptools'.
(Currently using {VC_err.args[0]!r})
""").format(VC_err=VC_err, version=version)
sys.stderr.write(msg)
sys.exit(2)
# otherwise, reload ok
del pkg_resources, sys.modules['pkg_resources']
return _do_download(version, download_base, to_dir, download_delay)
def _clean_check(cmd, target):
"""
Run the command to download target. If the command fails, clean up before
re-raising the error.
"""
try:
subprocess.check_call(cmd)
except subprocess.CalledProcessError:
if os.access(target, os.F_OK):
os.unlink(target)
raise
def download_file_powershell(url, target):
"""
Download the file at url to target using Powershell (which will validate
trust). Raise an exception if the command cannot complete.
"""
target = os.path.abspath(target)
ps_cmd = (
"[System.Net.WebRequest]::DefaultWebProxy.Credentials = "
"[System.Net.CredentialCache]::DefaultCredentials; "
"(new-object System.Net.WebClient).DownloadFile(%(url)r, %(target)r)"
% vars()
)
cmd = [
'powershell',
'-Command',
ps_cmd,
]
_clean_check(cmd, target)
def has_powershell():
if platform.system() != 'Windows':
return False
cmd = ['powershell', '-Command', 'echo test']
with open(os.path.devnull, 'wb') as devnull:
try:
subprocess.check_call(cmd, stdout=devnull, stderr=devnull)
except Exception:
return False
return True
download_file_powershell.viable = has_powershell
def download_file_curl(url, target):
cmd = ['curl', url, '--silent', '--output', target]
_clean_check(cmd, target)
def has_curl():
cmd = ['curl', '--version']
with open(os.path.devnull, 'wb') as devnull:
try:
subprocess.check_call(cmd, stdout=devnull, stderr=devnull)
except Exception:
return False
return True
download_file_curl.viable = has_curl
def download_file_wget(url, target):
cmd = ['wget', url, '--quiet', '--output-document', target]
_clean_check(cmd, target)
def has_wget():
cmd = ['wget', '--version']
with open(os.path.devnull, 'wb') as devnull:
try:
subprocess.check_call(cmd, stdout=devnull, stderr=devnull)
except Exception:
return False
return True
download_file_wget.viable = has_wget
def download_file_insecure(url, target):
"""
Use Python to download the file, even though it cannot authenticate the
connection.
"""
src = urlopen(url)
try:
# Read all the data in one block.
data = src.read()
finally:
src.close()
# Write all the data in one block to avoid creating a partial file.
with open(target, "wb") as dst:
dst.write(data)
download_file_insecure.viable = lambda: True
def get_best_downloader():
downloaders = (
download_file_powershell,
download_file_curl,
download_file_wget,
download_file_insecure,
)
viable_downloaders = (dl for dl in downloaders if dl.viable())
return next(viable_downloaders, None)
def download_setuptools(version=DEFAULT_VERSION, download_base=DEFAULT_URL,
to_dir=os.curdir, delay=15, downloader_factory=get_best_downloader):
"""
Download setuptools from a specified location and return its filename
`version` should be a valid setuptools version number that is available
as an sdist for download under the `download_base` URL (which should end
with a '/'). `to_dir` is the directory where the egg will be downloaded.
`delay` is the number of seconds to pause before an actual download
attempt.
``downloader_factory`` should be a function taking no arguments and
returning a function for downloading a URL to a target.
"""
# making sure we use the absolute path
to_dir = os.path.abspath(to_dir)
zip_name = "setuptools-%s.zip" % version
url = download_base + zip_name
saveto = os.path.join(to_dir, zip_name)
if not os.path.exists(saveto): # Avoid repeated downloads
log.warn("Downloading %s", url)
downloader = downloader_factory()
downloader(url, saveto)
return os.path.realpath(saveto)
def _build_install_args(options):
"""
Build the arguments to 'python setup.py install' on the setuptools package
"""
return ['--user'] if options.user_install else []
def _parse_args():
"""
Parse the command line for options
"""
parser = optparse.OptionParser()
parser.add_option(
'--user', dest='user_install', action='store_true', default=False,
help='install in user site package (requires Python 2.6 or later)')
parser.add_option(
'--download-base', dest='download_base', metavar="URL",
default=DEFAULT_URL,
help='alternative URL from where to download the setuptools package')
parser.add_option(
'--insecure', dest='downloader_factory', action='store_const',
const=lambda: download_file_insecure, default=get_best_downloader,
help='Use internal, non-validating downloader'
)
parser.add_option(
'--version', help="Specify which version to download",
default=DEFAULT_VERSION,
)
options, args = parser.parse_args()
# positional arguments are ignored
return options
def main():
"""Install or upgrade setuptools and EasyInstall"""
options = _parse_args()
archive = download_setuptools(
version=options.version,
download_base=options.download_base,
downloader_factory=options.downloader_factory,
)
return _install(archive, _build_install_args(options))
if __name__ == '__main__':
sys.exit(main())

4
setup.cfg
View File

@ -25,5 +25,5 @@ universal = 1
[flake8]
max-line-length=95
ignore=E113,E116,E221,E226,E241,E251
exclude=ez_setup.py,utils/*,tests/*,build/*,sphinx/search/*,sphinx/pycode/pgen2/*
ignore=E113,E116,E221,E226,E241,E251,E901
exclude=tests/*,build/*,sphinx/search/*,sphinx/pycode/pgen2/*,doc/ext/example*.py

72
setup.py
View File

@ -1,14 +1,10 @@
# -*- coding: utf-8 -*-
try:
from setuptools import setup, find_packages
except ImportError:
import ez_setup
ez_setup.use_setuptools()
from setuptools import setup, find_packages
import os
import sys
from distutils import log
from distutils.cmd import Command
import sphinx
@ -46,19 +42,20 @@ if sys.version_info < (2, 6) or (3, 0) <= sys.version_info < (3, 3):
sys.exit(1)
requires = [
'six>=1.4',
'six>=1.5',
'Jinja2>=2.3',
'Pygments>=2.0',
'docutils>=0.11',
'snowballstemmer>=1.1',
'babel>=1.3',
'babel>=1.3,!=2.0',
'alabaster>=0.7,<0.8',
'sphinx_rtd_theme>=0.1,<0.2',
'imagesize',
'requests',
]
extras_require = {
# Environment Marker works for wheel 0.24 or later
':sys_platform=="win32"': [
'colorama',
'colorama>=0.3.5',
],
'websupport': [
'sqlalchemy>=0.9',
@ -68,12 +65,13 @@ extras_require = {
'nose',
'mock', # it would be better for 'test:python_version in "2.6,2.7"'
'simplejson', # better: 'test:platform_python_implementation=="PyPy"'
'html5lib',
],
}
# for sdist installation with pip-1.5.6
if sys.platform == 'win32':
requires.append('colorama')
requires.append('colorama>=0.3.5')
# Provide a "compile_catalog" command that also creates the translated
# JavaScript files if Babel is available.
@ -102,6 +100,13 @@ else:
def run(self):
compile_catalog.run(self)
if isinstance(self.domain, list):
for domain in self.domain:
self._run_domain_js(domain)
else:
self._run_domain_js(self.domain)
def _run_domain_js(self, domain):
po_files = []
js_files = []
@ -110,20 +115,20 @@ else:
po_files.append((self.locale,
os.path.join(self.directory, self.locale,
'LC_MESSAGES',
self.domain + '.po')))
domain + '.po')))
js_files.append(os.path.join(self.directory, self.locale,
'LC_MESSAGES',
self.domain + '.js'))
domain + '.js'))
else:
for locale in os.listdir(self.directory):
po_file = os.path.join(self.directory, locale,
'LC_MESSAGES',
self.domain + '.po')
domain + '.po')
if os.path.exists(po_file):
po_files.append((locale, po_file))
js_files.append(os.path.join(self.directory, locale,
'LC_MESSAGES',
self.domain + '.js'))
domain + '.js'))
else:
po_files.append((self.locale, self.input_file))
if self.output_file:
@ -131,14 +136,11 @@ else:
else:
js_files.append(os.path.join(self.directory, self.locale,
'LC_MESSAGES',
self.domain + '.js'))
domain + '.js'))
for js_file, (locale, po_file) in zip(js_files, po_files):
infile = open(po_file, 'r')
try:
with open(po_file, 'r') as infile:
catalog = read_po(infile, locale)
finally:
infile.close()
if catalog.fuzzy and not self.use_fuzzy:
continue
@ -155,21 +157,43 @@ else:
msgid = msgid[0]
jscatalog[msgid] = message.string
outfile = open(js_file, 'wb')
try:
with open(js_file, 'wb') as outfile:
outfile.write('Documentation.addTranslations(')
dump(dict(
messages=jscatalog,
plural_expr=catalog.plural_expr,
locale=str(catalog.locale)
), outfile)
), outfile, sort_keys=True)
outfile.write(');')
finally:
outfile.close()
cmdclass['compile_catalog'] = compile_catalog_plusjs
class CompileGrammarCommand(Command):
description = 'Compile python grammar file for pycode'
user_options = []
def initialize_options(self):
pass
def finalize_options(self):
pass
def run(self):
from sphinx.pycode.pgen2.driver import compile_grammar
compile_grammar('sphinx/pycode/Grammar-py2.txt')
print('sphinx/pycode/Grammar-py2.txt ... done')
compile_grammar('sphinx/pycode/Grammar-py3.txt')
print('sphinx/pycode/Grammar-py3.txt ... done')
def sub_commands(self):
pass
cmdclass['compile_grammar'] = CompileGrammarCommand
setup(
name='Sphinx',
version=sphinx.__version__,

2
sphinx-apidoc.py
View File

@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx-autogen.py
View File

@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx-build.py
View File

@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

2
sphinx-quickstart.py
View File

@ -4,7 +4,7 @@
Sphinx - Python documentation toolchain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
:copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
:copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
:license: BSD, see LICENSE for details.
"""

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