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 with master and address code review

Browse Source
This commit is contained in:
woutdenolf
2019-07-08 08:29:23 +02:00
parent 063f2d066b 1c152d249c
commit 9dc9b8754d
243 changed files with 4667 additions and 5203 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
doc/extdev/deprecated.rst
View File

@@ -26,6 +26,52 @@ The following is a list of deprecated interfaces.
- (will be) Removed
- Alternatives
* - ``sphinx.domains.math.MathDomain.add_equation()``
- 2.2
- 4.0
- ``sphinx.domains.math.MathDomain.note_equation()``
* - ``sphinx.domains.math.MathDomain.get_next_equation_number()``
- 2.2
- 4.0
- ``sphinx.domains.math.MathDomain.note_equation()``
* - The ``info`` and ``warn`` arguments of
``sphinx.ext.autosummary.generate.generate_autosummary_docs()``
- 2.2
- 4.0
- ``logging.info()`` and ``logging.warning()``
* - ``sphinx.ext.autosummary.generate._simple_info()``
- 2.2
- 4.0
- ``logging.info()``
* - ``sphinx.ext.autosummary.generate._simple_warn()``
- 2.2
- 4.0
- ``logging.warning()``
* - ``sphinx.ext.todo.merge_info()``
- 2.2
- 4.0
- ``sphinx.ext.todo.TodoDomain``
* - ``sphinx.ext.todo.process_todo_nodes()``
- 2.2
- 4.0
- ``sphinx.ext.todo.TodoDomain``
* - ``sphinx.ext.todo.process_todos()``
- 2.2
- 4.0
- ``sphinx.ext.todo.TodoDomain``
* - ``sphinx.ext.todo.purge_todos()``
- 2.2
- 4.0
- ``sphinx.ext.todo.TodoDomain``
* - ``sphinx.builders.latex.LaTeXBuilder.apply_transforms()``
- 2.1
- 4.0

7
doc/faq.rst
View File

@@ -72,10 +72,9 @@ PyPI
https://pythonhosted.org/.
GitHub Pages
Directories starting with underscores are ignored by default which breaks
static files in Sphinx. GitHub's preprocessor can be `disabled
<https://github.com/blog/572-bypassing-jekyll-on-github-pages>`_ to support
Sphinx HTML output properly.
Please add :py:mod:`sphinx.ext.githubpages` to your project. It allows you
to publish your document in GitHub Pages. It generates helper files for
GitHub Pages on building HTML document automatically.
MediaWiki
See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a project by

67
doc/latex.rst
View File

@@ -740,19 +740,41 @@ thus allowing redefinitions. Check the respective files for the defaults.
Macros
~~~~~~
- text styling commands ``\sphinx<foo>`` with ``<foo>`` being one of
``strong``, ``bfcode``, ``email``, ``tablecontinued``, ``titleref``,
``menuselection``, ``accelerator``, ``crossref``, ``termref``, ``optional``.
- text styling commands:
- ``\sphinxstrong``,
- ``\sphinxbfcode``,
- ``\sphinxemail``,
- ``\sphinxtablecontinued``,
- ``\sphinxtitleref``,
- ``\sphinxmenuselection``,
- ``\sphinxaccelerator``,
- ``\sphinxcrossref``,
- ``\sphinxtermref``,
- ``\sphinxoptional``.
.. versionadded:: 1.4.5
Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
with LaTeX packages.
- more text styling: ``\sphinxstyle<bar>`` with ``<bar>`` one of
``indexentry``, ``indexextra``, ``indexpageref``, ``topictitle``,
``sidebartitle``, ``othertitle``, ``sidebarsubtitle``, ``theadfamily``,
``emphasis``, ``literalemphasis``, ``strong``, ``literalstrong``,
``abbreviation``, ``literalintitle``, ``codecontinued``, ``codecontinues``
- more text styling:
- ``\sphinxstyleindexentry``,
- ``\sphinxstyleindexextra``,
- ``\sphinxstyleindexpageref``,
- ``\sphinxstyletopictitle``,
- ``\sphinxstylesidebartitle``,
- ``\sphinxstyleothertitle``,
- ``\sphinxstylesidebarsubtitle``,
- ``\sphinxstyletheadfamily``,
- ``\sphinxstyleemphasis``,
- ``\sphinxstyleliteralemphasis``,
- ``\sphinxstylestrong``,
- ``\sphinxstyleliteralstrong``,
- ``\sphinxstyleabbreviation``,
- ``\sphinxstyleliteralintitle``,
- ``\sphinxstylecodecontinued``,
- ``\sphinxstylecodecontinues``.
.. versionadded:: 1.5
these macros were formerly hard-coded as non customizable ``\texttt``,
``\emph``, etc...
@@ -761,7 +783,7 @@ Macros
multiple paragraphs in header cells of tables.
.. versionadded:: 1.6.3
``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``.
- the table of contents is typeset via ``\sphinxtableofcontents`` which is a
- ``\sphinxtableofcontents``: it is a
wrapper (defined differently in :file:`sphinxhowto.cls` and in
:file:`sphinxmanual.cls`) of standard ``\tableofcontents``. The macro
``\sphinxtableofcontentshook`` is executed during its expansion right before
@@ -774,22 +796,22 @@ Macros
done during loading of ``'manual'`` docclass are now executed later via
``\sphinxtableofcontentshook``. This macro is also executed by the
``'howto'`` docclass, but defaults to empty with it.
- a custom ``\sphinxmaketitle`` is defined in the class files
- ``\sphinxmaketitle``: it is defined in the class files
:file:`sphinxmanual.cls` and :file:`sphinxhowto.cls` and is used as
default setting of ``'maketitle'`` :confval:`latex_elements` key.
.. versionchanged:: 1.8.3
formerly, ``\maketitle`` from LaTeX document class was modified by
Sphinx.
- for ``'manual'`` docclass a macro ``\sphinxbackoftitlepage``, if it is
defined, gets executed at end of ``\sphinxmaketitle``, before the final
- ``\sphinxbackoftitlepage``: for ``'manual'`` docclass, and if it is
defined, it gets executed at end of ``\sphinxmaketitle``, before the final
``\clearpage``. Use either the ``'maketitle'`` key or the ``'preamble'`` key
of :confval:`latex_elements` to add a custom definition of
``\sphinxbackoftitlepage``.
.. versionadded:: 1.8.3
- the citation reference is typeset via ``\sphinxcite`` which is a wrapper
of standard ``\cite``.
- ``\sphinxcite``: it is a wrapper of standard ``\cite`` for citation
references.
Environments
~~~~~~~~~~~~
@@ -801,12 +823,23 @@ Environments
.. versionadded:: 1.5.6
formerly, the ``\small`` was hardcoded in LaTeX writer and the ending
``\par`` was lacking.
- for each admonition type ``<foo>``, the
used environment is named ``sphinx<foo>``. They may be ``\renewenvironment``
- environments associated with admonitions:
- ``sphinxnote``,
- ``sphinxhint``,
- ``sphinximportant``,
- ``sphinxtip``,
- ``sphinxwarning``,
- ``sphinxcaution``,
- ``sphinxattention``,
- ``sphinxdanger``,
- ``sphinxerror``.
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*
*sphinxheavybox* (for the last 5 ones) or the *sphinxlightbox*
environments, configured to use the parameters (colours, border thickness)
specific to each type, which can be set via ``'sphinxsetup'`` string.

24
doc/man/sphinx-apidoc.rst
View File

@@ -126,6 +126,30 @@ These options are used when :option:`--full` is specified:
Sets the project release to put in generated files (see :confval:`release`).
.. rubric:: Project templating
.. versionadded:: 2.2
Project templating options for sphinx-apidoc
.. option:: -t, --templatedir=TEMPLATEDIR
Template directory for template files. You can modify the templates of
sphinx project files generated by apidoc. Following Jinja2 template
files are allowed:
* ``module.rst_t``
* ``package.rst_t``
* ``toc.rst_t``
* ``master_doc.rst_t``
* ``conf.py_t``
* ``Makefile_t``
* ``Makefile.new_t``
* ``make.bat_t``
* ``make.bat.new_t``
In detail, please refer the system template files Sphinx provides.
(``sphinx/templates/apidoc`` and ``sphinx/templates/quickstart``)
Environment
-----------

11
doc/usage/configuration.rst
View File

@@ -497,6 +497,17 @@ General configuration
direct usage of :program:`sphinx-build` as it caches
(in its default usage) the parsed source files in per builder locations.
.. hint:: An alternative way to effectively deactivate (or customize) the
smart quotes for a given builder, for example ``latex``, is to use
``make`` this way:
.. code-block:: console
make latex O="-D smartquotes_action="
This can follow some ``make html`` with no problem, in contrast to the
situation from the prior note. It requires Docutils 0.14 or later.
.. versionadded:: 1.6.6
.. confval:: tls_verify

16
doc/usage/extensions/autodoc.rst
View File

@@ -243,21 +243,23 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
These work exactly like :rst:dir:`autoclass` etc.,
but do not offer the options used for automatic member documentation.
:rst:dir:`autodata` and :rst:dir:`autoattribute` support
the ``annotation`` option.
Without this option, the representation of the object
will be shown in the documentation.
When the option is given without arguments,
only the name of the object will be printed::
:rst:dir:`autodata` and :rst:dir:`autoattribute` support the ``annotation``
option. The option controls how the value of variable is shown. If specified
without arguments, only the name of the variable will be printed, and its value
is not shown::
.. autodata:: CD_DRIVE
:annotation:
You can tell sphinx what should be printed after the name::
If the option specified with arguments, it is printed after the name as a value
of the variable::
.. autodata:: CD_DRIVE
:annotation: = your CD device name
By default, without ``annotation`` option, Sphinx tries to obtain the value of
the variable and print it after the name.
For module data members and class attributes, documentation can either be put
into a comment with special formatting (using a ``#:`` to start the comment
instead of just ``#``), or in a docstring *after* the definition. Comments

9
doc/usage/extensions/autosummary.rst
View File

@@ -148,12 +148,19 @@ also use these config values:
The new files will be placed in the directories specified in the
``:toctree:`` options of the directives.
.. confval:: autosummary_generate_overwrite
If true, autosummary already overwrites stub files by generated contents.
Defaults to true (enabled).
.. versionadded:: 3.0
.. confval:: autosummary_recursive
Boolean that determines whether to add modules and sub-packages
recursively. It is disabled by default.
.. versionadded:: 2.2
.. versionadded:: 3.0
.. confval:: autosummary_mock_imports

117
doc/usage/extensions/graphviz.rst
View File

@@ -39,6 +39,49 @@ It adds these directives:
.. versionchanged:: 1.1
Added support for external files.
.. rubric:: options
.. rst:directive:option:: alt: alternate text
:type: text
The alternate text of the graph. By default, the graph code is used to
the alternate text.
.. versionadded:: 1.0
.. rst:directive:option:: align: alignment of the graph
:type: left, center or right
The horizontal alignment of the graph.
.. versionadded:: 1.5
.. rst:directive:option:: caption: caption of the graph
:type: text
The caption of the graph.
.. versionadded:: 1.1
.. rst:directive:option:: layout: layout type of the graph
:type: text
The layout of the graph (ex. ``dot``, ``neato`` and so on). A path to the
graphviz commands are also allowed. By default, :confval:`graphviz_dot`
is used.
.. versionadded:: 1.4
.. versionchanged:: 2.2
Renamed from ``graphviz_dot``
.. rst:directive:option:: name: label
:type: text
The label of the graph.
.. versionadded:: 1.6
.. rst:directive:: graph
@@ -56,6 +99,38 @@ It adds these directives:
non-alphanumeric characters (e.g. a dash), you will have to double-quote
it.
.. rubric:: options
Same as :rst:dir:`graphviz`.
.. rst:directive:option:: alt: alternate text
:type: text
.. versionadded:: 1.0
.. rst:directive:option:: align: alignment of the graph
:type: left, center or right
.. versionadded:: 1.5
.. rst:directive:option:: caption: caption of the graph
:type: text
.. versionadded:: 1.1
.. rst:directive:option:: layout: layout type of the graph
:type: text
.. versionadded:: 1.4
.. versionchanged:: 2.2
Renamed from ``graphviz_dot``
.. rst:directive:option:: name: label
:type: text
.. versionadded:: 1.6
.. rst:directive:: digraph
@@ -69,26 +144,38 @@ It adds these directives:
"bar" -> "baz" -> "quux";
.. rubric:: options
.. versionadded:: 1.0
All three directives support an ``alt`` option that determines the image's
alternate text for HTML output. If not given, the alternate text defaults to
the graphviz code.
Same as :rst:dir:`graphviz`.
.. versionadded:: 1.1
All three directives support a ``caption`` option that can be used to give a
caption to the diagram.
.. rst:directive:option:: alt: alternate text
:type: text
.. versionchanged:: 1.4
All three directives support a ``graphviz_dot`` option that can be switch the
``dot`` command within the directive.
.. versionadded:: 1.0
.. versionadded:: 1.5
All three directives support a ``align`` option to align the graph
horizontal. The values "left", "center", "right" are allowed.
.. rst:directive:option:: align: alignment of the graph
:type: left, center or right
.. versionadded:: 1.5
.. rst:directive:option:: caption: caption of the graph
:type: text
.. versionadded:: 1.1
.. rst:directive:option:: layout: layout type of the graph
:type: text
.. versionadded:: 1.4
.. versionchanged:: 2.2
Renamed from ``graphviz_dot``
.. rst:directive:option:: name: label
:type: text
.. versionadded:: 1.6
.. versionadded:: 1.6
All three directives support a ``name`` option to set the label to graph.
There are also these config values:

13
doc/usage/installation.rst
View File

@@ -108,12 +108,13 @@ Windows
.. todo:: Could we start packaging this?
Most Windows users do not have Python installed by default, so we begin with
the installation of Python itself. If you are unsure, open the *Command
Prompt* (:kbd:`⊞Win-r` and type :command:`cmd`). Once the command prompt is
open, type :command:`python --version` and press Enter. If Python is
available, you will see the version of Python printed to the screen. If you do
not have Python installed, refer to the `Hitchhikers Guide to Python's`__
Python on Windows installation guides. You must install `Python 3`__.
the installation of Python itself. To check if you already have Python
installed, open the *Command Prompt* (:kbd:`⊞Win-r` and type :command:`cmd`).
Once the command prompt is open, type :command:`python --version` and press
Enter. If Python is installed, you will see the version of Python printed to
the screen. If you do not have Python installed, refer to the `Hitchhikers
Guide to Python's`__ Python on Windows installation guides. You must install
`Python 3`__.
Once Python is installed, you can install Sphinx using :command:`pip`. Refer
to the :ref:`pip installation instructions <install-pypi>` below for more

21
doc/usage/restructuredtext/directives.rst
View File

@@ -36,8 +36,8 @@ tables of contents. The ``toctree`` directive is the central element.
.. note::
For local tables of contents, use the standard reST :dudir:`contents
directive <table-of-contents>`.
To create table of contents for current document (.rst file), use the
standard reST :dudir:`contents directive <table-of-contents>`.
.. rst:directive:: toctree
@@ -463,6 +463,12 @@ __ http://pygments.org/docs/lexers/
This will produce line numbers for all code blocks longer than five lines.
To ignore minor errors on highlighting, you can specifiy ``:force:`` option.
.. versionchanged:: 2.1
``:force:`` option.
.. rst:directive:: .. code-block:: [language]
Example::
@@ -525,6 +531,8 @@ __ http://pygments.org/docs/lexers/
some ruby code
A ``force`` option can ignore minor errors on highlighting.
.. versionchanged:: 1.1
The ``emphasize-lines`` option has been added.
@@ -538,6 +546,10 @@ __ http://pygments.org/docs/lexers/
.. versionchanged:: 2.0
The ``language`` argument becomes optional.
.. versionchanged:: 2.1
``:force:`` option has been added.
.. rst:directive:: .. literalinclude:: filename
Longer displays of verbatim text may be included by storing the example text
@@ -630,6 +642,8 @@ __ http://pygments.org/docs/lexers/
This shows the diff between ``example.py`` and ``example.py.orig`` with
unified diff format.
A ``force`` option can ignore minor errors on highlighting.
.. versionchanged:: 0.4.3
Added the ``encoding`` option.
@@ -651,6 +665,9 @@ __ http://pygments.org/docs/lexers/
With both ``start-after`` and ``lines`` in use, the first line as per
``start-after`` is considered to be with line number ``1`` for ``lines``.
.. versionchanged:: 2.1
Added the ``force`` option.
.. _glossary-directive:
Glossary