mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
79 lines
2.5 KiB
ReStructuredText
79 lines
2.5 KiB
ReStructuredText
More Sphinx customization
|
|
=========================
|
|
|
|
There are two main ways to customize your documentation beyond what is possible
|
|
with core Sphinx: extensions and themes.
|
|
|
|
Enabling a built-in extension
|
|
-----------------------------
|
|
|
|
In addition to these configuration values, you can customize Sphinx even more
|
|
by using :doc:`extensions </usage/extensions/index>`. Sphinx ships several
|
|
:ref:`builtin ones <builtin-extensions>`, and there are many more
|
|
:ref:`maintained by the community <third-party-extensions>`.
|
|
|
|
For example, to enable the :mod:`sphinx.ext.duration` extension,
|
|
locate the ``extensions`` list in your ``conf.py`` and add one element as
|
|
follows:
|
|
|
|
.. code-block:: python
|
|
:caption: docs/source/conf.py
|
|
|
|
# Add any Sphinx extension module names here, as strings. They can be
|
|
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
|
# ones.
|
|
extensions = [
|
|
'sphinx.ext.duration',
|
|
]
|
|
|
|
After that, every time you generate your documentation, you will see a short
|
|
durations report at the end of the console output, like this one:
|
|
|
|
.. code-block:: console
|
|
|
|
(.venv) $ make html
|
|
...
|
|
The HTML pages are in build/html.
|
|
|
|
====================== slowest reading durations =======================
|
|
0.042 temp/source/index
|
|
|
|
Using a third-party HTML theme
|
|
------------------------------
|
|
|
|
Themes, on the other hand, are a way to customize the appearance of your
|
|
documentation. Sphinx has several :ref:`builtin themes <builtin-themes>`, and
|
|
there are also `third-party ones <https://sphinx-themes.org/>`_.
|
|
|
|
For example, to use the `Furo <https://pradyunsg.me/furo/>`_ third-party theme
|
|
in your HTML documentation, first you will need to install it with ``pip`` in
|
|
your Python virtual environment, like this:
|
|
|
|
.. code-block:: console
|
|
|
|
(.venv) $ pip install furo
|
|
|
|
And then, locate the ``html_theme`` variable on your ``conf.py`` and replace
|
|
its value as follows:
|
|
|
|
.. code-block:: python
|
|
:caption: docs/source/conf.py
|
|
|
|
# The theme to use for HTML and HTML Help pages. See the documentation for
|
|
# a list of builtin themes.
|
|
#
|
|
html_theme = 'furo'
|
|
|
|
With this change, you will notice that your HTML documentation has now a new
|
|
appearance:
|
|
|
|
.. figure:: /_static/tutorial/lumache-furo.png
|
|
:width: 80%
|
|
:align: center
|
|
:alt: HTML documentation of Lumache with the Furo theme
|
|
|
|
HTML documentation of Lumache with the Furo theme
|
|
|
|
It is now time to :doc:`expand the narrative documentation and split it into
|
|
several documents </tutorial/narrative-documentation>`.
|