mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Merge branch 'master' into 5216-update-markdown-doc
This commit is contained in:
Timotheus Kampik
328
doc/usage/advanced/intl.rst
Normal file
328
doc/usage/advanced/intl.rst
Normal file
@@ -0,0 +1,328 @@
|
||||
.. _intl:
|
||||
|
||||
Internationalization
|
||||
====================
|
||||
|
||||
.. versionadded:: 1.1
|
||||
|
||||
Complementary to translations provided for Sphinx-generated messages such as
|
||||
navigation bars, Sphinx provides mechanisms facilitating *document* translations
|
||||
in itself. See the :ref:`intl-options` for details on configuration.
|
||||
|
||||
.. figure:: /_static/translation.png
|
||||
:width: 100%
|
||||
|
||||
Workflow visualization of translations in Sphinx. (The stick-figure is taken
|
||||
from an `XKCD comic <https://xkcd.com/779/>`_.)
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
Sphinx internationalization details
|
||||
-----------------------------------
|
||||
|
||||
**gettext** [1]_ is an established standard for internationalization and
|
||||
localization. It naively maps messages in a program to a translated string.
|
||||
Sphinx uses these facilities to translate whole documents.
|
||||
|
||||
Initially project maintainers have to collect all translatable strings (also
|
||||
referred to as *messages*) to make them known to translators. Sphinx extracts
|
||||
these through invocation of ``sphinx-build -b gettext``.
|
||||
|
||||
Every single element in the doctree will end up in a single message which
|
||||
results in lists being equally split into different chunks while large
|
||||
paragraphs will remain as coarsely-grained as they were in the original
|
||||
document. This grants seamless document updates while still providing a little
|
||||
bit of context for translators in free-text passages. It is the maintainer's
|
||||
task to split up paragraphs which are too large as there is no sane automated
|
||||
way to do that.
|
||||
|
||||
After Sphinx successfully ran the
|
||||
:class:`~sphinx.builders.gettext.MessageCatalogBuilder` you will find a
|
||||
collection of ``.pot`` files in your output directory. These are **catalog
|
||||
templates** and contain messages in your original language *only*.
|
||||
|
||||
They can be delivered to translators which will transform them to ``.po`` files
|
||||
--- so called **message catalogs** --- containing a mapping from the original
|
||||
messages to foreign-language strings.
|
||||
|
||||
*gettext* compiles them into a binary format known as **binary catalogs**
|
||||
through :program:`msgfmt` for efficiency reasons. If you make these files
|
||||
discoverable with :confval:`locale_dirs` for your :confval:`language`, Sphinx
|
||||
will pick them up automatically.
|
||||
|
||||
An example: you have a document ``usage.rst`` in your Sphinx project. The
|
||||
*gettext* builder will put its messages into ``usage.pot``. Imagine you have
|
||||
Spanish translations [2]_ stored in ``usage.po`` --- for your builds to
|
||||
be translated you need to follow these instructions:
|
||||
|
||||
* Compile your message catalog to a locale directory, say ``locale``, so it
|
||||
ends up in ``./locale/es/LC_MESSAGES/usage.mo`` in your source directory
|
||||
(where ``es`` is the language code for Spanish.) ::
|
||||
|
||||
msgfmt "usage.po" -o "locale/es/LC_MESSAGES/usage.mo"
|
||||
|
||||
* Set :confval:`locale_dirs` to ``["locale/"]``.
|
||||
* Set :confval:`language` to ``es`` (also possible via
|
||||
:option:`-D <sphinx-build -D>`).
|
||||
* Run your desired build.
|
||||
|
||||
|
||||
Translating with sphinx-intl
|
||||
----------------------------
|
||||
|
||||
Quick guide
|
||||
~~~~~~~~~~~
|
||||
|
||||
`sphinx-intl`_ is a useful tool to work with Sphinx translation flow. This
|
||||
section describe an easy way to translate with *sphinx-intl*.
|
||||
|
||||
#. Install `sphinx-intl`_.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install sphinx-intl
|
||||
|
||||
#. Add configurations to ``conf.py``.
|
||||
|
||||
::
|
||||
|
||||
locale_dirs = ['locale/'] # path is example but recommended.
|
||||
gettext_compact = False # optional.
|
||||
|
||||
This case-study assumes that :confval:`locale_dirs` is set to ``locale/`` and
|
||||
:confval:`gettext_compact` is set to ``False`` (the Sphinx document is
|
||||
already configured as such).
|
||||
|
||||
#. Extract translatable messages into pot files.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make gettext
|
||||
|
||||
The generated pot files will be placed in the ``_build/gettext`` directory.
|
||||
|
||||
#. Generate po files.
|
||||
|
||||
We'll use the pot files generated in the above step.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sphinx-intl update -p _build/gettext -l de -l ja
|
||||
|
||||
Once completed, the generated po files will be placed in the below
|
||||
directories:
|
||||
|
||||
* ``./locale/de/LC_MESSAGES/``
|
||||
* ``./locale/ja/LC_MESSAGES/``
|
||||
|
||||
#. Translate po files.
|
||||
|
||||
AS noted above, these are located in the ``./locale/<lang>/LC_MESSAGES``
|
||||
directory. An example of one such file, from Sphinx, ``builders.po``, is
|
||||
given below.
|
||||
|
||||
.. code-block:: po
|
||||
|
||||
# a5600c3d2e3d48fc8c261ea0284db79b
|
||||
#: ../../builders.rst:4
|
||||
msgid "Available builders"
|
||||
msgstr "<FILL HERE BY TARGET LANGUAGE>"
|
||||
|
||||
Another case, msgid is multi-line text and contains reStructuredText syntax:
|
||||
|
||||
.. code-block:: po
|
||||
|
||||
# 302558364e1d41c69b3277277e34b184
|
||||
#: ../../builders.rst:9
|
||||
msgid ""
|
||||
"These are the built-in Sphinx builders. More builders can be added by "
|
||||
":ref:`extensions <extensions>`."
|
||||
msgstr ""
|
||||
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
|
||||
"BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
|
||||
|
||||
Please be careful not to break reST notation. Most po-editors will help you
|
||||
with that.
|
||||
|
||||
#. Build translated document.
|
||||
|
||||
You need a :confval:`language` parameter in ``conf.py`` or you may also
|
||||
specify the parameter on the command line.
|
||||
|
||||
For for BSD/GNU make, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make -e SPHINXOPTS="-D language='de'" html
|
||||
|
||||
For Windows :command:`cmd.exe`, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
> set SPHINXOPTS=-D language=de
|
||||
> .\make.bat html
|
||||
|
||||
For PowerShell, run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
> Set-Item env:SPHINXOPTS "-D language=de"
|
||||
> .\make.bat html
|
||||
|
||||
Congratulations! You got the translated documentation in the ``_build/html``
|
||||
directory.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
:program:`sphinx-build` that is invoked by make command will build po files
|
||||
into mo files.
|
||||
|
||||
If you are using 1.2.x or earlier, please invoke :command:`sphinx-intl build`
|
||||
command before :command:`make` command.
|
||||
|
||||
Translating
|
||||
~~~~~~~~~~~
|
||||
|
||||
Update your po files by new pot files
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
If a document is updated, it is necessary to generate updated pot files and to
|
||||
apply differences to translated po files. In order to apply the updates from a
|
||||
pot file to the po file, use the :command:`sphinx-intl update` command.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sphinx-intl update -p _build/locale
|
||||
|
||||
|
||||
Using Transifex service for team translation
|
||||
--------------------------------------------
|
||||
|
||||
Transifex_ is one of several services that allow collaborative translation via a
|
||||
web interface. It has a nifty Python-based command line client that makes it
|
||||
easy to fetch and push translations.
|
||||
|
||||
.. TODO: why use transifex?
|
||||
|
||||
|
||||
#. Install `transifex-client`_.
|
||||
|
||||
You need :command:`tx` command to upload resources (pot files).
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install transifex-client
|
||||
|
||||
.. seealso:: `Transifex Client documentation`_
|
||||
|
||||
#. Create your transifex_ account and create new project for your document.
|
||||
|
||||
Currently, transifex does not allow for a translation project to have more
|
||||
than one version of the document, so you'd better include a version number in
|
||||
your project name.
|
||||
|
||||
For example:
|
||||
|
||||
:Project ID: ``sphinx-document-test_1_0``
|
||||
:Project URL: ``https://www.transifex.com/projects/p/sphinx-document-test_1_0/``
|
||||
|
||||
#. Create config files for :command:`tx` command.
|
||||
|
||||
This process will create ``.tx/config`` in the current directory, as well as
|
||||
a ``~/.transifexrc`` file that includes auth information.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tx init
|
||||
Creating .tx folder...
|
||||
Transifex instance [https://www.transifex.com]:
|
||||
...
|
||||
Please enter your transifex username: <transifex-username>
|
||||
Password: <transifex-password>
|
||||
...
|
||||
Done.
|
||||
|
||||
#. Upload pot files to transifex service.
|
||||
|
||||
Register pot files to ``.tx/config`` file:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd /your/document/root
|
||||
$ sphinx-intl update-txconfig-resources --pot-dir _build/locale \
|
||||
--transifex-project-name sphinx-document-test_1_0
|
||||
|
||||
and upload pot files:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ tx push -s
|
||||
Pushing translations for resource sphinx-document-test_1_0.builders:
|
||||
Pushing source file (locale/pot/builders.pot)
|
||||
Resource does not exist. Creating...
|
||||
...
|
||||
Done.
|
||||
|
||||
#. Forward the translation on transifex.
|
||||
|
||||
.. TODO: write this section
|
||||
|
||||
#. Pull translated po files and make translated HTML.
|
||||
|
||||
Get translated catalogs and build mo files. For example, to build mo files
|
||||
for German (de):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd /your/document/root
|
||||
$ tx pull -l de
|
||||
Pulling translations for resource sphinx-document-test_1_0.builders (...)
|
||||
-> de: locale/de/LC_MESSAGES/builders.po
|
||||
...
|
||||
Done.
|
||||
|
||||
Invoke :command:`make html` (for BSD/GNU make):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make -e SPHINXOPTS="-D language='de'" html
|
||||
|
||||
That's all!
|
||||
|
||||
.. tip:: Translating locally and on Transifex
|
||||
|
||||
If you want to push all language's po files, you can be done by using
|
||||
:command:`tx push -t` command. Watch out! This operation overwrites
|
||||
translations in transifex.
|
||||
|
||||
In other words, if you have updated each in the service and local po files,
|
||||
it would take much time and effort to integrate them.
|
||||
|
||||
|
||||
Contributing to Sphinx reference translation
|
||||
--------------------------------------------
|
||||
|
||||
The recommended way for new contributors to translate Sphinx reference is to
|
||||
join the translation team on Transifex.
|
||||
|
||||
There is `sphinx translation page`_ for Sphinx (master) documentation.
|
||||
|
||||
1. Login to transifex_ service.
|
||||
2. Go to `sphinx translation page`_.
|
||||
3. Click ``Request language`` and fill form.
|
||||
4. Wait acceptance by transifex sphinx translation maintainers.
|
||||
5. (After acceptance) Translate on transifex.
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [1] See the `GNU gettext utilities
|
||||
<https://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_
|
||||
for details on that software suite.
|
||||
.. [2] Because nobody expects the Spanish Inquisition!
|
||||
|
||||
.. _`transifex-client`: https://pypi.org/project/transifex-client/
|
||||
.. _`sphinx-intl`: https://pypi.org/project/sphinx-intl/
|
||||
.. _Transifex: https://www.transifex.com/
|
||||
.. _`sphinx translation page`: https://www.transifex.com/sphinx-doc/sphinx-doc/
|
||||
.. _`Transifex Client documentation`: https://docs.transifex.com/client/introduction/
|
||||
196
doc/usage/advanced/setuptools.rst
Normal file
196
doc/usage/advanced/setuptools.rst
Normal file
@@ -0,0 +1,196 @@
|
||||
.. _setuptools:
|
||||
|
||||
Setuptools integration
|
||||
======================
|
||||
|
||||
Sphinx supports integration with setuptools and distutils through a custom
|
||||
command - :class:`~sphinx.setup_command.BuildDoc`.
|
||||
|
||||
Using setuptools integration
|
||||
----------------------------
|
||||
|
||||
The Sphinx build can then be triggered from distutils, and some Sphinx
|
||||
options can be set in ``setup.py`` or ``setup.cfg`` instead of Sphinx's own
|
||||
configuration file.
|
||||
|
||||
For instance, from ``setup.py``::
|
||||
|
||||
# this is only necessary when not using setuptools/distribute
|
||||
from sphinx.setup_command import BuildDoc
|
||||
cmdclass = {'build_sphinx': BuildDoc}
|
||||
|
||||
name = 'My project'
|
||||
version = '1.2'
|
||||
release = '1.2.0'
|
||||
setup(
|
||||
name=name,
|
||||
author='Bernard Montgomery',
|
||||
version=release,
|
||||
cmdclass=cmdclass,
|
||||
# these are optional and override conf.py settings
|
||||
command_options={
|
||||
'build_sphinx': {
|
||||
'project': ('setup.py', name),
|
||||
'version': ('setup.py', version),
|
||||
'release': ('setup.py', release),
|
||||
'source_dir': ('setup.py', 'doc')}},
|
||||
)
|
||||
|
||||
.. note::
|
||||
|
||||
If you set Sphinx options directly in the ``setup()`` command, replace
|
||||
hyphens in variable names with underscores. In the example above,
|
||||
``source-dir`` becomes ``source_dir``.
|
||||
|
||||
Or add this section in ``setup.cfg``::
|
||||
|
||||
[build_sphinx]
|
||||
project = 'My project'
|
||||
version = 1.2
|
||||
release = 1.2.0
|
||||
source-dir = 'doc'
|
||||
|
||||
Once configured, call this by calling the relevant command on ``setup.py``::
|
||||
|
||||
$ python setup.py build_sphinx
|
||||
|
||||
Options for setuptools integration
|
||||
----------------------------------
|
||||
|
||||
.. confval:: fresh-env
|
||||
|
||||
A boolean that determines whether the saved environment should be discarded
|
||||
on build. Default is false.
|
||||
|
||||
This can also be set by passing the `-E` flag to ``setup.py``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python setup.py build_sphinx -E
|
||||
|
||||
.. confval:: all-files
|
||||
|
||||
A boolean that determines whether all files should be built from scratch.
|
||||
Default is false.
|
||||
|
||||
This can also be set by passing the `-a` flag to ``setup.py``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python setup.py build_sphinx -a
|
||||
|
||||
.. confval:: source-dir
|
||||
|
||||
The target source directory. This can be relative to the ``setup.py`` or
|
||||
``setup.cfg`` file, or it can be absolute. It defaults to ``./doc`` or
|
||||
``./docs`` if either contains a file named ``conf.py`` (checking ``./doc``
|
||||
first); otherwise it defaults to the current directory.
|
||||
|
||||
This can also be set by passing the `-s` flag to ``setup.py``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python setup.py build_sphinx -s $SOURCE_DIR
|
||||
|
||||
.. confval:: build-dir
|
||||
|
||||
The target build directory. This can be relative to the ``setup.py`` or
|
||||
``setup.cfg`` file, or it can be absolute. Default is ``./build/sphinx``.
|
||||
|
||||
.. confval:: config-dir
|
||||
|
||||
Location of the configuration directory. This can be relative to the
|
||||
``setup.py`` or ``setup.cfg`` file, or it can be absolute. Default is to use
|
||||
`source-dir`.
|
||||
|
||||
This can also be set by passing the `-c` flag to ``setup.py``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python setup.py build_sphinx -c $CONFIG_DIR
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
.. confval:: builder
|
||||
|
||||
The builder or list of builders to use. Default is ``html``.
|
||||
|
||||
This can also be set by passing the `-b` flag to ``setup.py``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python setup.py build_sphinx -b $BUILDER
|
||||
|
||||
.. versionchanged:: 1.6
|
||||
This can now be a comma- or space-separated list of builders
|
||||
|
||||
.. confval:: warning-is-error
|
||||
|
||||
A boolean that ensures Sphinx warnings will result in a failed build.
|
||||
Default is false.
|
||||
|
||||
This can also be set by passing the `-W` flag to ``setup.py``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python setup.py build_sphinx -W
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
.. confval:: project
|
||||
|
||||
The documented project's name. Default is ``''``.
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
.. confval:: version
|
||||
|
||||
The short X.Y version. Default is ``''``.
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
.. confval:: release
|
||||
|
||||
The full version, including alpha/beta/rc tags. Default is ``''``.
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
.. confval:: today
|
||||
|
||||
How to format the current date, used as the replacement for ``|today|``.
|
||||
Default is ``''``.
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
.. confval:: link-index
|
||||
|
||||
A boolean that ensures index.html will be linked to the master doc. Default
|
||||
is false.
|
||||
|
||||
This can also be set by passing the `-i` flag to ``setup.py``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python setup.py build_sphinx -i
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
.. confval:: copyright
|
||||
|
||||
The copyright string. Default is ``''``.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
|
||||
.. confval:: nitpicky
|
||||
|
||||
Run in nit-picky mode. Currently, this generates warnings for all missing
|
||||
references. See the config value :confval:`nitpick_ignore` for a way to
|
||||
exclude some references as "known missing".
|
||||
|
||||
.. versionadded:: 1.8
|
||||
|
||||
.. confval:: pdb
|
||||
|
||||
A boolean to configure ``pdb`` on exception. Default is false.
|
||||
|
||||
.. versionadded:: 1.5
|
||||
80
doc/usage/advanced/websupport/api.rst
Normal file
80
doc/usage/advanced/websupport/api.rst
Normal file
@@ -0,0 +1,80 @@
|
||||
.. _websupportapi:
|
||||
|
||||
.. currentmodule:: sphinxcontrib.websupport
|
||||
|
||||
The WebSupport Class
|
||||
====================
|
||||
|
||||
.. class:: WebSupport
|
||||
|
||||
The main API class for the web support package. All interactions with the
|
||||
web support package should occur through this class.
|
||||
|
||||
The class takes the following keyword arguments:
|
||||
|
||||
srcdir
|
||||
The directory containing reStructuredText source files.
|
||||
|
||||
builddir
|
||||
The directory that build data and static files should be placed in. This
|
||||
should be used when creating a :class:`WebSupport` object that will be
|
||||
used to build data.
|
||||
|
||||
datadir
|
||||
The directory that the web support data is in. This should be used when
|
||||
creating a :class:`WebSupport` object that will be used to retrieve data.
|
||||
|
||||
search
|
||||
This may contain either a string (e.g. 'xapian') referencing a built-in
|
||||
search adapter to use, or an instance of a subclass of
|
||||
:class:`~.search.BaseSearch`.
|
||||
|
||||
storage
|
||||
This may contain either a string representing a database uri, or an
|
||||
instance of a subclass of :class:`~.storage.StorageBackend`. If this is
|
||||
not provided, a new sqlite database will be created.
|
||||
|
||||
moderation_callback
|
||||
A callable to be called when a new comment is added that is not
|
||||
displayed. It must accept one argument: a dictionary representing the
|
||||
comment that was added.
|
||||
|
||||
staticdir
|
||||
If the static files should be created in a different location
|
||||
**and not in** ``'/static'``, this should be a string with the name of
|
||||
that location (e.g. ``builddir + '/static_files'``).
|
||||
|
||||
.. note::
|
||||
If you specify ``staticdir``, you will typically want to adjust
|
||||
``staticroot`` accordingly.
|
||||
|
||||
staticroot
|
||||
If the static files are not served from ``'/static'``, this should be a
|
||||
string with the name of that location (e.g. ``'/static_files'``).
|
||||
|
||||
docroot
|
||||
If the documentation is not served from the base path of a URL, this
|
||||
should be a string specifying that path (e.g. ``'docs'``).
|
||||
|
||||
|
||||
.. versionchanged:: 1.6
|
||||
|
||||
WebSupport class is moved to sphinxcontrib.websupport from sphinx.websupport.
|
||||
Please add ``sphinxcontrib-websupport`` package in your dependency and use
|
||||
moved class instead.
|
||||
|
||||
|
||||
Methods
|
||||
-------
|
||||
|
||||
.. automethod:: sphinxcontrib.websupport.WebSupport.build
|
||||
|
||||
.. automethod:: sphinxcontrib.websupport.WebSupport.get_document
|
||||
|
||||
.. automethod:: sphinxcontrib.websupport.WebSupport.get_data
|
||||
|
||||
.. automethod:: sphinxcontrib.websupport.WebSupport.add_comment
|
||||
|
||||
.. automethod:: sphinxcontrib.websupport.WebSupport.process_vote
|
||||
|
||||
.. automethod:: sphinxcontrib.websupport.WebSupport.get_search_results
|
||||
16
doc/usage/advanced/websupport/index.rst
Normal file
16
doc/usage/advanced/websupport/index.rst
Normal file
@@ -0,0 +1,16 @@
|
||||
.. _websupport:
|
||||
|
||||
Sphinx Web Support
|
||||
==================
|
||||
|
||||
.. versionadded:: 1.1
|
||||
|
||||
Sphinx provides a Python API to easily integrate Sphinx documentation into your
|
||||
web application. To learn more read the :ref:`websupportquickstart`.
|
||||
|
||||
.. toctree::
|
||||
|
||||
quickstart
|
||||
api
|
||||
searchadapters
|
||||
storagebackends
|
||||
255
doc/usage/advanced/websupport/quickstart.rst
Normal file
255
doc/usage/advanced/websupport/quickstart.rst
Normal file
@@ -0,0 +1,255 @@
|
||||
.. _websupportquickstart:
|
||||
|
||||
Web Support Quick Start
|
||||
=======================
|
||||
|
||||
Building Documentation Data
|
||||
----------------------------
|
||||
|
||||
To make use of the web support package in your application you'll need to build
|
||||
the data it uses. This data includes pickle files representing documents,
|
||||
search indices, and node data that is used to track where comments and other
|
||||
things are in a document. To do this you will need to create an instance of the
|
||||
:class:`~.WebSupport` class and call its :meth:`~.WebSupport.build` method::
|
||||
|
||||
from sphinxcontrib.websupport import WebSupport
|
||||
|
||||
support = WebSupport(srcdir='/path/to/rst/sources/',
|
||||
builddir='/path/to/build/outdir',
|
||||
search='xapian')
|
||||
|
||||
support.build()
|
||||
|
||||
This will read reStructuredText sources from ``srcdir`` and place the necessary
|
||||
data in ``builddir``. The ``builddir`` will contain two sub-directories: one
|
||||
named "data" that contains all the data needed to display documents, search
|
||||
through documents, and add comments to documents. The other directory will be
|
||||
called "static" and contains static files that should be served from "/static".
|
||||
|
||||
.. note::
|
||||
|
||||
If you wish to serve static files from a path other than "/static", you can
|
||||
do so by providing the *staticdir* keyword argument when creating the
|
||||
:class:`~.WebSupport` object.
|
||||
|
||||
|
||||
Integrating Sphinx Documents Into Your Webapp
|
||||
----------------------------------------------
|
||||
|
||||
Now that the data is built, it's time to do something useful with it. Start off
|
||||
by creating a :class:`~.WebSupport` object for your application::
|
||||
|
||||
from sphinxcontrib.websupport import WebSupport
|
||||
|
||||
support = WebSupport(datadir='/path/to/the/data',
|
||||
search='xapian')
|
||||
|
||||
You'll only need one of these for each set of documentation you will be working
|
||||
with. You can then call its :meth:`~.WebSupport.get_document` method to access
|
||||
individual documents::
|
||||
|
||||
contents = support.get_document('contents')
|
||||
|
||||
This will return a dictionary containing the following items:
|
||||
|
||||
* **body**: The main body of the document as HTML
|
||||
* **sidebar**: The sidebar of the document as HTML
|
||||
* **relbar**: A div containing links to related documents
|
||||
* **title**: The title of the document
|
||||
* **css**: Links to CSS files used by Sphinx
|
||||
* **script**: JavaScript containing comment options
|
||||
|
||||
This dict can then be used as context for templates. The goal is to be easy to
|
||||
integrate with your existing templating system. An example using `Jinja2
|
||||
<http://jinja.pocoo.org/>`_ is:
|
||||
|
||||
.. sourcecode:: html+jinja
|
||||
|
||||
{%- extends "layout.html" %}
|
||||
|
||||
{%- block title %}
|
||||
{{ document.title }}
|
||||
{%- endblock %}
|
||||
|
||||
{% block css %}
|
||||
{{ super() }}
|
||||
{{ document.css|safe }}
|
||||
<link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
|
||||
{% endblock %}
|
||||
|
||||
{%- block script %}
|
||||
{{ super() }}
|
||||
{{ document.script|safe }}
|
||||
{%- endblock %}
|
||||
|
||||
{%- block relbar %}
|
||||
{{ document.relbar|safe }}
|
||||
{%- endblock %}
|
||||
|
||||
{%- block body %}
|
||||
{{ document.body|safe }}
|
||||
{%- endblock %}
|
||||
|
||||
{%- block sidebar %}
|
||||
{{ document.sidebar|safe }}
|
||||
{%- endblock %}
|
||||
|
||||
|
||||
Authentication
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
To use certain features such as voting, it must be possible to authenticate
|
||||
users. The details of the authentication are left to your application. Once a
|
||||
user has been authenticated you can pass the user's details to certain
|
||||
:class:`~.WebSupport` methods using the *username* and *moderator* keyword
|
||||
arguments. The web support package will store the username with comments and
|
||||
votes. The only caveat is that if you allow users to change their username you
|
||||
must update the websupport package's data::
|
||||
|
||||
support.update_username(old_username, new_username)
|
||||
|
||||
*username* should be a unique string which identifies a user, and *moderator*
|
||||
should be a boolean representing whether the user has moderation privileges.
|
||||
The default value for *moderator* is ``False``.
|
||||
|
||||
An example `Flask <http://flask.pocoo.org/>`_ function that checks whether a
|
||||
user is logged in and then retrieves a document is::
|
||||
|
||||
from sphinxcontrib.websupport.errors import *
|
||||
|
||||
@app.route('/<path:docname>')
|
||||
def doc(docname):
|
||||
username = g.user.name if g.user else ''
|
||||
moderator = g.user.moderator if g.user else False
|
||||
try:
|
||||
document = support.get_document(docname, username, moderator)
|
||||
except DocumentNotFoundError:
|
||||
abort(404)
|
||||
return render_template('doc.html', document=document)
|
||||
|
||||
The first thing to notice is that the *docname* is just the request path. This
|
||||
makes accessing the correct document easy from a single view. If the user is
|
||||
authenticated, then the username and moderation status are passed along with the
|
||||
docname to :meth:`~.WebSupport.get_document`. The web support package will then
|
||||
add this data to the ``COMMENT_OPTIONS`` that are used in the template.
|
||||
|
||||
.. note::
|
||||
|
||||
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::
|
||||
|
||||
support = WebSupport(..., docroot='docs')
|
||||
|
||||
@app.route('/docs/<path:docname>')
|
||||
|
||||
|
||||
Performing Searches
|
||||
-------------------
|
||||
|
||||
To use the search form built-in to the Sphinx sidebar, create a function to
|
||||
handle requests to the URL 'search' relative to the documentation root. The
|
||||
user's search query will be in the GET parameters, with the key `q`. Then use
|
||||
the :meth:`~sphinxcontrib.websupport.WebSupport.get_search_results` method to
|
||||
retrieve search results. In `Flask <http://flask.pocoo.org/>`_ that would be
|
||||
like this::
|
||||
|
||||
@app.route('/search')
|
||||
def search():
|
||||
q = request.args.get('q')
|
||||
document = support.get_search_results(q)
|
||||
return render_template('doc.html', document=document)
|
||||
|
||||
Note that we used the same template to render our search results as we did to
|
||||
render our documents. That's because :meth:`~.WebSupport.get_search_results`
|
||||
returns a context dict in the same format that :meth:`~.WebSupport.get_document`
|
||||
does.
|
||||
|
||||
|
||||
Comments & Proposals
|
||||
--------------------
|
||||
|
||||
Now that this is done it's time to define the functions that handle the AJAX
|
||||
calls from the script. You will need three functions. The first function is
|
||||
used to add a new comment, and will call the web support method
|
||||
:meth:`~.WebSupport.add_comment`::
|
||||
|
||||
@app.route('/docs/add_comment', methods=['POST'])
|
||||
def add_comment():
|
||||
parent_id = request.form.get('parent', '')
|
||||
node_id = request.form.get('node', '')
|
||||
text = request.form.get('text', '')
|
||||
proposal = request.form.get('proposal', '')
|
||||
username = g.user.name if g.user is not None else 'Anonymous'
|
||||
comment = support.add_comment(text, node_id='node_id',
|
||||
parent_id='parent_id',
|
||||
username=username, proposal=proposal)
|
||||
return jsonify(comment=comment)
|
||||
|
||||
You'll notice that both a ``parent_id`` and ``node_id`` are sent with the
|
||||
request. If the comment is being attached directly to a node, ``parent_id``
|
||||
will be empty. If the comment is a child of another comment, then ``node_id``
|
||||
will be empty. Then next function handles the retrieval of comments for a
|
||||
specific node, and is aptly named
|
||||
:meth:`~sphinxcontrib.websupport.WebSupport.get_data`::
|
||||
|
||||
@app.route('/docs/get_comments')
|
||||
def get_comments():
|
||||
username = g.user.name if g.user else None
|
||||
moderator = g.user.moderator if g.user else False
|
||||
node_id = request.args.get('node', '')
|
||||
data = support.get_data(node_id, username, moderator)
|
||||
return jsonify(**data)
|
||||
|
||||
The final function that is needed will call :meth:`~.WebSupport.process_vote`,
|
||||
and will handle user votes on comments::
|
||||
|
||||
@app.route('/docs/process_vote', methods=['POST'])
|
||||
def process_vote():
|
||||
if g.user is None:
|
||||
abort(401)
|
||||
comment_id = request.form.get('comment_id')
|
||||
value = request.form.get('value')
|
||||
if value is None or comment_id is None:
|
||||
abort(400)
|
||||
support.process_vote(comment_id, g.user.id, value)
|
||||
return "success"
|
||||
|
||||
|
||||
Comment Moderation
|
||||
------------------
|
||||
|
||||
By default, all comments added through :meth:`~.WebSupport.add_comment` are
|
||||
automatically displayed. If you wish to have some form of moderation, you can
|
||||
pass the ``displayed`` keyword argument::
|
||||
|
||||
comment = support.add_comment(text, node_id='node_id',
|
||||
parent_id='parent_id',
|
||||
username=username, proposal=proposal,
|
||||
displayed=False)
|
||||
|
||||
You can then create a new view to handle the moderation of comments. It
|
||||
will be called when a moderator decides a comment should be accepted and
|
||||
displayed::
|
||||
|
||||
@app.route('/docs/accept_comment', methods=['POST'])
|
||||
def accept_comment():
|
||||
moderator = g.user.moderator if g.user else False
|
||||
comment_id = request.form.get('id')
|
||||
support.accept_comment(comment_id, moderator=moderator)
|
||||
return 'OK'
|
||||
|
||||
Rejecting comments happens via comment deletion.
|
||||
|
||||
To perform a custom action (such as emailing a moderator) when a new comment is
|
||||
added but not displayed, you can pass callable to the :class:`~.WebSupport`
|
||||
class when instantiating your support object::
|
||||
|
||||
def moderation_callback(comment):
|
||||
"""Do something..."""
|
||||
|
||||
support = WebSupport(..., moderation_callback=moderation_callback)
|
||||
|
||||
The moderation callback must take one argument, which will be the same comment
|
||||
dict that is returned by :meth:`add_comment`.
|
||||
49
doc/usage/advanced/websupport/searchadapters.rst
Normal file
49
doc/usage/advanced/websupport/searchadapters.rst
Normal file
@@ -0,0 +1,49 @@
|
||||
.. _searchadapters:
|
||||
|
||||
.. currentmodule:: sphinxcontrib.websupport.search
|
||||
|
||||
Search Adapters
|
||||
===============
|
||||
|
||||
To create a custom search adapter you will need to subclass the
|
||||
:class:`BaseSearch` class. Then create an instance of the new class and pass
|
||||
that as the `search` keyword argument when you create the :class:`~.WebSupport`
|
||||
object::
|
||||
|
||||
support = WebSupport(srcdir=srcdir,
|
||||
builddir=builddir,
|
||||
search=MySearch())
|
||||
|
||||
For more information about creating a custom search adapter, please see the
|
||||
documentation of the :class:`BaseSearch` class below.
|
||||
|
||||
.. class:: BaseSearch
|
||||
|
||||
Defines an interface for search adapters.
|
||||
|
||||
.. versionchanged:: 1.6
|
||||
|
||||
BaseSearch class is moved to sphinxcontrib.websupport.search from
|
||||
sphinx.websupport.search.
|
||||
|
||||
Methods
|
||||
-------
|
||||
|
||||
The following methods are defined in the BaseSearch class. Some methods do not
|
||||
need to be overridden, but some (:meth:`~BaseSearch.add_document` and
|
||||
:meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
|
||||
working example, look at the built-in adapter for whoosh.
|
||||
|
||||
.. automethod:: BaseSearch.init_indexing
|
||||
|
||||
.. automethod:: BaseSearch.finish_indexing
|
||||
|
||||
.. automethod:: BaseSearch.feed
|
||||
|
||||
.. automethod:: BaseSearch.add_document
|
||||
|
||||
.. automethod:: BaseSearch.query
|
||||
|
||||
.. automethod:: BaseSearch.handle_query
|
||||
|
||||
.. automethod:: BaseSearch.extract_context
|
||||
49
doc/usage/advanced/websupport/storagebackends.rst
Normal file
49
doc/usage/advanced/websupport/storagebackends.rst
Normal file
@@ -0,0 +1,49 @@
|
||||
.. _storagebackends:
|
||||
|
||||
.. currentmodule:: sphinxcontrib.websupport.storage
|
||||
|
||||
Storage Backends
|
||||
================
|
||||
|
||||
To create a custom storage backend you will need to subclass the
|
||||
:class:`StorageBackend` class. Then create an instance of the new class and
|
||||
pass that as the `storage` keyword argument when you create the
|
||||
:class:`~.WebSupport` object::
|
||||
|
||||
support = WebSupport(srcdir=srcdir,
|
||||
builddir=builddir,
|
||||
storage=MyStorage())
|
||||
|
||||
For more information about creating a custom storage backend, please see the
|
||||
documentation of the :class:`StorageBackend` class below.
|
||||
|
||||
.. class:: StorageBackend
|
||||
|
||||
Defines an interface for storage backends.
|
||||
|
||||
.. versionchanged:: 1.6
|
||||
|
||||
StorageBackend class is moved to sphinxcontrib.websupport.storage from
|
||||
sphinx.websupport.storage.
|
||||
|
||||
|
||||
Methods
|
||||
-------
|
||||
|
||||
.. automethod:: StorageBackend.pre_build
|
||||
|
||||
.. automethod:: StorageBackend.add_node
|
||||
|
||||
.. automethod:: StorageBackend.post_build
|
||||
|
||||
.. automethod:: StorageBackend.add_comment
|
||||
|
||||
.. automethod:: StorageBackend.delete_comment
|
||||
|
||||
.. automethod:: StorageBackend.get_data
|
||||
|
||||
.. automethod:: StorageBackend.process_vote
|
||||
|
||||
.. automethod:: StorageBackend.update_username
|
||||
|
||||
.. automethod:: StorageBackend.accept_comment
|
||||
@@ -158,23 +158,41 @@ The builder's "name" must be given to the **-b** command-line option of
|
||||
chapter :ref:`latex-options` for details.
|
||||
|
||||
The produced LaTeX file uses several LaTeX packages that may not be present
|
||||
in a "minimal" TeX distribution installation. For example, on Ubuntu, the
|
||||
following packages need to be installed for successful PDF builds:
|
||||
in a "minimal" TeX distribution installation.
|
||||
|
||||
On Ubuntu xenial, the following packages need to be installed for
|
||||
successful PDF builds:
|
||||
|
||||
* ``texlive-latex-recommended``
|
||||
* ``texlive-fonts-recommended``
|
||||
* ``texlive-latex-extra``
|
||||
* ``latexmk`` (for ``make latexpdf`` on GNU/Linux and MacOS X)
|
||||
* ``latex-xcolor`` (old Ubuntu)
|
||||
* ``texlive-luatex``, ``texlive-xetex`` (see :confval:`latex_engine`)
|
||||
* ``latexmk`` (this is a Sphinx requirement on GNU/Linux and MacOS X
|
||||
for functioning of ``make latexpdf``)
|
||||
|
||||
The testing of Sphinx LaTeX is done on Ubuntu trusty with the above
|
||||
mentioned packages, which are from a TeXLive 2013 snapshot dated
|
||||
February 2014.
|
||||
Additional packages are needed in some circumstances (see the discussion of
|
||||
the ``'fontpkg'`` key of :confval:`latex_elements` for more information):
|
||||
|
||||
* to support occasional Cyrillic letters or words, and a fortiori if
|
||||
:confval:`language` is set to a Cyrillic language, the package
|
||||
``texlive-lang-cyrillic`` is required, and, with unmodified ``'fontpkg'``,
|
||||
also ``cm-super`` or ``cm-super-minimal``,
|
||||
* to support occasional Greek letters or words (in text, not in
|
||||
:rst:dir:`math` directive contents), ``texlive-lang-greek`` is required,
|
||||
and, with unmodified ``'fontpkg'``, also ``cm-super`` or
|
||||
``cm-super-minimal``,
|
||||
* for ``'xelatex'`` or ``'lualatex'`` (see :confval:`latex_engine`),
|
||||
``texlive-xetex`` resp. ``texlive-luatex``, and, if leaving unchanged
|
||||
``'fontpkg'``, ``fonts-freefont-otf``.
|
||||
|
||||
The testing of Sphinx LaTeX is done on Ubuntu xenial whose TeX distribution
|
||||
is based on a TeXLive 2015 snapshot dated March 2016.
|
||||
|
||||
.. versionchanged:: 1.6
|
||||
Formerly, testing had been done on Ubuntu precise (TeXLive 2009).
|
||||
|
||||
.. versionchanged:: 2.0
|
||||
Formerly, testing had been done on Ubuntu trusty (TeXLive 2013).
|
||||
|
||||
.. note::
|
||||
|
||||
Since 1.6, ``make latexpdf`` uses ``latexmk`` (not on Windows). This
|
||||
@@ -190,20 +208,16 @@ The builder's "name" must be given to the **-b** command-line option of
|
||||
|
||||
reduces console output to a minimum.
|
||||
|
||||
Also, if ``latexmk`` version is 4.52b or higher (Jan 17)
|
||||
``LATEXMKOPTS="-xelatex"`` will speed up PDF builds via XeLateX in case
|
||||
Also, if ``latexmk`` is at version 4.52b or higher (January 2017)
|
||||
``LATEXMKOPTS="-xelatex"`` speeds up PDF builds via XeLateX in case
|
||||
of numerous graphics inclusions.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
make latexpdf LATEXMKOPTS="-xelatex"
|
||||
|
||||
To pass options directly to the ``(pdf|xe|lua)latex`` executable, use
|
||||
variable ``LATEXOPTS``.
|
||||
To pass options directly to the ``(pdf|xe|lua)latex`` binary, use
|
||||
variable ``LATEXOPTS``, for example:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
make latexpdf LATEXOPTS="--interaction=nonstopmode"
|
||||
make latexpdf LATEXOPTS="--halt-on-error"
|
||||
|
||||
.. autoattribute:: name
|
||||
|
||||
@@ -215,7 +229,7 @@ Note that a direct PDF builder is being provided by `rinohtype`_. The builder's
|
||||
name is ``rinoh``. Refer to the `rinohtype manual`_ for details.
|
||||
|
||||
.. _rinohtype: https://github.com/brechtm/rinohtype
|
||||
.. _rinohtype manual: http://www.mos6581.org/rinohtype/quickstart.html#sphinx-builder
|
||||
.. _rinohtype manual: https://www.mos6581.org/rinohtype/quickstart.html#sphinx-builder
|
||||
|
||||
.. module:: sphinx.builders.text
|
||||
.. class:: TextBuilder
|
||||
|
||||
@@ -40,9 +40,7 @@ Important points to note:
|
||||
contain the file name extension.
|
||||
|
||||
* Since :file:`conf.py` is read as a Python file, the usual rules apply for
|
||||
encodings and Unicode support: declare the encoding using an encoding cookie
|
||||
(a comment like ``# -*- coding: utf-8 -*-``) and use Unicode string literals
|
||||
when you include non-ASCII characters in configuration values.
|
||||
encodings and Unicode support.
|
||||
|
||||
* The contents of the config namespace are pickled (so that Sphinx can find out
|
||||
when configuration changes), so it may not contain unpickleable values --
|
||||
@@ -60,6 +58,36 @@ Important points to note:
|
||||
created *after* the builder is initialized.
|
||||
|
||||
|
||||
Project information
|
||||
-------------------
|
||||
|
||||
.. confval:: project
|
||||
|
||||
The documented project's name.
|
||||
|
||||
.. confval:: author
|
||||
|
||||
The author name(s) of the document. The default value is ``'unknown'``.
|
||||
|
||||
.. confval:: copyright
|
||||
|
||||
A copyright statement in the style ``'2008, Author Name'``.
|
||||
|
||||
.. confval:: version
|
||||
|
||||
The major project version, used as the replacement for ``|version|``. For
|
||||
example, for the Python documentation, this may be something like ``2.6``.
|
||||
|
||||
.. confval:: release
|
||||
|
||||
The full project version, used as the replacement for ``|release|`` and
|
||||
e.g. in the HTML templates. For example, for the Python documentation, this
|
||||
may be something like ``2.6.0rc1``.
|
||||
|
||||
If you don't need the separation provided between :confval:`version` and
|
||||
:confval:`release`, just set them both to the same value.
|
||||
|
||||
|
||||
General configuration
|
||||
---------------------
|
||||
|
||||
@@ -98,7 +126,7 @@ General configuration
|
||||
'.md': 'markdown',
|
||||
}
|
||||
|
||||
By default, Sphinx only supports ``'restrcturedtext'`` file type. You can
|
||||
By default, Sphinx only supports ``'restructuredtext'`` file type. You can
|
||||
add a new file type using source parser extensions. Please read a document
|
||||
of the extension to know what file type the extension supports.
|
||||
|
||||
@@ -149,7 +177,10 @@ General configuration
|
||||
.. confval:: master_doc
|
||||
|
||||
The document name of the "master" document, that is, the document that
|
||||
contains the root :rst:dir:`toctree` directive. Default is ``'contents'``.
|
||||
contains the root :rst:dir:`toctree` directive. Default is ``'index'``.
|
||||
|
||||
.. versionchanged:: 2.0
|
||||
The default is changed to ``'index'`` from ``'contents'``.
|
||||
|
||||
.. confval:: exclude_patterns
|
||||
|
||||
@@ -477,36 +508,6 @@ General configuration
|
||||
|
||||
.. versionadded:: 1.5
|
||||
|
||||
|
||||
Project information
|
||||
-------------------
|
||||
|
||||
.. confval:: project
|
||||
|
||||
The documented project's name.
|
||||
|
||||
.. confval:: author
|
||||
|
||||
The author name(s) of the document. The default value is ``'unknown'``.
|
||||
|
||||
.. confval:: copyright
|
||||
|
||||
A copyright statement in the style ``'2008, Author Name'``.
|
||||
|
||||
.. confval:: version
|
||||
|
||||
The major project version, used as the replacement for ``|version|``. For
|
||||
example, for the Python documentation, this may be something like ``2.6``.
|
||||
|
||||
.. confval:: release
|
||||
|
||||
The full project version, used as the replacement for ``|release|`` and
|
||||
e.g. in the HTML templates. For example, for the Python documentation, this
|
||||
may be something like ``2.6.0rc1``.
|
||||
|
||||
If you don't need the separation provided between :confval:`version` and
|
||||
:confval:`release`, just set them both to the same value.
|
||||
|
||||
.. confval:: today
|
||||
today_fmt
|
||||
|
||||
@@ -813,7 +814,7 @@ that use Sphinx's HTMLWriter class.
|
||||
.. confval:: html_theme
|
||||
|
||||
The "theme" that the HTML output should use. See the :doc:`section about
|
||||
theming </theming>`. The default is ``'alabaster'``.
|
||||
theming </usage/theming>`. The default is ``'alabaster'``.
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
@@ -1108,12 +1109,6 @@ that use Sphinx's HTMLWriter class.
|
||||
If true, the reST sources are included in the HTML build as
|
||||
:file:`_sources/{name}`. The default is ``True``.
|
||||
|
||||
.. warning::
|
||||
|
||||
If this config value is set to ``False``, the JavaScript search function
|
||||
will only display the titles of matching documents, and no excerpt from
|
||||
the matching contents.
|
||||
|
||||
.. confval:: html_show_sourcelink
|
||||
|
||||
If true (and :confval:`html_copy_source` is true as well), links to the
|
||||
@@ -1251,7 +1246,7 @@ that use Sphinx's HTMLWriter class.
|
||||
|
||||
:'sphinx.search.ja.DefaultSplitter':
|
||||
TinySegmenter algorithm. This is default splitter.
|
||||
:'sphinx.search.ja.MeCabSplitter':
|
||||
:'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.
|
||||
@@ -1333,6 +1328,16 @@ that use Sphinx's HTMLWriter class.
|
||||
|
||||
.. versionadded:: 1.6
|
||||
|
||||
Options for Single HTML output
|
||||
-------------------------------
|
||||
|
||||
.. confval:: singlehtml_sidebars
|
||||
|
||||
Custom sidebar templates, must be a dictionary that maps document names to
|
||||
template names. And it only allows a key named `'index'`. All other keys
|
||||
are ignored. For more information, refer to :confval:`html_sidebars`. By
|
||||
default, it is same as :confval:`html_sidebars`.
|
||||
|
||||
|
||||
.. _htmlhelp-options:
|
||||
|
||||
@@ -1343,6 +1348,19 @@ Options for HTML help output
|
||||
|
||||
Output file base name for HTML help builder. Default is ``'pydoc'``.
|
||||
|
||||
.. confval:: htmlhelp_file_suffix
|
||||
|
||||
This is the file name suffix for generated HTML help files. The
|
||||
default is ``".html"``.
|
||||
|
||||
.. versionadded:: 2.0
|
||||
|
||||
.. confval:: htmlhelp_link_suffix
|
||||
|
||||
Suffix for generated links to HTML files. The default is ``".html"``.
|
||||
|
||||
.. versionadded:: 2.0
|
||||
|
||||
|
||||
.. _applehelp-options:
|
||||
|
||||
@@ -1763,8 +1781,8 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
|
||||
Options for LaTeX output
|
||||
------------------------
|
||||
|
||||
These options influence LaTeX output. For customization of LaTeX
|
||||
macros and environments, see also :doc:`/latex`.
|
||||
These options influence LaTeX output. Refer to :doc:`/latex` for more
|
||||
information.
|
||||
|
||||
.. confval:: latex_engine
|
||||
|
||||
@@ -1776,24 +1794,29 @@ macros and environments, see also :doc:`/latex`.
|
||||
* ``'lualatex'`` -- LuaLaTeX
|
||||
* ``'platex'`` -- pLaTeX (default if :confval:`language` is ``'ja'``)
|
||||
|
||||
PDFLaTeX's support for Unicode characters covers those from the document
|
||||
language (the LaTeX ``babel`` and ``inputenc`` packages map them to glyph
|
||||
slots in the document font, at various encodings allowing each only 256
|
||||
characters; Sphinx uses by default (except for Cyrillic languages) the
|
||||
``times`` package), but stray characters from other scripts or special
|
||||
symbols may require adding extra LaTeX packages or macros to the LaTeX
|
||||
preamble.
|
||||
``'pdflatex'``\ 's support for Unicode characters is limited.
|
||||
|
||||
If your project uses such extra Unicode characters, switching the engine to
|
||||
XeLaTeX or LuaLaTeX often provides a quick fix. They only work with UTF-8
|
||||
encoded sources and can (in fact, should) use OpenType fonts, either from
|
||||
the system or the TeX install tree. Recent LaTeX releases will default with
|
||||
these engines to the Latin Modern OpenType font, which has good coverage of
|
||||
Latin and Cyrillic scripts (it is provided by standard LaTeX installation),
|
||||
and Sphinx does not modify this default. Refer to the documentation of the
|
||||
LaTeX ``polyglossia`` package to see how to instruct LaTeX to use some
|
||||
other OpenType font if Unicode coverage proves insufficient (or use
|
||||
directly ``\setmainfont`` et. al. as in :ref:`this example <latex-basic>`.)
|
||||
.. note::
|
||||
|
||||
2.0 adds to ``'pdflatex'`` support in Latin language document of
|
||||
occasional Cyrillic or Greek letters or words. This is not automatic,
|
||||
see the discussion of the :confval:`latex_elements` ``'fontenc'`` key.
|
||||
|
||||
If your project uses Unicode characters, setting the engine to
|
||||
``'xelatex'`` or ``'lualatex'`` and making sure to use an OpenType font
|
||||
with wide-enough glyph coverage is often easier than trying to make
|
||||
``'pdflatex'`` work with the extra Unicode characters. Since Sphinx 2.0
|
||||
the default is the GNU FreeFont which covers well Latin, Cyrillic and Greek.
|
||||
|
||||
Contrarily to :ref:`MathJaX math rendering in HTML output <math-support>`,
|
||||
LaTeX requires some extra configuration to support Unicode literals in
|
||||
:rst:dir:`math`: the only comprehensive solution (as far as we know) is to
|
||||
use ``'xelatex'`` or ``'lualatex'`` *and* to add
|
||||
``r'\usepackage{unicode-math}'`` (e.g. via the :confval:`latex_elements`
|
||||
``'preamble'`` key). You may prefer
|
||||
``r'\usepackage[math-style=literal]{unicode-math}'`` to keep a Unicode
|
||||
literal such as ``α`` (U+03B1) for example as is in output, rather than
|
||||
being rendered as :math:`\alpha`.
|
||||
|
||||
.. confval:: latex_documents
|
||||
|
||||
@@ -1926,26 +1949,23 @@ macros and environments, see also :doc:`/latex`.
|
||||
__ http://xindy.sourceforge.net/
|
||||
|
||||
- This option is ignored if :confval:`latex_engine` is ``'platex'``
|
||||
(Japanese documents) as :program:`mendex` is used in that case.
|
||||
(Japanese documents; :program:`mendex` replaces :program:`makeindex`
|
||||
then).
|
||||
|
||||
- The default is ``True`` for ``'xelatex'`` or ``'lualatex'`` as
|
||||
:program:`makeindex`, if any indexed term starts with a non-ascii
|
||||
character, creates ``.ind`` file containing invalid bytes for
|
||||
character, creates ``.ind`` files containing invalid bytes for
|
||||
UTF-8 encoding. With ``'lualatex'`` this then breaks the PDF
|
||||
build. Notice that :program:`xindy` supports most but not
|
||||
all European languages.
|
||||
build.
|
||||
|
||||
- The default is ``False`` for ``'pdflatex'`` but ``True`` is
|
||||
recommended for non-English documents as soon as some indexed
|
||||
terms use non-ascii characters from the language script.
|
||||
Cyrillic scripts are (transparently) supported with
|
||||
``'pdflatex'`` thanks to a specific Sphinx-contributed ``xindy``
|
||||
style file :file:`cyrLICRutf8.xdy`.
|
||||
|
||||
As :program:`xindy` does not support the same range of languages
|
||||
as ``LaTeX/babel`` does, the default :program:`makeindex` for
|
||||
``'pdflatex'`` may be preferred in some circumstances, although
|
||||
the index will be ill-formed probably.
|
||||
Sphinx adds to :program:`xindy` base distribution some dedicated support
|
||||
for using ``'pdflatex'`` engine with Cyrillic scripts. And whether with
|
||||
``'pdflatex'`` or Unicode engines, Cyrillic documents handle correctly the
|
||||
indexing of Latin names, even with diacritics.
|
||||
|
||||
.. versionadded:: 1.8
|
||||
|
||||
@@ -1998,33 +2018,82 @@ macros and environments, see also :doc:`/latex`.
|
||||
``english`` is used if no language.) For Japanese documents, the
|
||||
default is the empty string.
|
||||
|
||||
With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use
|
||||
`polyglossia`_, but one should be aware that current `babel`_ has
|
||||
improved its support for Unicode engines in recent years and for some
|
||||
languages it may make sense to prefer ``babel`` over ``polyglossia``.
|
||||
|
||||
.. hint::
|
||||
|
||||
After modifiying a core LaTeX key like this one, clean up the LaTeX
|
||||
build repertory before next PDF build, else left-over auxiliary
|
||||
files are likely to break the build.
|
||||
|
||||
.. _`polyglossia`: https://ctan.org/pkg/polyglossia
|
||||
.. _`babel`: https://ctan.org/pkg/babel
|
||||
|
||||
.. versionchanged:: 1.5
|
||||
For :confval:`latex_engine` set to ``'xelatex'``, the default
|
||||
is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``.
|
||||
.. versionchanged:: 1.6
|
||||
``'lualatex'`` uses same default setting as ``'xelatex'``
|
||||
.. versionchanged:: 1.7.6
|
||||
For French, ``xelatex`` and ``lualatex`` default to using
|
||||
``babel``, not ``polyglossia``.
|
||||
|
||||
``'fontpkg'``
|
||||
Font package inclusion, default ``'\\usepackage{times}'`` (which uses
|
||||
Times for text, Helvetica for sans serif and Courier for code-blocks).
|
||||
|
||||
.. hint::
|
||||
|
||||
Courier is much wider than Times, and Sphinx emits LaTeX command
|
||||
``\small`` in code-blocks to compensate. Since ``1.5`` this is not
|
||||
hard-coded anymore: ``\fvset{fontsize=auto}`` can be added to
|
||||
preamble to not change font size in code-blocks. Since ``1.8`` a
|
||||
separate ``'fvset'`` key is provided for this.
|
||||
Font package inclusion, the default is ``'\\usepackage{times}'`` which
|
||||
uses Times for text, Helvetica for sans serif and Courier for monospace.
|
||||
|
||||
.. versionchanged:: 1.2
|
||||
Defaults to ``''`` when the :confval:`language` uses the Cyrillic
|
||||
script.
|
||||
.. versionchanged:: 1.5
|
||||
Defaults to ``''`` when :confval:`latex_engine` is ``'xelatex'``.
|
||||
.. versionchanged:: 1.6
|
||||
Defaults to ``''`` also with ``'lualatex'``.
|
||||
.. versionchanged:: 1.8
|
||||
``'xelatex'`` and ``'lualatex'`` do ``\fvset{fontsize=auto}``.
|
||||
.. versionchanged:: 2.0
|
||||
Support for individual Greek and Cyrillic letters:
|
||||
|
||||
- In order to support occasional Cyrillic (физика частиц)
|
||||
or Greek letters (Σωματιδιακή φυσική) in
|
||||
a document whose language is English or a Latin European
|
||||
one, the default set-up is enhanced (only for ``'pdflatex'``
|
||||
engine) to do:
|
||||
|
||||
.. code-block:: latex
|
||||
|
||||
\substitutefont{LGR}{\rmdefault}{cmr}
|
||||
\substitutefont{LGR}{\sfdefault}{cmss}
|
||||
\substitutefont{LGR}{\ttdefault}{cmtt}
|
||||
\substitutefont{X2}{\rmdefault}{cmr}
|
||||
\substitutefont{X2}{\sfdefault}{cmss}
|
||||
\substitutefont{X2}{\ttdefault}{cmtt}
|
||||
|
||||
but this is activated only under the condition that the
|
||||
``'fontenc'`` key is configured to load the ``LGR`` (Greek)
|
||||
and/or ``X2`` (Cyrillic) pdflatex-font encodings (if the
|
||||
:confval:`language` is set to a Cyrillic language, this
|
||||
``'fontpkg'`` key must be used as "times" package has no direct
|
||||
support for it; then keep only ``LGR`` lines from the above,
|
||||
if support is needed for Greek in the text).
|
||||
|
||||
The ``\substitutefont`` command is from the eponymous LaTeX
|
||||
package, which is loaded by Sphinx if needed (on Ubuntu xenial it
|
||||
is part of ``texlive-latex-extra`` which is a Sphinx
|
||||
requirement).
|
||||
|
||||
Only if the document actually does contain Unicode Greek letters
|
||||
(in text) or Cyrillic letters, will the above default set-up
|
||||
cause additional requirements for the PDF build. On Ubuntu
|
||||
xenial, ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and
|
||||
(with the above choice of fonts) the ``cm-super`` (or
|
||||
``cm-super-minimal``) package.
|
||||
|
||||
- For ``'xelatex'`` and ``'lualatex'``, the default is to
|
||||
use the FreeFont family: this OpenType font family
|
||||
supports both Cyrillic and Greek scripts and is available as
|
||||
separate Ubuntu xenial package ``fonts-freefont-otf``, it is not
|
||||
needed to install the big package ``texlive-fonts-extra``.
|
||||
|
||||
- ``'platex'`` (Japanese documents) engine supports individual
|
||||
Cyrillic and Greek letters with no need of extra user set-up.
|
||||
``'fncychap'``
|
||||
Inclusion of the "fncychap" package (which makes fancy chapter titles),
|
||||
default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation
|
||||
@@ -2034,6 +2103,8 @@ macros and environments, see also :doc:`/latex`.
|
||||
"fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and
|
||||
"Bjornstrup". You can also set this to ``''`` to disable fncychap.
|
||||
|
||||
The default is ``''`` for Japanese documents.
|
||||
|
||||
``'preamble'``
|
||||
Additional preamble content, default empty. See :doc:`/latex`.
|
||||
|
||||
@@ -2101,14 +2172,69 @@ macros and environments, see also :doc:`/latex`.
|
||||
.. versionadded:: 1.2
|
||||
|
||||
``'fontenc'``
|
||||
"fontenc" package inclusion, default ``'\\usepackage[T1]{fontenc}'``.
|
||||
"fontenc" package inclusion, defaults to
|
||||
``'\\usepackage[T1]{fontenc}'``.
|
||||
|
||||
If ``'pdflatex'`` is the :confval:`latex_engine`, one can add ``LGR``
|
||||
for support of Greek letters in the document, and also ``X2`` (or
|
||||
``T2A``) for Cyrillic letters, like this:
|
||||
|
||||
.. code-block:: latex
|
||||
|
||||
r'\usepackage[LGR,X2,T1]{fontenc}'
|
||||
|
||||
.. attention::
|
||||
|
||||
Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math
|
||||
mark-up. This is not the case anymore, and the above must be used
|
||||
(only in case of ``'pdflatex'`` engine) if the source contains such
|
||||
Unicode Greek.
|
||||
|
||||
On Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
|
||||
(for the latter, only if the ``'fontpkg'`` setting is left to its
|
||||
default) are needed for ``LGR`` to work. In place of ``cm-super``
|
||||
one can install smaller ``cm-super-minimal``, but it requires the
|
||||
LaTeX document to execute ``\usepackage[10pt]{type1ec}`` before
|
||||
loading ``fontenc``. Thus, use this key with this extra at its
|
||||
start if needed.
|
||||
|
||||
.. versionchanged:: 1.5
|
||||
Defaults to ``'\\usepackage{fontspec}'`` when
|
||||
:confval:`latex_engine` is ``'xelatex'``.
|
||||
.. versionchanged:: 1.6
|
||||
``'lualatex'`` also uses ``fontspec`` per default.
|
||||
``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``.
|
||||
.. versionchanged:: 2.0
|
||||
``'lualatex'`` executes
|
||||
``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX
|
||||
ligatures.
|
||||
.. versionchanged:: 2.0
|
||||
Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of
|
||||
occasional Greek or Cyrillic (``'pdflatex'`` only, as this support
|
||||
is provided natively by ``'platex'`` and only requires suitable
|
||||
font with ``'xelatex'/'lualatex'``).
|
||||
|
||||
``'textgreek'``
|
||||
The default (``'pdflatex'`` only) is
|
||||
``'\\usepackage{textalpha}'``, but only if ``'fontenc'`` was
|
||||
modified by user to include ``LGR`` option. If not, the key
|
||||
value will be forced to be the empty string.
|
||||
|
||||
This is needed for ``pdfLaTeX`` to support Unicode input of Greek
|
||||
letters such as φύσις. Expert users may want to load the ``textalpha``
|
||||
package with its option ``normalize-symbols``.
|
||||
|
||||
.. hint::
|
||||
|
||||
Unicode Greek (but no further Unicode symbols) in :rst:dir:`math`
|
||||
can be supported by ``'pdflatex'`` from setting this key to
|
||||
``r'\usepackage{textalpha,alphabeta}'``. Then ``:math:`α``` (U+03B1)
|
||||
will render as :math:`\alpha`. For wider Unicode support in math
|
||||
input, see the discussion of :confval:`latex_engine`.
|
||||
|
||||
With ``'platex'`` (Japanese), ``'xelatex'`` or ``'lualatex'``, this
|
||||
key is ignored.
|
||||
|
||||
.. versionadded:: 2.0
|
||||
``'geometry'``
|
||||
"geometry" package inclusion, the default definition is:
|
||||
|
||||
@@ -2153,10 +2279,22 @@ macros and environments, see also :doc:`/latex`.
|
||||
Previously this was done from inside :file:`sphinx.sty`.
|
||||
|
||||
``'maketitle'``
|
||||
"maketitle" call, default ``'\\maketitle'`` (but it has been
|
||||
redefined by the Sphinx ``manual`` and ``howto`` classes.) Override
|
||||
if you want to generate a differently-styled title page.
|
||||
"maketitle" call, default ``'\\sphinxmaketitle'``. Override
|
||||
if you want to generate a differently styled title page.
|
||||
|
||||
.. hint::
|
||||
|
||||
If the key value is set to
|
||||
``r'\newcommand\sphinxbackoftitlepage{<Extra
|
||||
material>}\sphinxmaketitle'``, then ``<Extra material>`` will be
|
||||
typeset on back of title page (``'manual'`` docclass only).
|
||||
|
||||
.. versionchanged:: 1.8.3
|
||||
Original ``\maketitle`` from document class is not overwritten,
|
||||
hence is re-usable as part of some custom setting for this key.
|
||||
.. versionadded:: 1.8.3
|
||||
``\sphinxbackoftitlepage`` optional macro. It can also be defined
|
||||
inside ``'preamble'`` key rather than this one.
|
||||
``'releasename'``
|
||||
value that prefixes ``'release'`` element on title page, default
|
||||
``'Release'``. As for *title* and *author* used in the tuples of
|
||||
@@ -2185,25 +2323,23 @@ macros and environments, see also :doc:`/latex`.
|
||||
Remove unneeded ``{}`` after ``\\hrule``.
|
||||
|
||||
``'printindex'``
|
||||
"printindex" call, the last thing in the file.
|
||||
|
||||
.. versionchanged:: 1.8
|
||||
Former default ``'\\printindex'`` now ``'\\sphinxprintindex'``.
|
||||
This macro works around an issue__ with PDF builds at RTD doing too
|
||||
few ``pdflatex`` runs.
|
||||
|
||||
__ https://github.com/rtfd/readthedocs.org/issues/2857
|
||||
"printindex" call, the last thing in the file, default
|
||||
``'\\printindex'``. Override if you want to generate the index
|
||||
differently or append some content after the index. For example
|
||||
``'\\footnotesize\\raggedright\\printindex'`` is advisable when the
|
||||
index is full of long entries.
|
||||
|
||||
``'fvset'``
|
||||
Customization of ``fancyvrb`` LaTeX package. Defaults to
|
||||
``'\\fvset{fontsize=\\small}'``, because default font (Courier) used in
|
||||
code-blocks is wider and taller than default text font (Times).
|
||||
|
||||
For ``'xelatex'`` and ``'lualatex'``, defaults to
|
||||
``'\\fvset{fontsize=auto}'``, because the default fonts are part of
|
||||
one unified typeface family (Latin Modern OpenType).
|
||||
Customization of ``fancyvrb`` LaTeX package. Sphinx does by default
|
||||
``'fvset': '\\fvset{fontsize=\\small}'``, to adjust for the large
|
||||
character width of the monospace font, used in code-blocks.
|
||||
You may need to modify this if you use custom fonts.
|
||||
|
||||
.. versionadded:: 1.8
|
||||
.. versionchanged:: 2.0
|
||||
Due to new default font choice for ``'xelatex'`` and ``'lualatex'``
|
||||
(FreeFont), Sphinx does ``\\fvset{fontsize=\\small}`` also with these
|
||||
engines (and not ``\\fvset{fontsize=auto}``).
|
||||
|
||||
* Keys that are set by other options and therefore should not be overridden
|
||||
are:
|
||||
@@ -2211,10 +2347,8 @@ macros and environments, see also :doc:`/latex`.
|
||||
``'docclass'``
|
||||
``'classoptions'``
|
||||
``'title'``
|
||||
``'date'``
|
||||
``'release'``
|
||||
``'author'``
|
||||
``'logo'``
|
||||
``'makeindex'``
|
||||
|
||||
.. confval:: latex_docclass
|
||||
|
||||
@@ -45,6 +45,10 @@ docstrings to correct reStructuredText before :mod:`autodoc` processes them.
|
||||
.. _NumPy:
|
||||
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
|
||||
|
||||
|
||||
Directives
|
||||
----------
|
||||
|
||||
:mod:`autodoc` provides several directives that are versions of the usual
|
||||
:rst:dir:`py:module`, :rst:dir:`py:class` and so forth. On parsing time, they
|
||||
import the corresponding module and extract the docstring of the given objects,
|
||||
@@ -114,8 +118,17 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
|
||||
.. autoclass:: Noodle
|
||||
:members: eat, slurp
|
||||
|
||||
* If you want to make the ``members`` option (or other flag options described
|
||||
below) the default, see :confval:`autodoc_default_flags`.
|
||||
* If you want to make the ``members`` option (or other options described
|
||||
below) the default, see :confval:`autodoc_default_options`.
|
||||
|
||||
.. tip::
|
||||
|
||||
You can use a negated form, :samp:`'no-{flag}'`, as an option of
|
||||
autodoc directive, to disable it temporarily. For example::
|
||||
|
||||
.. automodule:: foo
|
||||
:no-undoc-members:
|
||||
|
||||
|
||||
* Members without docstrings will be left out, unless you give the
|
||||
``undoc-members`` flag option::
|
||||
@@ -297,6 +310,9 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
|
||||
well-behaved decorating functions.
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
There are also new config values that you can set:
|
||||
|
||||
.. confval:: autoclass_content
|
||||
@@ -341,20 +357,39 @@ There are also new config values that you can set:
|
||||
This value is a list of autodoc directive flags that should be automatically
|
||||
applied to all autodoc directives. The supported flags are ``'members'``,
|
||||
``'undoc-members'``, ``'private-members'``, ``'special-members'``,
|
||||
``'inherited-members'``, ``'show-inheritance'`` and ``'ignore-module-all'``.
|
||||
|
||||
If you set one of these flags in this config value, you can use a negated
|
||||
form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.
|
||||
For example, if ``autodoc_default_flags`` is set to ``['members',
|
||||
'undoc-members']``, and you write a directive like this::
|
||||
|
||||
.. automodule:: foo
|
||||
:no-undoc-members:
|
||||
|
||||
the directive will be interpreted as if only ``:members:`` was given.
|
||||
``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'``
|
||||
and ``'exclude-members'``.
|
||||
|
||||
.. versionadded:: 1.0
|
||||
|
||||
.. deprecated:: 1.8
|
||||
|
||||
Integrated into :confval:`autodoc_default_options`.
|
||||
|
||||
.. confval:: autodoc_default_options
|
||||
|
||||
The default options for autodoc directives. They are applied to all autodoc
|
||||
directives automatically. It must be a dictionary which maps option names
|
||||
to the values. For example::
|
||||
|
||||
autodoc_default_options = {
|
||||
'members': 'var1, var2',
|
||||
'member-order': 'bysource',
|
||||
'special-members': '__init__',
|
||||
'undoc-members': None,
|
||||
'exclude-members': '__weakref__'
|
||||
}
|
||||
|
||||
Setting ``None`` is equivalent to giving the option name in the list format
|
||||
(i.e. it means "yes/true/on").
|
||||
|
||||
The supported options are ``'members'``, ``'member-order'``,
|
||||
``'undoc-members'``, ``'private-members'``, ``'special-members'``,
|
||||
``'inherited-members'``, ``'show-inheritance'``, ``'ignore-module-all'`` and
|
||||
``'exclude-members'``.
|
||||
|
||||
.. versionadded:: 1.8
|
||||
|
||||
.. confval:: autodoc_docstring_signature
|
||||
|
||||
Functions imported from C modules cannot be introspected, and therefore the
|
||||
@@ -405,6 +440,16 @@ There are also new config values that you can set:
|
||||
|
||||
.. versionadded:: 1.7
|
||||
|
||||
.. confval:: suppress_warnings
|
||||
:noindex:
|
||||
|
||||
:mod:`autodoc` supports to suppress warning messages via
|
||||
:confval:`suppress_warnings`. It allows following warnings types in
|
||||
addition:
|
||||
|
||||
* autodoc
|
||||
* autodoc.import_object
|
||||
|
||||
|
||||
Docstring preprocessing
|
||||
-----------------------
|
||||
|
||||
@@ -208,6 +208,8 @@ The following variables available in the templates:
|
||||
List containing names of all inherited members of class. Only available for
|
||||
classes.
|
||||
|
||||
.. versionadded:: 1.8.0
|
||||
|
||||
.. data:: functions
|
||||
|
||||
List containing names of "public" functions in the module. Here, "public"
|
||||
|
||||
@@ -198,6 +198,81 @@ The following is an example for the usage of the directives. The test via
|
||||
This parrot wouldn't voom if you put 3000 volts through it!
|
||||
|
||||
|
||||
Skipping tests conditionally
|
||||
----------------------------
|
||||
|
||||
``skipif``, a string option, can be used to skip directives conditionally. This
|
||||
may be useful e.g. when a different set of tests should be run depending on the
|
||||
environment (hardware, network/VPN, optional dependencies or different versions
|
||||
of dependencies). The ``skipif`` option is supported by all of the doctest
|
||||
directives. Below are typical use cases for ``skipif`` when used for different
|
||||
directives:
|
||||
|
||||
- :rst:dir:`testsetup` and :rst:dir:`testcleanup`
|
||||
|
||||
- conditionally skip test setup and/or cleanup
|
||||
- customize setup/cleanup code per environment
|
||||
|
||||
- :rst:dir:`doctest`
|
||||
|
||||
- conditionally skip both a test and its output verification
|
||||
|
||||
- :rst:dir:`testcode`
|
||||
|
||||
- conditionally skip a test
|
||||
- customize test code per environment
|
||||
|
||||
- :rst:dir:`testoutput`
|
||||
|
||||
- conditionally skip output assertion for a skipped test
|
||||
- expect different output depending on the environment
|
||||
|
||||
The value of the ``skipif`` option is evaluated as a Python expression. If the
|
||||
result is a true value, the directive is omitted from the test run just as if
|
||||
it wasn't present in the file at all.
|
||||
|
||||
Instead of repeating an expression, the :confval:`doctest_global_setup`
|
||||
configuration option can be used to assign it to a variable which can then be
|
||||
used instead.
|
||||
|
||||
Here's an example which skips some tests if Pandas is not installed:
|
||||
|
||||
.. code-block:: py
|
||||
:caption: conf.py
|
||||
|
||||
extensions = ['sphinx.ext.doctest']
|
||||
doctest_global_setup = '''
|
||||
try:
|
||||
import pandas as pd
|
||||
except ImportError:
|
||||
pd = None
|
||||
'''
|
||||
|
||||
.. code-block:: rst
|
||||
:caption: contents.rst
|
||||
|
||||
.. testsetup::
|
||||
:skipif: pd is None
|
||||
|
||||
data = pd.Series([42])
|
||||
|
||||
.. doctest::
|
||||
:skipif: pd is None
|
||||
|
||||
>>> data.iloc[0]
|
||||
42
|
||||
|
||||
.. testcode::
|
||||
:skipif: pd is None
|
||||
|
||||
print(data.iloc[-1])
|
||||
|
||||
.. testoutput::
|
||||
:skipif: pd is None
|
||||
|
||||
42
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""Example Google style docstrings.
|
||||
|
||||
This module demonstrates documentation as specified by the `Google Python
|
||||
@@ -178,7 +177,7 @@ class ExampleError(Exception):
|
||||
self.code = code
|
||||
|
||||
|
||||
class ExampleClass(object):
|
||||
class ExampleClass:
|
||||
"""The summary line for a class docstring should fit on one line.
|
||||
|
||||
If the class has public attributes, they may be documented here
|
||||
|
||||
@@ -1,4 +1,3 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
"""Example NumPy style docstrings.
|
||||
|
||||
This module demonstrates documentation as specified by the `NumPy
|
||||
@@ -223,7 +222,7 @@ class ExampleError(Exception):
|
||||
self.code = code
|
||||
|
||||
|
||||
class ExampleClass(object):
|
||||
class ExampleClass:
|
||||
"""The summary line for a class docstring should fit on one line.
|
||||
|
||||
If the class has public attributes, they may be documented here
|
||||
|
||||
@@ -54,7 +54,7 @@ It adds this directive:
|
||||
E D F
|
||||
"""
|
||||
|
||||
class A(object):
|
||||
class A:
|
||||
pass
|
||||
|
||||
class B(A):
|
||||
|
||||
@@ -168,6 +168,23 @@ Sphinx.
|
||||
|
||||
The default is empty (``{}``).
|
||||
|
||||
.. confval:: mathjax_config
|
||||
|
||||
The inline configuration options for mathjax. The value is used as a
|
||||
parameter of ``MathJax.Hub.Config()``. For more information, please
|
||||
read `Using in-line configuration options`_.
|
||||
|
||||
For example::
|
||||
|
||||
mathjax_config = {
|
||||
'extensions': ['tex2jax.js'],
|
||||
'jax': ['input/TeX', 'output/HTML-CSS'],
|
||||
}
|
||||
|
||||
The default is empty (not configured).
|
||||
|
||||
.. _Using in-line configuration options: https://docs.mathjax.org/en/latest/configuration.html#using-in-line-configuration-options
|
||||
|
||||
:mod:`sphinx.ext.jsmath` -- Render math via JavaScript
|
||||
------------------------------------------------------
|
||||
|
||||
|
||||
@@ -409,10 +409,10 @@ sure that "sphinx.ext.napoleon" is enabled in `conf.py`::
|
||||
|
||||
.. attribute:: attr1
|
||||
|
||||
*int*
|
||||
|
||||
Description of `attr1`
|
||||
|
||||
:type: int
|
||||
|
||||
.. confval:: napoleon_use_param
|
||||
|
||||
True to use a ``:param:`` role for each function parameter. False to
|
||||
|
||||
@@ -25,7 +25,11 @@ from the source to the description will also be inserted.
|
||||
|
||||
In addition, if you don't want to import the modules by ``viewcode``,
|
||||
you can tell the location of the location of source code to ``viewcode``
|
||||
using :event:`viewcode-find-source` event.
|
||||
using the :event:`viewcode-find-source` event.
|
||||
|
||||
If :confval:`viewcode_follow_imported_members` is enabled,
|
||||
you will also need to resolve imported attributes
|
||||
using the :event:`viewcode-follow-imported` event.
|
||||
|
||||
This extension works only on HTML related builders like ``html``,
|
||||
``applehelp``, ``devhelp``, ``htmlhelp``, ``qthelp`` and so on except
|
||||
@@ -83,3 +87,13 @@ Configuration
|
||||
|
||||
:param app: The Sphinx application object.
|
||||
:param modname: The name of the module to find source code for.
|
||||
|
||||
.. event:: viewcode-follow-imported (app, modname, attribute)
|
||||
|
||||
.. versionadded:: 1.8
|
||||
|
||||
Find the name of the original module for an attribute.
|
||||
|
||||
:param app: The Sphinx application object.
|
||||
:param modname: The name of the module that the attribute belongs to.
|
||||
:param attribute: The name of the member to follow.
|
||||
|
||||
@@ -12,10 +12,9 @@ Installing Sphinx
|
||||
Overview
|
||||
--------
|
||||
|
||||
Sphinx is written in `Python`__ and supports both Python 2.7 and Python 3.3+.
|
||||
We recommend the latter.
|
||||
Sphinx is written in `Python`__ and supports Python 3.5+.
|
||||
|
||||
__ http://docs.python-guide.org/en/latest/
|
||||
__ https://docs.python-guide.org/
|
||||
|
||||
|
||||
Linux
|
||||
@@ -73,7 +72,7 @@ Homebrew
|
||||
|
||||
For more information, refer to the `package overview`__.
|
||||
|
||||
__ http://formulae.brew.sh/formula/sphinx-doc
|
||||
__ https://formulae.brew.sh/formula/sphinx-doc
|
||||
|
||||
MacPorts
|
||||
~~~~~~~~
|
||||
@@ -121,9 +120,9 @@ Once Python is installed, you can install Sphinx using :command:`pip`. Refer
|
||||
to the :ref:`pip installation instructions <install-pypi>` below for more
|
||||
information.
|
||||
|
||||
__ http://docs.python-guide.org/en/latest/
|
||||
__ http://docs.python-guide.org/en/latest/starting/install3/win/
|
||||
__ http://docs.python-guide.org/en/latest/starting/install/win/
|
||||
__ https://docs.python-guide.org/
|
||||
__ https://docs.python-guide.org/starting/install3/win/
|
||||
__ https://docs.python-guide.org/starting/install/win/
|
||||
|
||||
|
||||
.. _install-pypi:
|
||||
|
||||
@@ -15,7 +15,7 @@ parsing the `CommonMark`__ Markdown flavor.
|
||||
__ https://daringfireball.net/projects/markdown/
|
||||
__ https://recommonmark.readthedocs.io/en/latest/index.html
|
||||
__ https://github.com/rtfd/CommonMark-py
|
||||
__ http://commonmark.org/
|
||||
__ https://commonmark.org/
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
@@ -320,8 +320,8 @@ More topics to be covered
|
||||
|
||||
- :doc:`Other extensions </usage/extensions/index>`:
|
||||
- Static files
|
||||
- :doc:`Selecting a theme </theming>`
|
||||
- :doc:`/setuptools`
|
||||
- :doc:`Selecting a theme </usage/theming>`
|
||||
- :doc:`/usage/advanced/setuptools`
|
||||
- :ref:`Templating <templating>`
|
||||
- Using extensions
|
||||
- :ref:`Writing extensions <dev-extensions>`
|
||||
|
||||
@@ -1063,6 +1063,15 @@ or use Python raw strings (``r"raw"``).
|
||||
|
||||
.. _AmSMath LaTeX package: https://www.ams.org/publications/authors/tex/amslatex
|
||||
|
||||
.. seealso::
|
||||
|
||||
:ref:`math-support`
|
||||
Rendering options for math with HTML builders.
|
||||
|
||||
:confval:`latex_engine`
|
||||
Explains how to configure LaTeX builder to support Unicode literals in
|
||||
math mark-up.
|
||||
|
||||
|
||||
Grammar production displays
|
||||
---------------------------
|
||||
|
||||
@@ -850,8 +850,8 @@ 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++.
|
||||
|
||||
Inline Expressions and Tpes
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Inline Expressions and Types
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. rst:role:: cpp:expr
|
||||
cpp:texpr
|
||||
@@ -1005,20 +1005,46 @@ These roles link to the given declaration types:
|
||||
When a custom title is not needed it may be useful to use the roles for inline expressions,
|
||||
:rst:role:`cpp:expr` and :rst:role:`cpp:texpr`, where angle brackets do not need escaping.
|
||||
|
||||
.. admonition:: Note on References to Overloaded Functions
|
||||
|
||||
It is currently impossible to link to a specific version of an overloaded
|
||||
function. Currently the C++ domain is the first domain that has basic
|
||||
support for overloaded functions and until there is more data for comparison
|
||||
we don't want to select a bad syntax to reference a specific overload.
|
||||
Currently Sphinx will link to the first overloaded version of the function.
|
||||
|
||||
Declarations without template parameters and template arguments
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
For linking to non-templated declarations the name must be a nested name, e.g.,
|
||||
``f`` or ``MyClass::f``.
|
||||
|
||||
|
||||
Overloaded (member) functions
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
When a (member) function is referenced using just its name, the reference
|
||||
will point to an arbitrary matching overload.
|
||||
The :rst:role:`cpp:any` and :rst:role:`cpp:func` roles will an alternative
|
||||
format, which simply is a complete function declaration.
|
||||
This will resolve to the exact matching overload.
|
||||
As example, consider the following class declaration:
|
||||
|
||||
.. cpp:namespace-push:: overload_example
|
||||
.. cpp:class:: C
|
||||
|
||||
.. cpp:function:: void f(double d) const
|
||||
.. cpp:function:: void f(double d)
|
||||
.. cpp:function:: void f(int i)
|
||||
.. cpp:function:: void f()
|
||||
|
||||
References using the :rst:role:`cpp:func` role:
|
||||
|
||||
- Arbitrary overload: ``C::f``, :cpp:func:`C::f`
|
||||
- Also arbitrary overload: ``C::f()``, :cpp:func:`C::f()`
|
||||
- Specific overload: ``void C::f()``, :cpp:func:`void C::f()`
|
||||
- Specific overload: ``void C::f(int)``, :cpp:func:`void C::f(int)`
|
||||
- Specific overload: ``void C::f(double)``, :cpp:func:`void C::f(double)`
|
||||
- Specific overload: ``void C::f(double) const``, :cpp:func:`void C::f(double) const`
|
||||
|
||||
Note that the :confval:`add_function_parentheses` configuration variable
|
||||
does not influence specific overload references.
|
||||
|
||||
.. cpp:namespace-pop::
|
||||
|
||||
|
||||
Templated declarations
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -1033,19 +1059,25 @@ Assume the following declarations.
|
||||
Inner
|
||||
|
||||
In general the reference must include the template parameter 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.
|
||||
and template arguments for the prefix of qualified names. For example:
|
||||
|
||||
The inner class template cannot 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.
|
||||
- ``template\<typename TOuter> Wrapper::Outer``
|
||||
(:cpp:class:`template\<typename TOuter> Wrapper::Outer`)
|
||||
- ``template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner``
|
||||
(:cpp:class:`template\<typename TOuter> template\<typename TInner> Wrapper::Outer<TOuter>::Inner`)
|
||||
|
||||
- ``Wrapper::Outer`` (:cpp:class:`Wrapper::Outer`)
|
||||
- ``Wrapper::Outer::Inner`` (:cpp:class:`Wrapper::Outer::Inner`)
|
||||
Currently the lookup only succeed if the template parameter identifiers are equal strings.
|
||||
That is, ``template\<typename UOuter> Wrapper::Outer`` will not work.
|
||||
|
||||
As a shorthand notation, if a template parameter list is omitted,
|
||||
then the lookup will assume either a primary template or a non-template,
|
||||
but not a partial template specialisation.
|
||||
This means the following references work as well:
|
||||
|
||||
- ``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`)
|
||||
|
||||
@@ -1325,6 +1357,25 @@ These roles are provided to refer to the described objects:
|
||||
.. rst:role:: rst:dir
|
||||
rst:role
|
||||
|
||||
.. _math-domain:
|
||||
|
||||
The Math Domain
|
||||
---------------
|
||||
|
||||
The math domain (name **math**) provides the following roles::
|
||||
|
||||
.. rst:role:: math:numref
|
||||
|
||||
Role for cross-referencing equations defined by :rst:dir:`math` directive
|
||||
via their label. Example::
|
||||
|
||||
.. math:: e^{i\pi} + 1 = 0
|
||||
:label: euler
|
||||
|
||||
Euler's identity, equation :math:numref:`euler`, was elected one of the
|
||||
most beautiful mathematical formulas.
|
||||
|
||||
.. versionadded:: 1.8
|
||||
|
||||
More domains
|
||||
------------
|
||||
|
||||
@@ -288,13 +288,7 @@ Math
|
||||
|
||||
.. rst:role:: eq
|
||||
|
||||
Role for cross-referencing equations via their label. Example::
|
||||
|
||||
.. math:: e^{i\pi} + 1 = 0
|
||||
:label: euler
|
||||
|
||||
Euler's identity, equation :eq:`euler`, was elected one of the most
|
||||
beautiful mathematical formulas.
|
||||
Same as :rst:role:`math:numref`.
|
||||
|
||||
|
||||
Other semantic markup
|
||||
|
||||
339
doc/usage/theming.rst
Normal file
339
doc/usage/theming.rst
Normal file
@@ -0,0 +1,339 @@
|
||||
.. highlight:: python
|
||||
|
||||
HTML
|
||||
====
|
||||
|
||||
Sphinx provides a number of builders for HTML and HTML-based formats.
|
||||
|
||||
Builders
|
||||
--------
|
||||
|
||||
.. todo:: Populate when the 'builders' document is split up.
|
||||
|
||||
|
||||
Themes
|
||||
------
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
.. note::
|
||||
|
||||
This section provides information about using pre-existing HTML themes. If
|
||||
you wish to create your own theme, refer to :doc:`/theming`.
|
||||
|
||||
Sphinx supports changing the appearance of its HTML output via *themes*. A
|
||||
theme is a collection of HTML templates, stylesheet(s) and other static files.
|
||||
Additionally, it has a configuration file which specifies from which theme to
|
||||
inherit, which highlighting style to use, and what options exist for customizing
|
||||
the theme's look and feel.
|
||||
|
||||
Themes are meant to be project-unaware, so they can be used for different
|
||||
projects without change.
|
||||
|
||||
Using a theme
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Using a :ref:`theme provided with Sphinx <builtin-themes>` is easy. Since these
|
||||
do not need to be installed, you only need to set the :confval:`html_theme`
|
||||
config value. For example, to enable the ``classic`` theme, add the following
|
||||
to :file:`conf.py`::
|
||||
|
||||
html_theme = "classic"
|
||||
|
||||
You can also set theme-specific options using the :confval:`html_theme_options`
|
||||
config value. These options are generally used to change the look and feel of
|
||||
the theme. For example, to place the sidebar on the right side and a black
|
||||
background for the relation bar (the bar with the navigation links at the
|
||||
page's top and bottom), add the following :file:`conf.py`::
|
||||
|
||||
html_theme_options = {
|
||||
"rightsidebar": "true",
|
||||
"relbarbgcolor": "black"
|
||||
}
|
||||
|
||||
If the theme does not come with Sphinx, it can be in two static forms or as a
|
||||
Python package. For the static forms, either a directory (containing
|
||||
:file:`theme.conf` and other needed files), or a zip file with the same
|
||||
contents is supported. The directory or zipfile must be put where Sphinx can
|
||||
find it; for this there is the config value :confval:`html_theme_path`. This
|
||||
can be a list of directories, relative to the directory containing
|
||||
:file:`conf.py`, that can contain theme directories or zip files. For example,
|
||||
if you have a theme in the file :file:`blue.zip`, you can put it right in the
|
||||
directory containing :file:`conf.py` and use this configuration::
|
||||
|
||||
html_theme = "blue"
|
||||
html_theme_path = ["."]
|
||||
|
||||
The third form is a Python package. If a theme you want to use is distributed
|
||||
as a Python package, you can use it after installing
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# installing theme package
|
||||
$ pip install sphinxjp.themes.dotted
|
||||
|
||||
Once installed, this can be used in the same manner as a directory or
|
||||
zipfile-based theme::
|
||||
|
||||
html_theme = "dotted"
|
||||
|
||||
For more information on the design of themes, including information about
|
||||
writing your own themes, refer to :doc:`/theming`.
|
||||
|
||||
.. _builtin-themes:
|
||||
|
||||
Builtin themes
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. cssclass:: longtable
|
||||
|
||||
+--------------------+--------------------+
|
||||
| **Theme overview** | |
|
||||
+--------------------+--------------------+
|
||||
| |alabaster| | |classic| |
|
||||
| | |
|
||||
| *alabaster* | *classic* |
|
||||
+--------------------+--------------------+
|
||||
| |sphinxdoc| | |scrolls| |
|
||||
| | |
|
||||
| *sphinxdoc* | *scrolls* |
|
||||
+--------------------+--------------------+
|
||||
| |agogo| | |traditional| |
|
||||
| | |
|
||||
| *agogo* | *traditional* |
|
||||
+--------------------+--------------------+
|
||||
| |nature| | |haiku| |
|
||||
| | |
|
||||
| *nature* | *haiku* |
|
||||
+--------------------+--------------------+
|
||||
| |pyramid| | |bizstyle| |
|
||||
| | |
|
||||
| *pyramid* | *bizstyle* |
|
||||
+--------------------+--------------------+
|
||||
|
||||
.. |alabaster| image:: /_static/themes/alabaster.png
|
||||
.. |classic| image:: /_static/themes/classic.png
|
||||
.. |sphinxdoc| image:: /_static/themes/sphinxdoc.png
|
||||
.. |scrolls| image:: /_static/themes/scrolls.png
|
||||
.. |agogo| image:: /_static/themes/agogo.png
|
||||
.. |traditional| image:: /_static/themes/traditional.png
|
||||
.. |nature| image:: /_static/themes/nature.png
|
||||
.. |haiku| image:: /_static/themes/haiku.png
|
||||
.. |pyramid| image:: /_static/themes/pyramid.png
|
||||
.. |bizstyle| image:: /_static/themes/bizstyle.png
|
||||
|
||||
Sphinx comes with a selection of themes to choose from.
|
||||
|
||||
.. cssclass:: clear
|
||||
|
||||
These themes are:
|
||||
|
||||
**basic**
|
||||
This is a basically unstyled layout used as the base for the
|
||||
other themes, and usable as the base for custom themes as well. The HTML
|
||||
contains all important elements like sidebar and relation bar. There are
|
||||
these options (which are inherited by the other themes):
|
||||
|
||||
- **nosidebar** (true or false): Don't include the sidebar. Defaults to
|
||||
``False``.
|
||||
|
||||
- **sidebarwidth** (int or str): Width of the sidebar in pixels.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Defaults to 230 pixels.
|
||||
|
||||
- **body_min_width** (int or str): Minimal width of the document body.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Use 0 if you don't want
|
||||
a width limit. Defaults may depend on the theme (often 450px).
|
||||
|
||||
- **body_max_width** (int or str): Maximal width of the document body.
|
||||
This can be an int, which is interpreted as pixels or a valid CSS
|
||||
dimension string such as '70em' or '50%'. Use 'none' if you don't
|
||||
want a width limit. Defaults may depend on the theme (often 800px).
|
||||
|
||||
**alabaster**
|
||||
`Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
|
||||
(especially as used in his Requests project), which was itself originally
|
||||
based on @mitsuhiko's theme used for Flask & related projects. Refer to its
|
||||
`installation page`_ for information on how to configure
|
||||
:confval:`html_sidebars` for its use.
|
||||
|
||||
.. _Alabaster theme: https://pypi.org/project/alabaster/
|
||||
.. _installation page: https://alabaster.readthedocs.io/en/latest/installation.html
|
||||
|
||||
**classic**
|
||||
This is the classic theme, which looks like `the Python 2
|
||||
documentation <https://docs.python.org/2/>`_. It can be customized via
|
||||
these options:
|
||||
|
||||
- **rightsidebar** (true or false): Put the sidebar on the right side.
|
||||
Defaults to ``False``.
|
||||
|
||||
- **stickysidebar** (true or false): Make the sidebar "fixed" so that it
|
||||
doesn't scroll out of view for long body content. This may not work well
|
||||
with all browsers. Defaults to ``False``.
|
||||
|
||||
- **collapsiblesidebar** (true or false): Add an *experimental* JavaScript
|
||||
snippet that makes the sidebar collapsible via a button on its side.
|
||||
Defaults to ``False``.
|
||||
|
||||
- **externalrefs** (true or false): Display external links differently from
|
||||
internal links. Defaults to ``False``.
|
||||
|
||||
There are also various color and font options that can change the color scheme
|
||||
without having to write a custom stylesheet:
|
||||
|
||||
- **footerbgcolor** (CSS color): Background color for the footer line.
|
||||
- **footertextcolor** (CSS color): Text color for the footer line.
|
||||
- **sidebarbgcolor** (CSS color): Background color for the sidebar.
|
||||
- **sidebarbtncolor** (CSS color): Background color for the sidebar collapse
|
||||
button (used when *collapsiblesidebar* is ``True``).
|
||||
- **sidebartextcolor** (CSS color): Text color for the sidebar.
|
||||
- **sidebarlinkcolor** (CSS color): Link color for the sidebar.
|
||||
- **relbarbgcolor** (CSS color): Background color for the relation bar.
|
||||
- **relbartextcolor** (CSS color): Text color for the relation bar.
|
||||
- **relbarlinkcolor** (CSS color): Link color for the relation bar.
|
||||
- **bgcolor** (CSS color): Body background color.
|
||||
- **textcolor** (CSS color): Body text color.
|
||||
- **linkcolor** (CSS color): Body link color.
|
||||
- **visitedlinkcolor** (CSS color): Body color for visited links.
|
||||
- **headbgcolor** (CSS color): Background color for headings.
|
||||
- **headtextcolor** (CSS color): Text color for headings.
|
||||
- **headlinkcolor** (CSS color): Link color for headings.
|
||||
- **codebgcolor** (CSS color): Background color for code blocks.
|
||||
- **codetextcolor** (CSS color): Default text color for code blocks, if not
|
||||
set differently by the highlighting style.
|
||||
|
||||
- **bodyfont** (CSS font-family): Font for normal text.
|
||||
- **headfont** (CSS font-family): Font for headings.
|
||||
|
||||
**sphinxdoc**
|
||||
The theme originally used by this documentation. It features
|
||||
a sidebar on the right side. There are currently no options beyond
|
||||
*nosidebar* and *sidebarwidth*.
|
||||
|
||||
.. note::
|
||||
|
||||
The Sphinx documentation now uses
|
||||
`an adjusted version of the sphinxdoc theme
|
||||
<https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_.
|
||||
|
||||
**scrolls**
|
||||
A more lightweight theme, based on `the Jinja documentation
|
||||
<http://jinja.pocoo.org/>`_. The following color options are available:
|
||||
|
||||
- **headerbordercolor**
|
||||
- **subheadlinecolor**
|
||||
- **linkcolor**
|
||||
- **visitedlinkcolor**
|
||||
- **admonitioncolor**
|
||||
|
||||
**agogo**
|
||||
A theme created by Andi Albrecht. The following options are supported:
|
||||
|
||||
- **bodyfont** (CSS font family): Font for normal text.
|
||||
- **headerfont** (CSS font family): Font for headings.
|
||||
- **pagewidth** (CSS length): Width of the page content, default 70em.
|
||||
- **documentwidth** (CSS length): Width of the document (without sidebar),
|
||||
default 50em.
|
||||
- **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
|
||||
- **bgcolor** (CSS color): Background color.
|
||||
- **headerbg** (CSS value for "background"): background for the header area,
|
||||
default a grayish gradient.
|
||||
- **footerbg** (CSS value for "background"): background for the footer area,
|
||||
default a light gray gradient.
|
||||
- **linkcolor** (CSS color): Body link color.
|
||||
- **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
|
||||
headings.
|
||||
- **headerlinkcolor** (CSS color): Color for the backreference link in
|
||||
headings.
|
||||
- **textalign** (CSS *text-align* value): Text alignment for the body, default
|
||||
is ``justify``.
|
||||
|
||||
**nature**
|
||||
A greenish theme. There are currently no options beyond
|
||||
*nosidebar* and *sidebarwidth*.
|
||||
|
||||
**pyramid**
|
||||
A theme from the Pyramid web framework project, designed by Blaise Laflamme.
|
||||
There are currently no options beyond *nosidebar* and *sidebarwidth*.
|
||||
|
||||
**haiku**
|
||||
A theme without sidebar inspired by the `Haiku OS user guide
|
||||
<https://www.haiku-os.org/docs/userguide/en/contents.html>`_. The following
|
||||
options are supported:
|
||||
|
||||
- **full_logo** (true or false, default ``False``): If this is true, the
|
||||
header will only show the :confval:`html_logo`. Use this for large logos.
|
||||
If this is false, the logo (if present) will be shown floating right, and
|
||||
the documentation title will be put in the header.
|
||||
|
||||
- **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**,
|
||||
**hoverlinkcolor** (CSS colors): Colors for various body elements.
|
||||
|
||||
**traditional**
|
||||
A theme resembling the old Python documentation. There are
|
||||
currently no options beyond *nosidebar* and *sidebarwidth*.
|
||||
|
||||
**epub**
|
||||
A theme for the epub builder. This theme tries to save visual
|
||||
space which is a sparse resource on ebook readers. The following options
|
||||
are supported:
|
||||
|
||||
- **relbar1** (true or false, default ``True``): If this is true, the
|
||||
`relbar1` block is inserted in the epub output, otherwise it is omitted.
|
||||
|
||||
- **footer** (true or false, default ``True``): If this is true, the
|
||||
`footer` block is inserted in the epub output, otherwise it is omitted.
|
||||
|
||||
**bizstyle**
|
||||
A simple bluish theme. The following options are supported
|
||||
beyond *nosidebar* and *sidebarwidth*:
|
||||
|
||||
- **rightsidebar** (true or false): Put the sidebar on the right side.
|
||||
Defaults to ``False``.
|
||||
|
||||
.. versionadded:: 1.3
|
||||
'alabaster', 'sphinx_rtd_theme' and 'bizstyle' theme.
|
||||
|
||||
.. versionchanged:: 1.3
|
||||
The 'default' theme has been renamed to 'classic'. 'default' is still
|
||||
available, however it will emit a notice that it is an alias for the new
|
||||
'alabaster' theme.
|
||||
|
||||
Third Party Themes
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. cssclass:: longtable
|
||||
|
||||
+--------------------+--------------------+
|
||||
| **Theme overview** | |
|
||||
+--------------------+--------------------+
|
||||
| |sphinx_rtd_theme| | |
|
||||
| | |
|
||||
| *sphinx_rtd_theme* | |
|
||||
+--------------------+--------------------+
|
||||
|
||||
.. |sphinx_rtd_theme| image:: /_static/themes/sphinx_rtd_theme.png
|
||||
|
||||
There are many third-party themes available. Some of these are general use,
|
||||
while others are specific to an individual project. A section of third-party
|
||||
themes is listed below. Many more can be found on PyPI__, GitHub__ and
|
||||
sphinx-themes.org__.
|
||||
|
||||
.. cssclass:: clear
|
||||
|
||||
**sphinx_rtd_theme**
|
||||
`Read the Docs Sphinx Theme`_.
|
||||
This is a mobile-friendly sphinx theme that was made for readthedocs.org.
|
||||
View a working demo over on readthedocs.org. You can get install and options
|
||||
information at `Read the Docs Sphinx Theme`_ page.
|
||||
|
||||
.. _Read the Docs Sphinx Theme: https://pypi.org/project/sphinx_rtd_theme/
|
||||
|
||||
.. versionchanged:: 1.4
|
||||
**sphinx_rtd_theme** has become optional.
|
||||
|
||||
.. __: https://pypi.org/search/?q=&o=&c=Framework+%3A%3A+Sphinx+%3A%3A+Theme
|
||||
.. __: https://github.com/search?utf8=%E2%9C%93&q=sphinx+theme&type=
|
||||
.. __: https://sphinx-themes.org/
|
||||
Reference in New Issue
Block a user