Minor documentation fixes (#919)

* Added
[`sphinx-autobuild`](https://github.com/sphinx-doc/sphinx-autobuild) to
improve documentation development flow
* Added
[`sphinx-copybutton`](https://github.com/executablebooks/sphinx-copybutton)
and
[`sphinxext-opengraph`](https://github.com/wpilibsuite/sphinxext-opengraph)
extension to the Read the Docs build
* Updating tons of references across the entire codebase to the official
Python documentation using
[`intersphinx`](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html)
(added in #909)

Author: chrisrink10

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 ### Added
  * Added `:end-line` and `:end-col` metadata to forms during compilation (#903)
+ * Added `basilisp.repl/source` to allow inspecting source code from the REPL (#205)
 
 ### Changed
  * Updated dozens of type annotations in the compiler to satisfy MyPy 1.11 (#910)
@@ -21,8 +22,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  * Fix a bug where reader column offset numbering began at 1, rather than 0 (#905)
 
 ### Other
+ * Add REPL documentation module (#205)
  * Update Sphinx documentation theme (#909)
- * Fix a few minor documentation issues (#907)
+ * Update documentation to directly reference Python documentation and fix many other minor issues and misspellings (#907, #919)
 
 ## [v0.1.0b2]
 ### Added

Makefile

@@ -1,6 +1,14 @@
+DOCSOURCEDIR = "./docs"
+DOCBUILDDIR = "./docs/_build"
+
 .PHONY: docs
 docs:
-	@poetry run sphinx-build -M html "./docs" "./docs/_build"
+	@poetry run sphinx-build -M html "$(DOCSOURCEDIR)" "$(DOCBUILDDIR)"
+
+
+.PHONY: livedocs
+livedocs:
+	@poetry run sphinx-autobuild "$(DOCSOURCEDIR)" "$(DOCBUILDDIR)" -b html
 
 
 .PHONY: format

docs/cli.rst

@@ -92,7 +92,7 @@ Run Basilisp as an Application
 
 Python applications don't have nearly as many constraints on their entrypoints as do Java applications.
 Nevertheless, developers may have a clear entrypoint in mind when designing their application code.
-In such cases, it may be desirable to take advantage of the computed Python ``sys.path`` to invoke your entrypoint.
+In such cases, it may be desirable to take advantage of the computed Python :external:py:data:`sys.path` to invoke your entrypoint.
 To do so, you can use the ``basilisp run -n`` flag to invoke an namespace directly:
 
 .. code-block:: bash

docs/concepts.rst

@@ -216,6 +216,13 @@ References and Refs
 
 TBD
 
+.. _volatiles:
+
+Volatiles
+---------
+
+TBD
+
 .. _transducers:
 
 Transducers

docs/conf.py

@@ -30,6 +30,8 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
+    "sphinxext.opengraph",
+    "sphinx_copybutton",
     "basilisp.contrib.sphinx",
 ]
 

docs/requirements.txt

@@ -8,3 +8,5 @@ sphinxcontrib-devhelp>=1.0.6,<2.0.0
 sphinxcontrib-htmlhelp>=2.0.5,<3.0.0
 sphinxcontrib-qthelp>=1.0.7,<2.0.0
 sphinxcontrib-serializinghtml>=1.1.10,<2.0.0
+sphinx-copybutton>=0.5.2,<1.0.0
+sphinxext-opengraph>=0.9.1,<1.0.0

pyproject.toml

@@ -57,6 +57,9 @@ pytest-pycharm = "*"
 # to maintain consistent output during both development and publishing on
 # Read The Docs.
 sphinx = "^7.1.0"
+sphinx-autobuild = { version = "^2024.04.16", python = ">=3.9" }
+sphinx-copybutton = "^0.5.2"
+sphinxext-opengraph = "^v0.9.1"
 furo = "^2023.08.19"
 tox = "*"
 

src/basilisp/contrib/bencode.lpy

@@ -1,6 +1,7 @@
 ;; Decoding logic adapted from
 ;; https://github.com/babashka/nbb/blob/bca8b5017a06768eb35d02a2d6233ca9c6c2f692/src/nbb/impl/bencode.cljs
 (ns basilisp.contrib.bencode
+  "Support for bencode encoding and decoding."
   (:require
    [basilisp.string :as str]))
 
@@ -82,24 +83,24 @@
 
   ``encode`` supports encoding the following types:
 
-  - ``bytes``
-  - ``int``
-  - ``str``, which is first decided to UTF-8 ``bytes``
+  - :external:py:class:`bytes`
+  - :external:py:class:`int`
+  - :external:py:class:`str` , which is first decoded to UTF-8 ``bytes``
   - keywords and symbols, which are first converted to strings (including namespace,
     separated by '/') and then converted using the rules for ``str`` s
-  - Python ``list``
-  - ``tuple``
-  - Basilisp lists and vectors
-  - ``dict``
-  - maps
+  - :external:py:class:`list`
+  - :external:py:class:`tuple`
+  - :external:py:class:`dict`
+  - Basilisp lists, vectors, and maps
 
   Mapping type keys must one of: keywords, symbols, or strings.
 
   This function does not support ``float`` because the ``bencode`` specification does
   not support non-integer numerics.
 
-  Set types (including ``frozenset``, ``set``, or Basilisp's set types) are not
-  supported due to the requirement that lists retain their original element ordering."
+  Set types (including :external:py:class:`frozenset` , :external:py:class:`set`, or
+  Basilisp's set types) are not supported due to the requirement that lists retain
+  their original element ordering."
   [d]
   (to-bencode-encodeable* d))
 
@@ -111,11 +112,10 @@
   `(.index ~b ~c))
 
 (defn- slice
-  "Returns the slice of the ``bytes`` from the ``start`` index to
-  the end of the array or to the ``end`` index if provided. Returns
-  `nil` if the slice is empty.
+  "Returns the slice of the ``bytes`` from the ``start`` index to the end of the
+  array or to the ``end`` index if provided. Returns ``nil`` if the slice is empty.
 
-  Throw a `python/EOFError` exception if any of the indices are out
+  Throw a :external:py:exc:`python.EOFError` exception if any of the indices are out
   of bounds."
   ([bytes start]
    (if (< (len bytes) start)
@@ -178,13 +178,13 @@
 
 (defn decode
   "Decode the first value in the bencoded ``data`` bytes according to ``opts`` and
-  return a [decoded* rest*] vector.
+  return a ``[decoded* rest*]`` vector.
 
   The decoded* item in the vector is the decoded value of the first item in ``data``
   while rest* is the remaining unencoded values.
 
   If ``data`` cannot be decoded (e.g. is incomplete or an error occurred), it returns
-  a [nil ``data``] vector.
+  a ``[nil data]`` vector.
 
   ``opts`` is a map with the following optional supported keys.
 
@@ -207,12 +207,12 @@
         [nil data]))))
 
 (defn decode-all
-  "Decode all values in the bencoded ``data`` bytes and return them as
-  a [values* incomplete*] vector.
+  "Decode all values in the bencoded ``data`` bytes and return them as a
+  ``[values* incomplete*]`` vector.
 
-  The values* item is a collection of the ``data`` decoded values,
-  while incomplete* is the rest of the ``data`` bytes that could not
-  be decoded or nil.
+  The ``values*`` item is a collection of the ``data`` decoded values, while
+  ``incomplete*`` is the rest of the ``data`` bytes that could not be decoded
+  or ``nil``.
 
   ``opts`` is a map supporting the same keys as :lpy:fn:`decode`."
   ([data]