{%trans path=pathto('ext/builtins')%}Extensions: automatic testing of code snippets, inclusion of
docstrings from Python modules (API docs), and
more{%endtrans%}
@@ -38,10 +38,10 @@
most of them installable from PyPI{%endtrans%}
{%trans%}
- Sphinx uses reStructuredText
+ Sphinx uses reStructuredText
as its markup language, and many of its strengths come from the power and
straightforwardness of reStructuredText and its parsing and translating
- suite, the Docutils.{%endtrans%}
+ suite, the Docutils.{%endtrans%}
diff --git a/doc/conf.py b/doc/conf.py
index 3eb01b5ea..add9e8d61 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -35,7 +35,7 @@ htmlhelp_basename = 'Sphinxdoc'
epub_theme = 'epub'
epub_basename = 'sphinx'
epub_author = 'Georg Brandl'
-epub_publisher = 'http://sphinx-doc.org/'
+epub_publisher = 'https://sphinx-doc.org/'
epub_uid = 'web-site'
epub_scheme = 'url'
epub_identifier = epub_publisher
@@ -80,11 +80,11 @@ latex_use_xindy = True
autodoc_member_order = 'groupwise'
autosummary_generate = False
todo_include_todos = True
-extlinks = {'duref': ('http://docutils.sourceforge.net/docs/ref/rst/'
+extlinks = {'duref': ('https://docutils.sourceforge.io/docs/ref/rst/'
'restructuredtext.html#%s', ''),
- 'durole': ('http://docutils.sourceforge.net/docs/ref/rst/'
+ 'durole': ('https://docutils.sourceforge.io/docs/ref/rst/'
'roles.html#%s', ''),
- 'dudir': ('http://docutils.sourceforge.net/docs/ref/rst/'
+ 'dudir': ('https://docutils.sourceforge.io/docs/ref/rst/'
'directives.html#%s', '')}
man_pages = [
diff --git a/doc/contents.rst b/doc/contents.rst
index eb6946292..21a27e233 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -7,6 +7,7 @@ Sphinx documentation contents
:maxdepth: 2
usage/index
+ tutorial/index
development/index
man/index
diff --git a/doc/development/theming.rst b/doc/development/theming.rst
index 5de10158a..da2c644b9 100644
--- a/doc/development/theming.rst
+++ b/doc/development/theming.rst
@@ -207,9 +207,9 @@ inside your module:
First, define the registration function, which accepts the arguments for
:event:`html-page-context`.
-Within the registration function, define the template function that you'd like to use
-within Jinja. The template function should return a string or Python objects (lists,
-dictionaries) with strings inside that Jinja uses in the templating process
+Within the registration function, define the template function that you'd like to
+use within Jinja. The template function should return a string or Python objects
+(lists, dictionaries) with strings inside that Jinja uses in the templating process
.. note::
diff --git a/doc/development/tutorials/helloworld.rst b/doc/development/tutorials/helloworld.rst
index 6eae5d6a3..2273330f1 100644
--- a/doc/development/tutorials/helloworld.rst
+++ b/doc/development/tutorials/helloworld.rst
@@ -181,9 +181,9 @@ This is the very basic principle of an extension that creates a new directive.
For a more advanced example, refer to :doc:`todo`.
-.. _docutils: http://docutils.sourceforge.net/
-.. _docutils directives: http://docutils.sourceforge.net/docs/howto/rst-directives.html
-.. _docutils nodes: http://docutils.sourceforge.net/docs/ref/doctree.html
+.. _docutils: https://docutils.sourceforge.io/
+.. _docutils directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html
+.. _docutils nodes: https://docutils.sourceforge.io/docs/ref/doctree.html
.. _PyPI: https://pypi.org/
.. _Python package: https://packaging.python.org/
.. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
diff --git a/doc/development/tutorials/recipe.rst b/doc/development/tutorials/recipe.rst
index 404be542f..0e96a45cb 100644
--- a/doc/development/tutorials/recipe.rst
+++ b/doc/development/tutorials/recipe.rst
@@ -223,4 +223,4 @@ Further reading
For more information, refer to the `docutils`_ documentation and
:doc:`/extdev/index`.
-.. _docutils: http://docutils.sourceforge.net/docs/
+.. _docutils: https://docutils.sourceforge.io/docs/
diff --git a/doc/development/tutorials/todo.rst b/doc/development/tutorials/todo.rst
index 21d9e74be..c0a5c0d87 100644
--- a/doc/development/tutorials/todo.rst
+++ b/doc/development/tutorials/todo.rst
@@ -105,7 +105,7 @@ is just a "general" node.
Many extensions will not have to create their own node classes and work fine
with the nodes already provided by `docutils
- `__ and :ref:`Sphinx
+ `__ and :ref:`Sphinx
`.
.. attention::
@@ -362,6 +362,6 @@ For more information, refer to the `docutils`_ documentation and
:doc:`/extdev/index`.
-.. _docutils: http://docutils.sourceforge.net/docs/
+.. _docutils: https://docutils.sourceforge.io/docs/
.. _Python path: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
-.. _docutils documentation: http://docutils.sourceforge.net/docs/ref/rst/directives.html
+.. _docutils documentation: https://docutils.sourceforge.io/docs/ref/rst/directives.html
diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst
index 41318e9d6..7c331382c 100644
--- a/doc/extdev/appapi.rst
+++ b/doc/extdev/appapi.rst
@@ -159,7 +159,9 @@ connect handlers to the events. Example:
Below is an overview of each event that happens during a build. In the list
below, we include the event name, its callback parameters, and the input and output
-type for that event::
+type for that event:
+
+.. code-block:: none
1. event.config-inited(app,config)
2. event.builder-inited(app)
@@ -168,7 +170,7 @@ type for that event::
for docname in docnames:
5. event.env-purge-doc(app, env, docname)
-
+
if doc changed and not removed:
6. source-read(app, docname, source)
7. run source parsers: text -> docutils.document
@@ -176,10 +178,10 @@ type for that event::
8. apply transforms based on priority: docutils.document -> docutils.document
- event.doctree-read(app, doctree) is called in the middle of transforms,
transforms come before/after this event depending on their priority.
-
+
9. event.env-merge-info(app, env, docnames, other)
- if running in parallel mode, this event will be emitted for each process
-
+
10. event.env-updated(app, env)
11. event.env-get-updated(app, env)
12. event.env-check-consistency(app, env)
@@ -377,13 +379,22 @@ Here is a more detailed list of these events.
``'page.html'`` as the HTML template for this page.
.. note:: You can install JS/CSS files for the specific page via
- :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since v3.5.0.
+ :meth:`Sphinx.add_js_file` and :meth:`Sphinx.add_css_file` since
+ v3.5.0.
.. versionadded:: 0.4
.. versionchanged:: 1.3
The return value can now specify a template name.
+.. event:: linkcheck-process-uri (app, uri)
+
+ Emitted when the linkcheck builder collects hyperlinks from document. *uri*
+ is a collected URI. The event handlers can modify the URI by returning a
+ string.
+
+ .. versionadded:: 4.1
+
.. event:: build-finished (app, exception)
Emitted when a build has finished, before Sphinx exits, usually used for
diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst
index 514a80541..c35b0525b 100644
--- a/doc/extdev/deprecated.rst
+++ b/doc/extdev/deprecated.rst
@@ -22,6 +22,21 @@ The following is a list of deprecated interfaces.
- (will be) Removed
- Alternatives
+ * - The optional argument ``app`` for ``sphinx.environment.BuildEnvironment``
+ - 4.1
+ - 6.0
+ - The required argument
+
+ * - ``sphinx.application.Sphinx.html_theme``
+ - 4.1
+ - 6.0
+ - ``sphinx.registry.SphinxComponentRegistry.html_themes``
+
+ * - ``sphinx.ext.autosummary._app``
+ - 4.1
+ - 6.0
+ - N/A
+
* - ``sphinx.util.docstrings.extract_metadata()``
- 4.1
- 6.0
@@ -40,12 +55,12 @@ The following is a list of deprecated interfaces.
* - ``sphinx.directives.patches.ListTable``
- 4.0
- 6.0
- - ``docutils.parsers.rst.diretives.tables.ListSVTable``
+ - ``docutils.parsers.rst.directives.tables.ListSVTable``
* - ``sphinx.directives.patches.RSTTable``
- 4.0
- 6.0
- - ``docutils.parsers.rst.diretives.tables.RSTTable``
+ - ``docutils.parsers.rst.directives.tables.RSTTable``
* - ``sphinx.ext.autodoc.directive.DocumenterBridge.filename_set``
- 4.0
@@ -85,7 +100,7 @@ The following is a list of deprecated interfaces.
* - ``sphinx.util.smartypants``
- 4.0
- 6.0
- - ``docutils.utils.smartyquotes``
+ - ``docutils.utils.smartquotes``
* - ``sphinx.util.typing.DirectiveOption``
- 4.0
diff --git a/doc/extdev/i18n.rst b/doc/extdev/i18n.rst
index 75ef36cc5..6b32b8b73 100644
--- a/doc/extdev/i18n.rst
+++ b/doc/extdev/i18n.rst
@@ -94,4 +94,4 @@ message catalog template and message catalogs, for example via `Babel`_:
$ pybabel extract --output=src/locale/myextension.pot src/
$ pybabel update --input-file=src/locale/myextension.pot --domain=myextension --output-dir=src/locale
-.. _Babel: http://babel.pocoo.org/
+.. _Babel: https://babel.pocoo.org/
diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst
index d9c04f413..d210ee49b 100644
--- a/doc/extdev/index.rst
+++ b/doc/extdev/index.rst
@@ -112,7 +112,7 @@ in which a Sphinx project is built: this works in several phases.
existing files are read, temporary nodes are created.
There are nodes provided by docutils, which are documented `in the docutils
- documentation `__.
+ documentation `__.
Additional nodes are provided by Sphinx and :ref:`documented here `.
During reading, the build environment is updated with all meta- and cross
diff --git a/doc/extdev/markupapi.rst b/doc/extdev/markupapi.rst
index 7a21f8126..8fc884d7c 100644
--- a/doc/extdev/markupapi.rst
+++ b/doc/extdev/markupapi.rst
@@ -149,4 +149,4 @@ return ``node.children`` from the Directive.
`Creating directives`_ HOWTO of the Docutils documentation
-.. _Creating directives: http://docutils.sourceforge.net/docs/howto/rst-directives.html
+.. _Creating directives: https://docutils.sourceforge.io/docs/howto/rst-directives.html
diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst
index 0beb51711..1bd03fd09 100644
--- a/doc/extdev/parserapi.rst
+++ b/doc/extdev/parserapi.rst
@@ -8,7 +8,7 @@ Parser API
The Parser analyzes the input document and creates a node tree
representation.
-__ http://docutils.sourceforge.net/docs/dev/hacking.html#parsing-the-document
+__ https://docutils.sourceforge.io/docs/dev/hacking.html#parsing-the-document
In Sphinx, the parser modules works as same as docutils. The parsers are
registered to Sphinx by extensions using Application APIs;
diff --git a/doc/faq.rst b/doc/faq.rst
index 49723d134..4b273023d 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -145,7 +145,7 @@ Google Search
.. _Getting Started: https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
.. _api role: https://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
-.. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
+.. _xhtml to reST: https://docutils.sourceforge.io/sandbox/xhtml2rest/xhtml2rest.py
Sphinx vs. Docutils
@@ -179,10 +179,10 @@ of the *writers* provided by docutils. This allows Sphinx to provide many
features that would simply not be possible with docutils, such as those
outlined above.
-__ http://docutils.sourceforge.io/
-__ http://docutils.sourceforge.io/docs/dev/hacking.html
-__ http://docutils.sourceforge.io/rst.html
-__ http://docutils.sourceforge.net/docs/user/tools.html
+__ https://docutils.sourceforge.io/
+__ https://docutils.sourceforge.io/docs/dev/hacking.html
+__ https://docutils.sourceforge.io/rst.html
+__ https://docutils.sourceforge.io/docs/user/tools.html
.. _epub-faq:
@@ -259,7 +259,9 @@ The following list gives some hints for the creation of epub files:
``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
- If you get the following error, fix your document structure::
+ If you get the following error, fix your document structure:
+
+ .. code-block:: none
Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
Error(prcgen):E24001: The table of content could not be built.
diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst
index 798736b03..6977614cd 100644
--- a/doc/internals/contributing.rst
+++ b/doc/internals/contributing.rst
@@ -251,7 +251,7 @@ The parts of messages in Sphinx that go into builds are translated into several
locales. The translations are kept as gettext ``.po`` files translated from the
master template :file:`sphinx/locale/sphinx.pot`.
-Sphinx uses `Babel `_ to extract messages
+Sphinx uses `Babel `_ to extract messages
and maintain the catalog files. It is integrated in ``setup.py``:
* Use ``python setup.py extract_messages`` to update the ``.pot`` template.
@@ -297,7 +297,7 @@ Debugging tips
will complain about references without a known target.
* Set the debugging options in the `Docutils configuration file
- `_.
+ `_.
* JavaScript stemming algorithms in ``sphinx/search/*.py`` (except ``en.py``)
are generated by this `modified snowballcode generator
diff --git a/doc/make.bat b/doc/make.bat
index 4bc6ddb9a..fb183035e 100644
--- a/doc/make.bat
+++ b/doc/make.bat
@@ -19,7 +19,7 @@ if errorlevel 9009 (
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
- echo.http://sphinx-doc.org/
+ echo.https://sphinx-doc.org/
exit /b 1
)
diff --git a/doc/templating.rst b/doc/templating.rst
index 61b714bfa..0e9d38add 100644
--- a/doc/templating.rst
+++ b/doc/templating.rst
@@ -6,10 +6,11 @@
Templating
==========
-Sphinx uses the `Jinja `_ templating engine for its HTML
-templates. Jinja is a text-based engine, inspired by Django templates, so
-anyone having used Django will already be familiar with it. It also has
-excellent documentation for those who need to make themselves familiar with it.
+Sphinx uses the `Jinja `_ templating engine
+for its HTML templates. Jinja is a text-based engine, inspired by Django
+templates, so anyone having used Django will already be familiar with it. It
+also has excellent documentation for those who need to make themselves familiar
+with it.
Do I need to use Sphinx's templates to produce HTML?
diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst
new file mode 100644
index 000000000..39ce7b697
--- /dev/null
+++ b/doc/tutorial/index.rst
@@ -0,0 +1,185 @@
+.. _tutorial:
+
+===============
+Sphinx tutorial
+===============
+
+In this tutorial you will build a simple documentation project using Sphinx, and
+view it in your browser as HTML. The project will include narrative,
+handwritten documentation, as well as autogenerated API documentation.
+
+The tutorial is aimed towards Sphinx newcomers willing to learn the fundamentals
+of how projects are created and structured. You will create a fictional
+software library to generate random food recipes that will serve as a guide
+throughout the process, with the objective of properly documenting it.
+
+To showcase Sphinx capabilities for code documentation you will use Python,
+which also supports *automatic* documentation generation.
+
+.. note::
+
+ Several other languages are natively supported in Sphinx for *manual* code
+ documentation, however they require extensions for *automatic* code
+ documentation, like `Breathe `_.
+
+To follow the instructions you will need access to a Linux-like command line and
+a basic understanding of how it works, as well as a working Python installation
+for development, since you will use *Python virtual environments* to create the
+project.
+
+Getting started
+---------------
+
+Setting up your project and development environment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In a new directory, create a file called ``README.rst`` with the following
+content.
+
+.. code-block:: rest
+
+ Lumache
+ =======
+
+ **Lumache** (/luˈmake/) is a Python library for cooks and food lovers that
+ creates recipes mixing random ingredients.
+
+It is a good moment to create a Python virtual environment and install the
+required tools. For that, open a command line terminal, ``cd`` into the
+directory you just created, and run the following commands:
+
+.. code-block:: console
+
+ $ python -m venv .venv
+ $ source .venv/bin/activate
+ (.venv) $ python -m pip install sphinx
+
+.. note::
+
+ The installation method used above is described in more detail in
+ :ref:`install-pypi`. For the rest of this tutorial, the instructions will
+ assume a Python virtual environment.
+
+If you executed these instructions correctly, you should have the Sphinx command
+line tools available. You can do a basic verification running this command:
+
+.. code-block:: console
+
+ (.venv) $ sphinx-build --version
+ sphinx-build 4.0.2
+
+If you see a similar output, you are on the right path!
+
+Creating the documentation layout
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Then from the command line, run the following command:
+
+.. code-block:: console
+
+ (.venv) $ sphinx-quickstart docs
+
+This will present to you a series of questions required to create the basic
+directory and configuration layout for your project inside the ``docs`` folder.
+To proceed, answer each question as follows:
+
+- ``> Separate source and build directories (y/n) [n]``: Write "``y``" (without
+ quotes) and press :kbd:`Enter`. - ``> Project name``: Write "``Lumache``"
+ (without quotes) and press :kbd:`Enter`. - ``> Author name(s)``: Write
+ "``Graziella``" (without quotes) and press :kbd:`Enter`. - ``> Project
+ release []``: Write "``0.1``" (without quotes) and press :kbd:`Enter`. - ``>
+ Project language [en]``: Leave it empty (the default, English) and press
+ :kbd:`Enter`.
+
+After the last question, you will see the new ``docs`` directory with the
+following content.
+
+.. code-block:: text
+
+ docs ├── build ├── make.bat ├── Makefile └── source ├── conf.py ├──
+ index.rst ├── _static └── _templates
+
+The purpose of each of these files is:
+
+``build/``
+
+ An empty directory (for now) that will hold the rendered documentation.
+
+``make.bat`` and ``Makefile``
+
+ Convenience scripts to simplify some common Sphinx operations, such as
+ rendering the content.
+
+``source/conf.py``
+
+ A Python script holding the configuration of the Sphinx project. It contains
+ the project name and release you specified to ``sphinx-quickstart``, as well
+ as some extra configuration keys.
+
+``source/index.rst``
+
+ The :term:`master document` of the project, which serves as welcome page and
+ contains the root of the "table of contents tree" (or *toctree*).
+
+Thanks to this bootstrapping step, you already have everything needed to render
+the documentation as HTML for the first time. To do that, run this command:
+
+.. code-block:: console
+
+ (.venv) $ sphinx-build -b html docs/source/ docs/build/html
+
+And finally, open `docs/build/html/index.html` in your browser. You should see
+something like this:
+
+.. image:: /_static/tutorial/lumache-first-light.png
+
+There we go! You created your first HTML documentation using Sphinx.
+
+Making some tweaks to the index
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``index.rst`` file that ``sphinx-quickstart`` created has some content
+already, and it gets rendered as the front page of our HTML documentation. It
+is written in reStructuredText, a powerful markup language.
+
+Modify the file as follows:
+
+.. code-block:: rest
+
+ Welcome to Lumache's documentation!
+ ===================================
+
+ **Lumache** (/luˈmake/) is a Python library for cooks and food lovers that
+ creates recipes mixing random ingredients. It pulls data from the `Open Food
+ Facts database `_ and offers a *simple* and
+ *intuitive* API.
+
+ .. note::
+
+ This project is under active development.
+
+This showcases several features of the reStructuredText syntax, including:
+
+- a **section header** using ``===`` for the underline, - two examples of
+ :ref:`rst-inline-markup`: ``**strong emphasis**`` (typically bold) and
+ ``*emphasis*`` (typically italics), - an **inline external link**, - and a
+ ``note`` **admonition** (one of the available :ref:`directives
+ `)
+
+Now to render it with the new content, you can use the ``sphinx-build`` command
+as before, or leverage the convenience script as follows:
+
+.. code-block:: console
+
+ (.venv) $ cd docs
+ (.venv) $ make html
+
+After running this command, you will see that ``index.html`` reflects the new
+changes!
+
+Where to go from here
+---------------------
+
+This tutorial covered the very first steps to create a documentation project
+with Sphinx. To continue learning more about Sphinx, check out the :ref:`rest
+of the documentation `.
diff --git a/doc/usage/advanced/intl.rst b/doc/usage/advanced/intl.rst
index 03b77fb6b..3bf353e8d 100644
--- a/doc/usage/advanced/intl.rst
+++ b/doc/usage/advanced/intl.rst
@@ -13,7 +13,7 @@ navigation bars, Sphinx provides mechanisms facilitating the translation of
:width: 100%
Workflow visualization of translations in Sphinx. (The figure is created by
- `plantuml `_.)
+ `plantuml `_.)
.. contents::
:local:
@@ -118,7 +118,7 @@ section describe an easy way to translate with *sphinx-intl*.
#. Translate po files.
- AS noted above, these are located in the ``./locale//LC_MESSAGES``
+ As noted above, these are located in the ``./locale//LC_MESSAGES``
directory. An example of one such file, from Sphinx, ``builders.po``, is
given below.
@@ -193,7 +193,7 @@ pot file to the po file, use the :command:`sphinx-intl update` command.
.. code-block:: console
- $ sphinx-intl update -p _build/locale
+ $ sphinx-intl update -p _build/gettext
Using Transifex service for team translation
diff --git a/doc/usage/advanced/websupport/quickstart.rst b/doc/usage/advanced/websupport/quickstart.rst
index a55080339..5fa5b00f1 100644
--- a/doc/usage/advanced/websupport/quickstart.rst
+++ b/doc/usage/advanced/websupport/quickstart.rst
@@ -61,7 +61,7 @@ This will return a dictionary containing the following items:
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
-`_ is:
+`_ is:
.. code-block:: html+jinja
@@ -112,8 +112,8 @@ must update the websupport package's data::
should be a boolean representing whether the user has moderation privileges.
The default value for *moderator* is ``False``.
-An example `Flask `_ function that checks whether a
-user is logged in and then retrieves a document is::
+An example `Flask `_ function that checks
+whether a user is logged in and then retrieves a document is::
from sphinxcontrib.websupport.errors import *
@@ -152,8 +152,8 @@ 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 `_ that would be
-like this::
+retrieve search results. In `Flask `_ that
+would be like this::
@app.route('/search')
def search():
diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst
index 95a4b6267..4e9f516b4 100644
--- a/doc/usage/configuration.rst
+++ b/doc/usage/configuration.rst
@@ -18,8 +18,8 @@ and output behavior.
directory to adjust `Docutils`_ configuration if not otherwise overridden or
set by Sphinx.
- .. _`docutils`: http://docutils.sourceforge.net/
- .. _`docutils.conf`: http://docutils.sourceforge.net/docs/user/config.html
+ .. _`docutils`: https://docutils.sourceforge.io/
+ .. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html
The configuration file is executed as Python code at build time (using
:func:`execfile`, and with the current directory set to its containing
@@ -484,7 +484,7 @@ General configuration
languages, will be used to convert quotes and dashes to typographically
correct entities. Default: ``True``.
- __ http://docutils.sourceforge.net/docs/user/smartquotes.html
+ __ https://docutils.sourceforge.io/docs/user/smartquotes.html
__ https://daringfireball.net/projects/smartypants/
.. versionadded:: 1.6.6
@@ -497,8 +497,8 @@ General configuration
*deactivates* smart quotes via the corresponding `Docutils option`__. But
if it *activates* them, then :confval:`smartquotes` does prevail.
- __ http://docutils.sourceforge.net/docs/user/config.html
- __ http://docutils.sourceforge.net/docs/user/config.html#smart-quotes
+ __ https://docutils.sourceforge.io/docs/user/config.html
+ __ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes
.. confval:: smartquotes_action
@@ -591,17 +591,18 @@ General configuration
.. confval:: highlight_language
The default language to highlight source code in. The default is
- ``'python3'``. The value should be a valid Pygments lexer name, see
+ ``'default'``. It is similar to ``'python3'``; it is mostly a superset of
+ ``'python'`` but it fallbacks to ``'none'`` without warning if failed.
+ ``'python3'`` and other languages will emit warning if failed.
+
+ The value should be a valid Pygments lexer name, see
:ref:`code-examples` for more details.
.. versionadded:: 0.5
.. versionchanged:: 1.4
- The default is now ``'default'``. It is similar to ``'python3'``;
- it is mostly a superset of ``'python'`` but it fallbacks to
- ``'none'`` without warning if failed. ``'python3'`` and other
- languages will emit warning if failed. If you prefer Python 2
- only highlighting, you can set it back to ``'python'``.
+ The default is now ``'default'``. If you prefer Python 2 only
+ highlighting, you can set it back to ``'python'``.
.. confval:: highlight_options
@@ -794,6 +795,10 @@ documentation on :ref:`intl` for details.
The default is ``['locales']``.
+ .. note:: The :option:`-v option for sphinx-build command `
+ is useful to check the locale_dirs config works as expected. It
+ emits debug messages if message catalog directory not found.
+
.. versionchanged:: 1.5
Use ``locales`` directory as a default value
@@ -1047,7 +1052,7 @@ that use Sphinx's HTMLWriter class.
A list of CSS files. The entry must be a *filename* string or a tuple
containing the *filename* string and the *attributes* dictionary. The
*filename* must be relative to the :confval:`html_static_path`, or a full URI
- with scheme like ``http://example.org/style.css``. The *attributes* is used
+ with scheme like ``https://example.org/style.css``. The *attributes* is used
for attributes of ```` tag. It defaults to an empty list.
Example::
@@ -1070,7 +1075,7 @@ that use Sphinx's HTMLWriter class.
A list of JavaScript *filename*. The entry must be a *filename* string or a
tuple containing the *filename* string and the *attributes* dictionary. The
*filename* must be relative to the :confval:`html_static_path`, or a full
- URI with scheme like ``http://example.org/script.js``. The *attributes* is
+ URI with scheme like ``https://example.org/script.js``. The *attributes* is
used for attributes of ``