Update documentation structure and theming (#10677)

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>

doc/_themes/sphinx13/layout.html

@@ -32,15 +32,15 @@
 {%- block content %}
 <div class="document">
   <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
-  {%- include "searchbox.html" %}
+    {%- include "searchbox.html" %}
-  <div>
+    <div class="sphinxsidebar-navigation__contents">
-    <h3>{{ _('Contents') }}</h3>
+      <h3>{{ _('On this page') }}</h3>
-    {%- if pagename != "index" %}
       {{ toc }}
-    {%- else %}
+    </div>
-      {{ toctree(includehidden=True, maxdepth=3) }}
+    <div class="sphinxsidebar-navigation__pages">
-    {%- endif %}
+      <h3>{{ _('Site navigation') }}</h3>
-  </div>
+      {{ toctree(includehidden=True, maxdepth=3, titles_only=True) }}
+    </div>
   </div>
   {%- block document %}
   <div class="body" role="main">

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;
 }
 

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
+Here are some of Sphinx's major features:
-=======
-
-Install Sphinx with ``pip install -U Sphinx``. See :doc:`usage/installation` for
-further details.
-
-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 <builtin-extensions>`
+  from Python modules (API docs) via :ref:`built-in extensions
-* **Contributed extensions:** dozens of extensions
+  <builtin-extensions>`, and much more functionality via :ref:`third-party
-  :ref:`contributed by users <third-party-extensions>`; most of them installable
+  extensions <third-party-extensions>`.
-  from PyPI
+* **Themes:** modify the look and feel of outputs via :doc:`creating themes
-
+  <development/theming>`, and re-use many :ref:`third-party themes
-.. _Pygments: https://pygments.org/
+  <third-party-themes>`.
-
+* **Contributed extensions:** dozens of extensions :ref:`contributed by users
-Sphinx uses reStructuredText_ as its markup language, and many of its strengths
+  <third-party-extensions>`; most of them installable from PyPI.
-come from the power and straightforwardness of reStructuredText and its parsing
-and translating suite, the Docutils_.
 
 .. _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 <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 <usage/quickstart>`: overview of basic tasks
+See below for how to navigate Sphinx's documentation.
-* :doc:`Tutorial <tutorial/index>`: beginners tutorial
-* :ref:`Search page <search>`: search the documentation
-* :doc:`Changes <changes>`: release history
-* :ref:`General Index <genindex>`: all functions, classes, terms
-* :ref:`Python Module Index <modindex>`: the index of Python modules
-* :doc:`Glossary <glossary>`: definitions of various terms
-* :doc:`Sphinx's Authors <internals/authors>`: the Sphinx developers
-* `Contents <contents.html>`__: full table of contents
 
-Support
+.. seealso::
-=======
 
-For questions or to report problems with Sphinx, join the `sphinx-users`_
+   The `Sphinx documentation Table of Contents <contents.html>`_ has
-mailing list on Google Groups, come to the ``#sphinx-doc`` channel on
+   a full list of this site's pages.
-`libera.chat`_, or open an issue at the tracker_.
 
-.. _sphinx-users: https://groups.google.com/group/sphinx-users
+.. _get-started:
-.. _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
+Get started
-<examples>`. A useful tutorial_ has been written by the matplotlib developers.
+===========
 
-.. _tutorial: http://matplotlib.sourceforge.net/sampledoc/
+These sections cover the basics of getting started with Sphinx, including
-
+creating and building your own documentation from scratch.
-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 <internals/contributing>` if you would
-like to contribute to the project.
-
-.. master toctree:
 
 .. toctree::
-   :maxdepth: 5
+   :maxdepth: 2
-   :hidden:
+   :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 <internals/contributing>` 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

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 <https://tox.wiki/en/latest/>`__ 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
 ~~~~~~~~~~~~
 

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

doc/man/index.rst

@@ -1,5 +1,5 @@
-Man Pages
+Command-Line Tools
-=========
+==================
 
 These are the applications provided as part of Sphinx.
 

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
+<examples>`. 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/

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,

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

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,

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 =