Update Sphinx theme to Furo (#909)

Author: chrisrink10

.github/workflows/run-tests.yml

@@ -83,7 +83,7 @@ jobs:
     # VERSION with the minimal possible Basilisp dependencies
     # versions.
     #
-    # For dependencies to be elligible for minimum version testing,
+    # For dependencies to be eligible for minimum version testing,
     # they should be declared in `pyproject.toml` as such in the
     # following format
     #

CHANGELOG.md

@@ -15,6 +15,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  * Fix a bug where `.` characters were not allowed in keyword names (#899)
  * Fix a bug where nested quotation marks were not escaped properly by various print functions and at the REPL (#894)
 
+### Other
+ * Update Sphinx documentation theme (#909)
+ * Fix a few minor documentation issues (#907)
+
 ## [v0.1.0b2]
 ### Added
  * Added filename metadata to compiler exceptions (#844)

docs/compiler.rst

@@ -13,7 +13,7 @@ Since the compiler cannot reason about larger units of code, it cannot make infe
 
 There are three steps to the Basilisp compiler: analysis, generation, and optimization.
 After a Basilisp form is read in by the :ref:`reader`, it is passed off to the analyzer to produce an abstract syntax tree.
-The generator reads the AST and produces Python code (*not* bytecode) using Python's builtin `ast <https://docs.python.org/3/library/ast.html>`_ module.
+The generator reads the AST and produces Python code (*not* bytecode) using Python's builtin :external:py:mod:`ast` module.
 Afterwards, the compiler passes the generated AST through a quick optimization phase to remove redundant branches and other artifacts of code generation.
 From there, the compiler injects the compiled code into a dynamically-generated Python module which is associated with a Basilisp Namespace and executes the code so the generated objects are available.
 
@@ -182,7 +182,7 @@ Debugging
 
 The compiler generates Python code by generating Python AST nodes, rather than emitting the raw Python code as text.
 This is convenient for the compiler, but inspecting Python AST nodes manually for bugs can be a bit of a challenge even with a debugger.
-For this reason, the Basilisp compiler can also use the `ast.unparse <https://docs.python.org/3/library/ast.html#ast.unparse>`_ (`astor <https://github.com/berkerpeksag/astor>`_ in versions of Python prior to 3.9) library to generate raw Python code for visual inspection.
+For this reason, the Basilisp compiler can also use the :external:py:func:`ast.unparse` (`astor <https://github.com/berkerpeksag/astor>`_ in versions of Python prior to 3.9) library to generate raw Python code for visual inspection.
 
 Currently, the compiler is configured to automatically generate Python code for all namespaces.
 This code generation isn't slow, but it does add an appreciable amount of time to the compilation of each individual namespace.

docs/conf.py

@@ -6,21 +6,11 @@
 # full list see the documentation:
 # http://www.sphinx-doc.org/en/master/config
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
 
 # -- Project information -----------------------------------------------------
 
 project = "Basilisp"
-copyright = "2018-2023, Chris Rink"
+copyright = "2018-2024, Chris Rink"
 author = "Chris Rink"
 
 # The short X.Y version
@@ -37,7 +27,11 @@
 # 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.autodoc", "basilisp.contrib.sphinx"]
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "basilisp.contrib.sphinx",
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -74,13 +68,18 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "sphinx_rtd_theme"
+html_theme = "furo"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-html_theme_options = {"collapse_navigation": False}
+html_title = "Basilisp"
+html_theme_options = {
+    "source_repository": "https://github.com/basilisp-lang/basilisp/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}
 
 # 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,
@@ -145,7 +144,7 @@
         "Basilisp Documentation",
         author,
         "Basilisp",
-        "One line description of project.",
+        "A Clojure-like lisp written for Python",
         "Miscellaneous",
     )
 ]
@@ -167,4 +166,8 @@
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ["search.html"]
 
-# -- Extension configuration -------------------------------------------------
+# -- Options for Intersphinx -------------------------------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}

docs/contributing.rst

@@ -12,7 +12,7 @@ We accept the following types of contributions:
   Bugs may sometimes be fixed in unreleased code, so be sure to look at the `CHANGELOG <https://github.com/basilisp-lang/basilisp/blob/main/CHANGELOG.md>`_ in the ``main`` branch to see if the fix has simply not yet been released.
 
 * **Feature Requests:** Submit a new issue on GitHub reporting a feature request.
-  Because Basilisp targets a high degree of compatibility with Clojure, feature requests should generally be for features from Clojure which have not yet been implemented in Basilisp.
+  Basilisp targets a reasonable degree of compatibility with Clojure, so feature requests should generally be for features from Clojure which have not yet been implemented in Basilisp.
   Occasionally, new features outside of the scope of Clojure compatibility may be covered, in particular if the feature is related to a Python ecosystem affordance.
 
 * **Documentation:** Documentation is hard.

docs/differencesfromclojure.rst

@@ -43,7 +43,7 @@ In Clojure, this optimistic equality comparison is performed by the ``==`` funct
 
 .. note::
 
-   Basilisp's ``=`` will perform as expected when using Python `Decimal <https://docs.python.org/3/library/decimal.html>`__ typed :ref:`floating_point_numbers`.
+   Basilisp's ``=`` will perform as expected when using Python :external:py:class:`decimal.Decimal` typed :ref:`floating_point_numbers`.
 
 .. seealso::
 
@@ -79,8 +79,8 @@ Reader
 
   * Python integers natively support unlimited precision, so there is no difference between regular integers and those suffixed with ``N`` (which are read as ``BigInt``\s in Clojure).
   * Floating point numbers are read as Python ``float``\s by default and subject to the limitations of that type on the current Python VM.
-    Floating point numbers suffixed with ``M`` are read as Python `Decimal <https://docs.python.org/3/library/decimal.html#decimal.Decimal>`_ types and support user-defined precision.
-  * Ratios are supported and are read in as Python `Fraction <https://docs.python.org/3/library/fractions.html#fractions.Fraction>`_ types.
+    Floating point numbers suffixed with ``M`` are read as Python :external:py:class:`decimal.Decimal` types and support user-defined precision.
+  * Ratios are supported and are read in as Python :external:py:class:`fractions.Fraction` types.
   * Python natively supports Complex numbers.
     The reader will return a complex number for any integer or floating point literal suffixed with ``J``.
 
@@ -97,7 +97,7 @@ Reader
 Regular Expressions
 -------------------
 
-Basilisp regular expressions use Python's `regular expression <https://docs.python.org/3/library/re.html>`_ syntax and engine.
+Basilisp regular expressions use Python's :external:py:mod:`regular expression <re>` syntax and engine.
 
 .. _repl_differences:
 
@@ -194,7 +194,7 @@ Type Hinting
 
 Type hints may be applied anywhere they are supported in Clojure (as the ``:tag`` metadata key), but the compiler does not currently use them for any purpose.
 Tags provided for ``def`` names, function arguments and return values, and :lpy:form:`let` locals will be applied to the resulting Python AST by the compiler wherever possible.
-Particularly in the case of function arguments and return values, these tags maybe introspected from the Python `inspect <https://docs.python.org/3/library/inspect.html>`_ module.
+Particularly in the case of function arguments and return values, these tags maybe introspected from the Python :external:py:mod:`inspect` module.
 There is no need for type hints anywhere in Basilisp right now, however.
 
 .. _compilation_differences:

docs/gettingstarted.rst

@@ -135,7 +135,7 @@ For systems where the shebang line allows arguments, you can use ``#!/usr/bin/en
    (println "Hello world!")
 
 Finally, Basilisp has a command line option to bootstrap your Python installation such that Basilisp will already be importable whenever Python is started.
-This takes advantage of the ``.pth`` file feature supported by the `site <https://docs.python.org/3/library/site.html>`_ package.
+This takes advantage of the ``.pth`` file feature supported by the :external:py:mod:`site` package.
 Specifically, any file with a ``.pth`` extension located in any of the known ``site-packages`` directories will be read at startup and, if any line of such a file starts with ``import``, it is executed.
 
 .. code-block:: bash

docs/pyinterop.rst

@@ -220,7 +220,7 @@ Basilisp supports passing type hints through to the underlying generated Python
 In Clojure, these tags are type declarations for certain primitive types.
 In Clojurescript, tags are type *hints* and they are only necessary in extremely limited circumstances to help the compiler.
 In Basilisp, tags are not used by the compiler at all.
-Instead, tags applied to function arguments and return values in Basilisp are applied to the underlying Python objects and are introspectable at runtime using the Python `inspect <https://docs.python.org/3/library/inspect.html>`_ standard library module.
+Instead, tags applied to function arguments and return values in Basilisp are applied to the underlying Python objects and are introspectable at runtime using the Python :external:py:mod:`inspect` standard library module.
 
 Type hints may be applied to :lpy:form:`def` names, function arguments and return values, and :lpy:form:`let` local forms.
 
@@ -259,4 +259,4 @@ In Clojure, the ``clojure.core/quot`` function utilizes Java's long division ope
 
 Basilisp has chosen to adopt the same mathematical formulae as Clojure for these three functions, rather than using the Python's built in operators under all cases. This approach offers the advantage of enhanced cross-platform compatibility without requiring modification, and ensures compatibility with examples in  `ClojureDocs <https://clojuredocs.org/>`_.
 
-Users still have the option to use the native `operator/floordiv <https://docs.python.org/3/library/operator.html#operator.floordiv>`_, i.e. Python's ``//``  operator, if they prefer so.
+Users still have the option to use the native :external:py:func:`operator.floordiv`, i.e. Python's ``//``  operator, if they prefer so.

docs/reader.rst

@@ -71,7 +71,7 @@ Floating point values are represented using ``0-9`` and a trailing decimal value
 Like integers, floating point values may be prefixed with a single negative sign ``-``.
 By default floating point values are represented by Python's ``float`` type, which does **not** support arbitrary precision by default.
 Like in Clojure, floating point literals may be specified with a single ``M`` suffix to specify an arbitrary-precision floating point value.
-In Basilisp, a floating point number declared with a trailing ``M`` will return Python's `Decimal <https://docs.python.org/3/library/decimal.html>`_ type, which supports arbitrary floating point arithmetic.
+In Basilisp, a floating point number declared with a trailing ``M`` will return Python's :external:py:class:`decimal.Decimal` type, which supports arbitrary floating point arithmetic.
 
 .. _scientific_notation:
 
@@ -125,7 +125,7 @@ Ratios
 Basilisp includes support for ratios.
 Ratios are represented as the division of 2 integers which cannot be reduced to an integer.
 As with integers and floats, the numerator of a ratio may be prefixed with a single negative sign ``-`` -- a negative sign may not appear in the denominator.
-In Basilisp, ratios are backed by Python's `Fraction <https://docs.python.org/3/library/fractions.html>`_ type, which is highly interoperable with other Python numeric types.
+In Basilisp, ratios are backed by Python's :external:py:class:`fractions.Fraction` type, which is highly interoperable with other Python numeric types.
 
 .. _strings:
 
@@ -391,7 +391,7 @@ Reader macros are always dispatched using the ``#`` character.
 * ``#'form`` is rewritten as ``(var form)``.
 * ``#_form`` causes the reader to completely ignore ``form``.
 * ``#!form`` is treated as a single-line comment (like ``;form``) as a convenience to support `shebangs <https://en.wikipedia.org/wiki/Shebang_(Unix)>`_ at the top of Basilisp scripts.
-* ``#"str"`` causes the reader to interpret ``"str"`` as a regex and return a Python `re.pattern <https://docs.python.org/3/library/re.html>`_.
+* ``#"str"`` causes the reader to interpret ``"str"`` as a regex and return a Python :external:py:mod:`re.pattern <re>`.
 * ``#(...)`` causes the reader to interpret the contents of the list as an anonymous function. Anonymous functions specified in this way can name arguments using ``%1``, ``%2``, etc. and rest args as ``%&``. For anonymous functions with only one argument, ``%`` can be used in place of ``%1``.
 
 .. _data_readers:
@@ -407,8 +407,8 @@ User-specified data reader symbols must include a namespace, but builtin data re
 
 Basilisp supports a few builtin data readers:
 
-* ``#inst "2018-09-14T15:11:20.253-00:00"`` yields a Python `datetime <https://docs.python.org/3/library/datetime.html#datetime-objects>`_ object.
-* ``#uuid "c3598794-20b4-48db-b76e-242f4405743f"`` yields a Python `UUID <https://docs.python.org/3/library/uuid.html#uuid.UUID>`_ object.
+* ``#inst "2018-09-14T15:11:20.253-00:00"`` yields a Python :external:py:class:`datetime.datetime` object.
+* ``#uuid "c3598794-20b4-48db-b76e-242f4405743f"`` yields a Python :external:py:class`uuid.UUID` object.
 
 One of the benefits of choosing Basilisp is convenient built-in Python language interop.
 However, the immutable data structures of Basilisp may not always play nicely with code written for (and expecting to be used by) other Python code.

docs/requirements.txt

@@ -2,7 +2,7 @@
 # to maintain consistent output during both development and publishing
 # on Read The Docs.
 sphinx>=7.1.0,<8.0.0
-sphinx-rtd-theme>=2.0.0,<3.0.0
+furo==2024.04.27
 sphinxcontrib-applehelp>=1.0.8,<2.0.0
 sphinxcontrib-devhelp>=1.0.6,<2.0.0
 sphinxcontrib-htmlhelp>=2.0.5,<3.0.0