Add documentation for Basilisp interfaces (#920)

Add some initial documentation around the Python interfaces which
underpin most Basilisp collection functions.

Author: chrisrink10

CHANGELOG.md

@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Other
  * Add REPL documentation module (#205)
+ * Add documentation module for Basilisp interfaces (#920)
  * Update Sphinx documentation theme (#909)
  * Update documentation to directly reference Python documentation and fix many other minor issues and misspellings (#907, #919)
 

Makefile

@@ -8,7 +8,7 @@ docs:
 
 .PHONY: livedocs
 livedocs:
-	@poetry run sphinx-autobuild "$(DOCSOURCEDIR)" "$(DOCBUILDDIR)" -b html
+	@poetry run sphinx-autobuild "$(DOCSOURCEDIR)" "$(DOCBUILDDIR)" -b html --watch "./src"
 
 
 .PHONY: format

docs/interfaces.rst

@@ -0,0 +1,31 @@
+Interfaces
+==========
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+Basilisp (like Clojure) is defined by interfaces.
+All of the built-in data types are implement 0 or more of these Python interfaces and :lpy:ns:`basilisp.core` functions typically operate on these interfaces, rather than concrete data types (with some exceptions).
+
+In day-to-day usage, you will not typically need to use these interfaces, but they are nevertheless helpful for understanding the abstractions Basilisp is built upon.
+
+.. warning::
+
+   These interfaces are not considered part of the Basilisp public API and therefore are subject to change at any time without notice.
+   This documentation is intended to help users understand the abstractions that underpin Basilisp.
+
+.. class:: basilisp.lang.interfaces.ILispObject
+
+   Abstract base class for Lisp objects which would like to customize their ``__str__`` and Python ``__repr__`` representation.
+
+   .. automethod:: _lrepr
+   .. automethod:: lrepr
+
+.. lpy:currentns::  basilisp.core
+
+.. automodule:: basilisp.lang.interfaces
+   :members:
+   :undoc-members:
+   :exclude-members: seq_equals
+   :show-inheritance:

docs/reference.rst

@@ -6,6 +6,7 @@ Reference
    :caption: Contents:
 
    api
+   interfaces
    cli
    repl
    reader

src/basilisp/core.lpy

@@ -907,10 +907,10 @@
 (defn deref
   "Dereference a delay or atom and returns its contents.
 
-  If ``o`` is an object implementing ``IBlockingDeref`` and ``timeout-s`` and
-  ``timeout-val`` are supplied, ``deref`` will wait at most ``timeout-s`` seconds,
-  returning ``timeout-val`` if ``timeout-s`` seconds elapse and ``o`` has not
-  returned."
+  If ``o`` is an object implementing :py:class:`basilisp.lang.interfaces.IBlockingDeref`
+  and ``timeout-s`` and ``timeout-val`` are supplied, ``deref`` will wait at most
+  ``timeout-s`` seconds, returning ``timeout-val`` if ``timeout-s`` seconds elapse and
+  ``o`` has not returned."
   ([o]
    (basilisp.lang.runtime/deref o))
   ([o timeout-s timeout-val]
@@ -1208,7 +1208,7 @@
   true)
 
 (defn ^:inline associative?
-  "Return ``true`` if ``x`` implements ``IAssociative``  ."
+  "Return ``true`` if ``x`` implements :py:class:`basilisp.lang.interfaces.IAssociative`."
   [x]
   (instance? basilisp.lang.interfaces/IAssociative x))
 
@@ -1243,7 +1243,7 @@
   (instance? python/type x))
 
 (defn ^:inline coll?
-  "Return ``true`` if ``x`` implements ``IPersistentCollection``\\."
+  "Return ``true`` if ``x`` implements :py:class:`basilisp.lang.interfaces.IPersistentCollection`\\."
   [x]
   (instance? basilisp.lang.interfaces/IPersistentCollection x))
 
@@ -1325,7 +1325,7 @@
   integer?)
 
 (defn ^:inline map-entry?
-  "Return ``true`` if ``x`` implements ``IMapEntry``\\."
+  "Return ``true`` if ``x`` implements :py:class:`basilisp.lang.interfaces.IMapEntry`\\."
   [x]
   (instance? basilisp.lang.interfaces/IMapEntry x))
 
@@ -1440,17 +1440,18 @@
   (or (integer? x) (float? x)))
 
 (defn ^:inline reversible?
-  "Return ``true`` if x implements ``IReversible``\\."
+  "Return ``true`` if x implements :py:class:`basilisp.lang.interfaces.IReversible`\\."
   [x]
   (instance? basilisp.lang.interfaces/IReversible x))
 
 (defn ^:inline seqable?
-  "Return ``true`` if an ``ISeq`` can be produced from ``x``\\."
+  "Return ``true`` if an :py:class:`basilisp.lang.interfaces.ISeq` can be produced from
+  ``x``\\."
   [x]
   (instance? basilisp.lang.interfaces/ISeqable x))
 
 (defn ^:inline sequential?
-  "Return ``true`` if ``x`` implements ``ISequential``\\."
+  "Return ``true`` if ``x`` implements :py:class:`basilisp.lang.interfaces.ISequential`\\."
   [x]
   (instance? basilisp.lang.interfaces/ISequential x))
 
@@ -2002,8 +2003,9 @@
     (or (.- ex __cause__) (.- ex __context__))))
 
 (defn ex-data
-  "Return the data map of ``ex`` if is an instance of ``IExceptionInfo``\\, otherwise
-  it returns ``nil``\\."
+  "Return the data map of ``ex`` if is an instance of
+  :py:class:`basilisp.lang.interfaces.IExceptionInfo`\\, otherwise it returns
+  ``nil``\\."
   [ex]
   (when (instance? basilisp.lang.interfaces/IExceptionInfo ex)
     (.-data ex)))