diff --git a/doc/_themes/sphinx13/layout.html b/doc/_themes/sphinx13/layout.html
index f6f858a57..afab3693b 100644
--- a/doc/_themes/sphinx13/layout.html
+++ b/doc/_themes/sphinx13/layout.html
@@ -32,15 +32,15 @@
{%- block content %}
{%- block document %}
diff --git a/doc/_themes/sphinx13/static/sphinx13.css b/doc/_themes/sphinx13/static/sphinx13.css
index 562b1757b..4cf1df80e 100644
--- a/doc/_themes/sphinx13/static/sphinx13.css
+++ b/doc/_themes/sphinx13/static/sphinx13.css
@@ -27,7 +27,7 @@ div.document {
div.body {
border-left: 1px solid var(--colour-sphinx-blue);
margin: 0;
- padding: 0.5em 1.25em;
+ padding: 0.5em 1.75em;
min-width: 0;
max-width: 800px;
}
@@ -59,10 +59,15 @@ div.sphinxsidebarwrapper {
}
div.sphinxsidebar {
+ position: sticky;
+ top: 0;
+ align-self: flex-start;
+ height: 100vh;
+ width: 250px;
+ overflow-y: auto;
overflow-wrap: break-word;
margin: 0;
padding-right: 15px;
- width: 210px;
font-size: 1em;
}
@@ -99,8 +104,27 @@ div.sphinxsidebar ul {
}
div.sphinxsidebar ul ul {
- margin-left: 20px;
+ margin-left: 1rem;
list-style-type: none;
+ font-size: .9em;
+}
+
+/* De-dent the first list because we hide the top-level item */
+.sphinxsidebar .sphinxsidebar-navigation__contents > ul > li > ul {
+ margin-left: 0;
+}
+
+div.sphinxsidebar p.caption {
+ font-weight: 300;
+ font-size: 1.2rem;
+}
+
+div.sphinxsidebar li.current > a {
+ font-weight: 600;
+}
+
+.sphinxsidebar-navigation__contents > ul > li > a {
+ display: none;
}
div.footer {
@@ -170,11 +194,10 @@ div.body h1 a tt, div.body h2 a tt, div.body h3 a tt, div.body h4 a tt, div.body
a.headerlink {
color: var(--colour-sphinx-blue) !important;
- font-size: 12px;
+ font-size: .8em;
margin-left: 6px;
padding: 0 4px 0 4px;
text-decoration: none !important;
- float: right;
}
a.headerlink:hover {
@@ -250,6 +273,12 @@ div.quotebar {
margin-left: 1em;
}
+blockquote {
+ font-size: 1.5em;
+ padding-left: 1rem;
+ margin-left: 0;
+}
+
nav.contents,
div.topic,
aside.topic {
@@ -271,11 +300,11 @@ div.admonition, div.warning {
border: 1px solid #86989B;
border-radius: 2px;
background-color: #f7f7f7;
- padding: 0;
+ padding: 1rem;
}
div.admonition > p, div.warning > p {
- margin: 0.5em 1em 0.5em 1em;
+ margin: 0;
padding: 0;
}
@@ -285,7 +314,6 @@ div.admonition > pre, div.warning > pre {
div.admonition > p.admonition-title,
div.warning > p.admonition-title {
- margin-top: 0.5em;
font-weight: bold;
}
diff --git a/doc/index.rst b/doc/index.rst
index 50571cdb7..e795bdb57 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -2,16 +2,9 @@
Welcome
=======
-**Sphinx makes it easy to create intelligent and beautiful documentation.**
+.. epigraph:: Sphinx makes it easy to create intelligent and beautiful documentation.
-Install
-=======
-
-Install Sphinx with ``pip install -U Sphinx``. See :doc:`usage/installation` for
-further details.
-
-Features
-========
+Here are some of Sphinx's major features:
* **Output formats:** HTML (including Windows HTML Help), LaTeX (for printable
PDF versions), ePub, Texinfo, manual pages, plain text
@@ -24,78 +17,98 @@ Features
indices
* **Code handling:** automatic highlighting using the Pygments_ highlighter
* **Extensions:** automatic testing of code snippets, inclusion of docstrings
- from Python modules (API docs), and :ref:`more `
-* **Contributed extensions:** dozens of extensions
- :ref:`contributed by users `; most of them installable
- from PyPI
-
-.. _Pygments: https://pygments.org/
-
-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_.
+ from Python modules (API docs) via :ref:`built-in extensions
+ `, and much more functionality via :ref:`third-party
+ extensions `.
+* **Themes:** modify the look and feel of outputs via :doc:`creating themes
+ `, and re-use many :ref:`third-party themes
+ `.
+* **Contributed extensions:** dozens of extensions :ref:`contributed by users
+ `; most of them installable from PyPI.
.. _reStructuredText: https://docutils.sourceforge.io/rst.html
.. _Docutils: https://docutils.sourceforge.io/
+.. _Pygments: https://pygments.org/
-Documentation
-=============
+Sphinx uses the reStructuredText_ markup language by default, and can read
+:ref:`MyST markdown ` via third-party extensions. Both of these
+are powerful and straightforward to use, and have functionality
+for complex documentation and publishing workflows. They both build upon
+Docutils_ to parse and write documents.
-* :doc:`First steps with Sphinx `: overview of basic tasks
-* :doc:`Tutorial `: beginners tutorial
-* :ref:`Search page `: search the documentation
-* :doc:`Changes `: release history
-* :ref:`General Index `: all functions, classes, terms
-* :ref:`Python Module Index `: the index of Python modules
-* :doc:`Glossary `: definitions of various terms
-* :doc:`Sphinx's Authors `: the Sphinx developers
-* `Contents `__: full table of contents
+See below for how to navigate Sphinx's documentation.
-Support
-=======
+.. seealso::
-For questions or to report problems with Sphinx, join the `sphinx-users`_
-mailing list on Google Groups, come to the ``#sphinx-doc`` channel on
-`libera.chat`_, or open an issue at the tracker_.
+ The `Sphinx documentation Table of Contents `_ has
+ a full list of this site's pages.
-.. _sphinx-users: https://groups.google.com/group/sphinx-users
-.. _libera.chat: https://web.libera.chat/?channel=#sphinx-doc
-.. _tracker: https://github.com/sphinx-doc/sphinx/issues
+.. _get-started:
-Examples of other projects using Sphinx can be found in the :doc:`examples page
-`. A useful tutorial_ has been written by the matplotlib developers.
+Get started
+===========
-.. _tutorial: http://matplotlib.sourceforge.net/sampledoc/
-
-There is a translation team in Transifex_ of this documentation, thanks to the
-Sphinx document translators.
-
-.. _Transifex: https://www.transifex.com/sphinx-doc/sphinx-doc/dashboard/
-
-Contributor guide
-=================
-
-See the :doc:`Sphinx contributors' guide ` if you would
-like to contribute to the project.
-
-.. master toctree:
+These sections cover the basics of getting started with Sphinx, including
+creating and building your own documentation from scratch.
.. toctree::
- :maxdepth: 5
- :hidden:
+ :maxdepth: 2
+ :caption: Get started
+
+ usage/quickstart
+ usage/installation
+ tutorial/index
+
+.. _user-guides:
+
+User Guides
+===========
+
+These sections cover various topics in using and extending Sphinx for various
+use-cases. They are a comprehensive guide to using Sphinx in many contexts and
+assume more knowledge of Sphinx. If you are new to Sphinx, we recommend
+starting with :ref:`get-started`.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: User Guides
usage/index
- tutorial/index
development/index
- man/index
-
templating
latex
extdev/index
- internals/index
+Community guide
+===============
+Sphinx is community supported and welcomes contributions from anybody.
+The sections below should help you get started joining the Sphinx community
+as well as contributing.
+
+See the :doc:`Sphinx contributors' guide ` if you would
+like to contribute to the project.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Community
+
+ support
+ internals/index
faq
+
+Reference guide
+===============
+
+Reference documentation is more complete and programmatic in nature, it is a
+collection of information that can be quickly referenced. If you would like
+usecase-driven documentation, see :ref:`get-started` or :ref:`user-guides`.
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Reference
+
+ man/index
glossary
changes
examples
diff --git a/doc/internals/contributing.rst b/doc/internals/contributing.rst
index f6ba5146a..d633f9ca0 100644
--- a/doc/internals/contributing.rst
+++ b/doc/internals/contributing.rst
@@ -7,8 +7,8 @@ feature requests, writing new documentation or submitting patches for new or
fixed behavior. This guide serves to illustrate how you can get started with
this.
-Getting help
-------------
+Get help
+--------
The Sphinx community maintains a number of mailing lists and IRC channels.
@@ -46,8 +46,8 @@ and post that instead.
.. _`sphinx-dev`: mailto:sphinx-dev@googlegroups.com
-Writing code
-------------
+Contribute code
+---------------
The Sphinx source code is managed using Git and is hosted on `GitHub`__. The
recommended way for new contributors to submit code to Sphinx is to fork this
@@ -57,6 +57,8 @@ before it is merged into the main repository.
.. __: https://github.com/sphinx-doc/sphinx
+.. _contribute-get-started:
+
Getting started
~~~~~~~~~~~~~~~
@@ -235,15 +237,38 @@ If you want to know more detailed usage, please refer to ``tests/conftest.py``
and other ``test_*.py`` files under ``tests`` directory.
-Writing documentation
----------------------
+Contribute documentation
+------------------------
+
+Contributing to documentation involves modifying the source files found in the
+``doc/`` folder. To get started, you should first follow :ref:`contribute-get-started`,
+and then take the steps below to work with the documentation.
+
+The following sections describe how to get started with contributing
+documentation, as well as key aspects of a few different tools that we use.
.. todo:: Add a more extensive documentation contribution guide.
-You can build documentation using ``tox``::
+Build the documentation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+We use `the tox tool `__ to quickly build the
+documentation. Tox is kind-of like a Makefile, but includes the ability to
+intsall an isolated environment used to run each task.
+
+To build the documentation with ``tox``, run the following command::
tox -e docs
+This will parse the Sphinx documentation's source files and generate HTML for
+you to preview in ``build/sphinx/html``.
+
+You can also build a **live version of the documentation** that you can preview
+in the browser. It will detect changes and reload the page any time you make
+edits. To do so, run the following command::
+
+ tox -e docs-live
+
Translations
~~~~~~~~~~~~
diff --git a/doc/internals/index.rst b/doc/internals/index.rst
index 6a62a96be..c52f32a67 100644
--- a/doc/internals/index.rst
+++ b/doc/internals/index.rst
@@ -1,6 +1,6 @@
-================
-Sphinx internals
-================
+====================
+Contribute to Sphinx
+====================
This guide contains information about the Sphinx open source project itself.
This is where you can find information about how Sphinx is managed and learn
diff --git a/doc/man/index.rst b/doc/man/index.rst
index c2ca3f065..14680228b 100644
--- a/doc/man/index.rst
+++ b/doc/man/index.rst
@@ -1,5 +1,5 @@
-Man Pages
-=========
+Command-Line Tools
+==================
These are the applications provided as part of Sphinx.
diff --git a/doc/support.rst b/doc/support.rst
new file mode 100644
index 000000000..b7c6f01df
--- /dev/null
+++ b/doc/support.rst
@@ -0,0 +1,20 @@
+Get support
+===========
+
+For questions or to report problems with Sphinx, join the `sphinx-users`_
+mailing list on Google Groups, come to the ``#sphinx-doc`` channel on
+`libera.chat`_, or open an issue at the tracker_.
+
+.. _sphinx-users: https://groups.google.com/group/sphinx-users
+.. _libera.chat: https://web.libera.chat/?channel=#sphinx-doc
+.. _tracker: https://github.com/sphinx-doc/sphinx/issues
+
+Examples of other projects using Sphinx can be found in the :doc:`examples page
+`. A useful tutorial_ has been written by the matplotlib developers.
+
+.. _tutorial: http://matplotlib.sourceforge.net/sampledoc/
+
+There is a translation team in Transifex_ of this documentation, thanks to the
+Sphinx document translators.
+
+.. _Transifex: https://www.transifex.com/sphinx-doc/sphinx-doc/dashboard/
diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst
index 1d12aff83..57a055f43 100644
--- a/doc/tutorial/index.rst
+++ b/doc/tutorial/index.rst
@@ -1,8 +1,8 @@
.. _tutorial:
-===============
-Sphinx tutorial
-===============
+========================
+Build your first project
+========================
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,
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 49a4dccaa..0f4c22211 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -10,8 +10,6 @@ looking for guidance on extending Sphinx, refer to :doc:`/development/index`.
.. toctree::
:maxdepth: 2
- quickstart
- installation
restructuredtext/index
markdown
configuration
diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst
index 5f5417061..0e4b4a64d 100644
--- a/doc/usage/theming.rst
+++ b/doc/usage/theming.rst
@@ -345,10 +345,12 @@ These themes are:
available, however it will emit a notice that it is an alias for the new
'alabaster' theme.
+.. _third-party-themes:
+
Third Party Themes
~~~~~~~~~~~~~~~~~~
-There are many third-party themes available for Sphinx. Some of these are for
+There are many third-party themes created for Sphinx. Some of these are for
general use, while others are specific to an individual project.
sphinx-themes.org__ is a gallery that showcases various themes for Sphinx,
diff --git a/tox.ini b/tox.ini
index 664215955..7ca990b56 100644
--- a/tox.ini
+++ b/tox.ini
@@ -86,6 +86,17 @@ extras =
commands =
sphinx-lint --enable line-too-long --max-line-length 85 CHANGES CONTRIBUTING.rst README.rst doc/
+[testenv:docs-live]
+basepython = python3
+description =
+ Build documentation.
+extras =
+ docs
+deps =
+ sphinx-autobuild
+commands =
+ sphinx-autobuild ./doc ./build/sphinx/
+
[testenv:twine]
basepython = python3
description =