Overhaul rendering of the manual

docs/_static/custom.css

@@ -0,0 +1,15 @@
+div.body, div.footer, code, div.code-block-caption,
+div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6,
+a.toc-backref
+   {color: black}
+
+div.body p, div.body dd, div.body li, div.body blockquote
+   {hyphens: manual}
+
+a
+   {color: navy}
+a:visited
+   {color: purple}
+
+code
+   {background-color: #dfd}

docs/api.rst

@@ -1,6 +1,9 @@
 API
 ===
 
+.. contents:: Contents
+   :local:
+
 .. _core-macros:
 
 Core Macros

docs/cli.rst

@@ -4,6 +4,9 @@ Command-Line Interface
 
 Hy provides a handful of command-line programs for working with Hy code.
 
+.. contents:: Contents
+   :local:
+
 .. _hy-cli:
 
 hy

docs/conf.py

@@ -1,85 +1,48 @@
-# This file is execfile()d with the current directory set to its containing dir.
+import os, re, sys, time, html
 
-import html
-import os
-import re
-import sys
-import time
+sys.path.insert(0, os.path.abspath('..'))
 
-sys.path.insert(0, os.path.abspath(".."))
+import hy; hy.I = type(hy.I)  # A trick to enable `hy:autoclass:: hy.I`
 
 extensions = [
-    "sphinx.ext.napoleon",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.autodoc",
-    "sphinx.ext.viewcode",
-    "sphinxcontrib.hydomain",
-]
+    'sphinx.ext.napoleon',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autodoc',
+    'sphinxcontrib.hydomain']
 
 import warnings; import sphinx.deprecation as SD
 for c in (SD.RemovedInSphinx60Warning, SD.RemovedInSphinx70Warning):
     warnings.filterwarnings('ignore', category = c)
 
 from get_version import __version__ as hy_version
 
-# Read the Docs might dirty its checkout, so strip the dirty flag.
-hy_version = re.sub(r"[+.]dirty\Z", "", hy_version)
-
-templates_path = ["_templates"]
-source_suffix = ".rst"
-
-master_doc = "index"
-
-# General information about the project.
-project = "hy"
-copyright = "%s the authors" % time.strftime("%Y")
-
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = ".".join(hy_version.split(".")[:-1])
-# The full version, including alpha/beta/rc tags.
+project = 'Hy'
+copyright = '%s the authors' % time.strftime('%Y')
+html_title = f'Hy {hy_version} manual'
+version = '.'.join(hy_version.split('.')[:-1])
+  # The short dotted version identifier
 release = hy_version
-hy_descriptive_version = html.escape(hy_version)
-if "+" in hy_version:
-    hy_descriptive_version += " <strong style='color: red;'>(unstable)</strong>"
-
-exclude_patterns = ["_build", "coreteam.rst"]
-add_module_names = True
-
-pygments_style = "sphinx"
-
-import sphinx_rtd_theme
-
-html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
-
+  # The full version identifier, including alpha, beta, and RC tags
+
+source_suffix = '.rst'
+master_doc = 'index'
+exclude_patterns = ['_build', 'coreteam.rst']
+
+html_theme = 'nature'
+html_theme_options = dict(
+    nosidebar = True,
+    body_min_width = 0,
+    body_max_width = 'none')
+html_css_files = ['custom.css']
+html_static_path = ['_static']
 html_use_smartypants = False
+html_copy_source = False
 html_show_sphinx = False
 
-html_context = dict(
-    hy_descriptive_version=hy_descriptive_version)
+add_module_names = True
 
-highlight_language = "hylang"
+highlight_language = 'hylang'
 
 intersphinx_mapping = dict(
-    py=("https://docs.python.org/3/", None),
-    hyrule=("https://hyrule.readthedocs.io/en/master/", None),
-)
-
-import hy
-hy.I = type(hy.I)  # A trick to enable `hy:autoclass:: hy.I`
-
-
-# ** Sphinx App Setup
-
-
-def setup(app):
-    app.add_css_file("overrides.css")
+    py = ('https://docs.python.org/3/', None),
+    hyrule = ('https://hyrule.readthedocs.io/en/master/', None))

docs/hacking.rst

@@ -4,6 +4,9 @@
  Developing Hy
 ===============
 
+.. contents:: Contents
+   :local:
+
 .. include:: ../CONTRIBUTING.rst
 
 Core Team

docs/index.rst

@@ -1,5 +1,5 @@
-The Hy Manual
-=============
+Contents
+========
 
 .. image:: _static/hy-logo-small.png
    :alt: Hy
@@ -22,7 +22,7 @@ To install the latest release of Hy, just use the command ``pip3 install
 the command ``hy``, or run a Hy program with ``hy myprogram.hy``.
 
 Hy is tested on all released and currently maintained versions of CPython (on
-Linux and Windows), and on recent versions of PyPy and Pyodide.
+Linux, Windows, and Mac OS), and on recent versions of PyPy and Pyodide.
 
 .. toctree::
    :maxdepth: 3

docs/interop.rst

@@ -10,6 +10,9 @@ Hy and Python. For example, Python's ``str.format_map`` can be written
 ``hyx_valid_Xquestion_markX`` in Python. You can call :hy:func:`hy.mangle` and
 :hy:func:`hy.unmangle` from either language.
 
+.. contents:: Contents
+   :local:
+
 Using Python from Hy
 ====================
 

docs/macros.rst

@@ -4,6 +4,9 @@ Macros
 
 Macros, and the metaprogramming they enable, are one of the characteristic features of Lisp, and one of the main advantages Hy offers over vanilla Python. Much of the material covered in this chapter will be familiar to veterans of other Lisps, but there are also a lot of Hyly specific details.
 
+.. contents:: Contents
+   :local:
+
 What are macros for?
 --------------------
 

docs/semantics.rst

@@ -6,6 +6,9 @@ This chapter describes features of Hy semantics that differ from Python's and
 aren't better categorized elsewhere, such as in the chapter :doc:`macros`. Each
 is a potential trap for the unwary.
 
+.. contents:: Contents
+   :local:
+
 .. _implicit-names:
 
 Implicit names

docs/syntax.rst

@@ -14,6 +14,9 @@ Following Python, Hy is in general case-sensitive. For example, ``foo`` and
 ``FOO`` are different symbols, and the Python-level variables they refer to are
 also different.
 
+.. contents:: Contents
+   :local:
+
 .. _models:
 
 An introduction to models

docs/tutorial.rst

@@ -10,6 +10,9 @@ Tutorial
 This chapter provides a quick introduction to Hy. It assumes a basic background
 in programming, but no specific prior knowledge of Python or Lisp.
 
+.. contents:: Contents
+   :local:
+
 Lisp-stick on a Python
 ======================
 

docs/whyhy.rst

@@ -16,6 +16,8 @@ other Lisps, Hy provides direct access to Python's built-ins and
 third-party Python libraries, while allowing you to freely mix
 imperative, functional, and object-oriented styles of programming.
 
+.. contents:: Contents
+   :local:
 
 Hy versus Python
 ----------------

requirements-dev.txt

@@ -3,5 +3,4 @@ pytest >= 7
 # documentation
 Pygments @ git+https://github.com/Kodiologist/pygments@hylex
 Sphinx == 5.0.2
-sphinx_rtd_theme == 1.2.2
 git+https://github.com/hylang/sphinxcontrib-hydomain.git