WIP: Use furo Sphinx theme for Cookiecutter documentation (#612)

* Add furo 2021.11.12 to docs/requirements.txt

* Configure Sphinx to use furo theme

* Drop custom CSS

* Remove obsolete table class from User Guide

* Use headings for FAQ entries

* Remove table of contents from User Guide

Author: cjolowicz

docs/_static/custom.css

@@ -1,74 +1,3 @@
-table.hypermodern-table {
-  border-collapse: collapse;
-  margin-top: 2rem;
-  margin-bottom: 4rem;
-  max-width: 550px;
-  text-align: center;
-  width: 100%;
-  box-shadow: 0px 0px 20px rgba(0, 0, 0, 0.1), 0px 10px 20px rgba(0, 0, 0, 0.05),
-    0px 20px 20px rgba(0, 0, 0, 0.05), 0px 30px 20px rgba(0, 0, 0, 0.05);
-}
-
-table.hypermodern-table caption {
-  background: #777;
-  color: white;
-  font-family: "Lucida Grande", "Helvetica Neue", sans-serif;
-  font-size: 95%;
-  padding: 0.2rem;
-}
-
-table.hypermodern-table th,
-table.hypermodern-table td {
-  border: 1px solid #ccc;
-  padding: 0.5rem;
-  text-align: left;
-}
-
-table.hypermodern-table tbody tr:nth-child(odd) {
-  background: #eee;
-}
-
-table.hypermodern-table code {
-  background-color: inherit;
-}
-
-div.admonition {
-  border: none;
-  padding: 10px 20px;
-}
-
-div.admonition p.admonition-title {
-  background: #777;
-  color: white;
-  display: block;
-  font-family: "Lucida Grande", "Helvetica Neue", sans-serif;
-  font-size: inherit;
-  margin: -10px -20px 0px -20px;
-  padding: 5px 20px;
-}
-
-div.admonition p.admonition-title:after {
-  content: "";
-}
-
-div.contents li {
-  list-style-type: none;
-}
-
-code {
-  background: transparent;
-}
-
-code.xref,
-a code {
-  font-weight: normal;
-}
-
-ul,
-ol {
-  margin: 10px 30px 10px 30px;
-}
-
 /* Do not underline badges */
 .badges a.reference {
   border-bottom: 0px;

docs/conf.py

@@ -8,20 +8,8 @@
 extensions = ["sphinx.ext.intersphinx"]
 intersphinx_mapping = {"mypy": ("https://mypy.readthedocs.io/en/stable/", None)}
 language = "en"
-html_static_path = ["_static"]
-html_theme = "alabaster"
-html_theme_options = {
-    "github_banner": "true",
-    "github_button": "true",
-    "github_count": "true",
-    "github_user": "cjolowicz",
-    "github_repo": "cookiecutter-hypermodern-python",
-    "github_type": "star",
-    "logo": "logo.png",
-    "logo_name": "true",
-    "fixed_sidebar": "true",
-    "sidebar_width": "250px",
-}
+html_theme = "furo"
+html_logo = "_static/logo.png"
 linkcheck_ignore = [
     "codeofconduct.html",
     "https://github.com/PyCQA/flake8-bugbear#",

docs/guide.rst

@@ -8,10 +8,6 @@ a Python template based on the `Hypermodern Python`_ article series.
 If you're in a hurry, check out the :doc:`quickstart guide <quickstart>`
 and the :ref:`tutorials <Tutorials>`.
 
-.. contents::
-    :local:
-    :backlinks: none
-
 
 Introduction
 ~~~~~~~~~~~~
@@ -235,7 +231,6 @@ using a subdirectory with the same name as your project.
 Here is a complete list of the project variables defined by this template:
 
 .. table:: Project variables
-   :class: hypermodern-table
    :widths: auto
 
    ====================== ================================= ===================================
@@ -337,7 +332,6 @@ This section provides an overview of all the files generated for your project.
 Let's start with the directory layout:
 
 .. table:: Directories
-   :class: hypermodern-table
    :widths: auto
 
    ===================================== ===============================
@@ -351,7 +345,6 @@ The Python package is located in the ``src/<package>`` directory.
 For more details on these files, refer to the section :ref:`The initial package`.
 
 .. table:: Python package
-   :class: hypermodern-table
    :widths: auto
 
    ===================================== ===============================
@@ -364,7 +357,6 @@ The test suite is located in the ``tests`` directory.
 For more details on these files, refer to the section :ref:`The test suite`.
 
 .. table:: Test suite
-   :class: hypermodern-table
    :widths: auto
 
    ===================================== ===============================
@@ -376,7 +368,6 @@ The project documentation is written in reStructuredText_.
 The documentation files in the top-level directory are rendered on GitHub_:
 
 .. table:: Documentation files (top-level)
-   :class: hypermodern-table
    :widths: auto
 
    ======================= ============================================
@@ -391,7 +382,6 @@ built using :ref:`Sphinx <Documentation>` and
 hosted on :ref:`Read the Docs <Read the Docs integration>`:
 
 .. table:: Documentation files (Sphinx)
-   :class: hypermodern-table
    :widths: auto
 
    ====================== =======================================================
@@ -405,7 +395,6 @@ hosted on :ref:`Read the Docs <Read the Docs integration>`:
 The ``.github/workflows`` directory contains the :ref:`GitHub Actions workflows <GitHub Actions workflows>`:
 
 .. table:: GitHub Actions workflows
-   :class: hypermodern-table
    :widths: auto
 
    ======================= ===============================
@@ -420,7 +409,6 @@ The table below lists these files,
 and links each file to a section with more details.
 
 .. table:: Configuration files
-   :class: hypermodern-table
    :widths: auto
 
    ===================================== ========================================
@@ -450,7 +438,6 @@ The table below lists some additional files with pinned dependencies.
 Follow the links for more details on these.
 
 .. table:: Dependency files
-   :class: hypermodern-table
    :widths: auto
 
    ===================================== ================================
@@ -736,7 +723,6 @@ The template also comes with various development dependencies.
 See the table below for an overview of the dependencies of generated projects:
 
 .. table:: Dependencies
-   :class: hypermodern-table
    :widths: auto
 
    ======================= ====================================================================================
@@ -1099,7 +1085,6 @@ Overview of Nox sessions
 The following table gives an overview of the available Nox sessions:
 
 .. table:: Nox sessions
-   :class: hypermodern-table
    :widths: auto
 
    ========================================== ===================================== ================== =========
@@ -1644,7 +1629,6 @@ Overview of pre-commit hooks
 The |HPC| comes with a pre-commit configuration consisting of the following hooks:
 
 .. table:: pre-commit hooks
-   :class: hypermodern-table
    :widths: auto
 
    ======================== ===============================================
@@ -1738,7 +1722,6 @@ The following table lists the Flake8 plugins used by the |HPC|,
 and links to their lists of error codes.
 
 .. table:: Flake8 plugins
-   :class: hypermodern-table
    :widths: auto
 
    ================================ ============================================= ======================================
@@ -2076,7 +2059,6 @@ __ https://docs.github.com/en/github/administering-a-repository/configuration-op
 It manages the following dependencies:
 
 .. table::
-   :class: hypermodern-table
    :widths: auto
 
    =================== ===================================== ================================================
@@ -2175,7 +2157,6 @@ Overview of workflows
 The |HPC| defines the following workflows:
 
 .. table:: GitHub Actions workflows
-   :class: hypermodern-table
    :widths: auto
 
    ===================================================== ======================== ==================================== =====================
@@ -2193,7 +2174,6 @@ Overview of GitHub Actions
 Workflows use the following GitHub Actions:
 
 .. table:: GitHub Actions
-   :class: hypermodern-table
    :widths: auto
 
    ============================================ =========================================================
@@ -2272,7 +2252,6 @@ as shown in the table below:
 __ https://help.github.com/en/actions/automating-your-workflow-with-github-actions/virtual-environments-for-github-hosted-runners#supported-runners-and-hardware-resources
 
 .. table:: Jobs in the Tests workflow
-   :class: hypermodern-table
    :widths: auto
 
    ========================================== ====================== ==================
@@ -2335,7 +2314,6 @@ You can generate these tokens from your account settings on these services.
 The tokens need to be stored as secrets in the repository settings on GitHub:
 
 .. table:: Secrets
-   :class: hypermodern-table
    :widths: auto
 
    =================== ===================

docs/index.rst

@@ -43,13 +43,16 @@ Features
 FAQ
 ---
 
-  *What is this project about?*
+What is this project about?
+...........................
 
 The mission of this project is to
 enable current best practices
 through modern Python tooling.
 
-  *What makes this project different from other Python templates?*
+
+What makes this project different from other Python templates?
+..............................................................
 
 This is a general-purpose template for Python libraries and applications.
 
@@ -65,7 +68,9 @@ The project template is centered around the following tools:
 - Nox_ for automation of checks and other development tasks
 - `GitHub Actions`_ for continuous integration and delivery
 
-  *Why is this Python template called "hypermodern"?*
+
+Why is this Python template called "hypermodern"?
+.................................................
 
 Hypermodernism_ is a school of chess that dates back to more than a century ago.
 If this setup ever goes out of fashion,

docs/requirements.txt

@@ -1,2 +1,3 @@
+furo==2021.11.12
 sphinx==4.3.0
 sphinx-autobuild==2021.3.14