Add reference page to documentation using Sphinx autodoc (#312)

* Docstrings and type annotations for almost every method
* New /reference API documentation page using Sphink autodoc
* Custom Read The Docs config, to get autodoc working
* Fix for #313 (add_foreign_keys() doesn't reject being called with a View)
* Fixed #315 (.delete_where() returns [] when it should return self)

.readthedocs.yaml

@@ -0,0 +1,12 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  version: "3.8"
+  install:
+  - method: pip
+    path: .
+    extra_requirements:
+    - docs

docs/Makefile

@@ -20,4 +20,4 @@ help:
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 livehtml:
-	sphinx-autobuild -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0)
+	sphinx-autobuild -a -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(0) --watch ../sqlite_utils

docs/conf.py

@@ -30,7 +30,8 @@ from subprocess import Popen, PIPE
 # 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.extlinks"]
+extensions = ["sphinx.ext.extlinks", "sphinx.ext.autodoc"]
+autodoc_member_order = "bysource"
 
 extlinks = {
     "issue": ("https://github.com/simonw/sqlite-utils/issues/%s", "#"),

docs/index.rst

@@ -32,6 +32,7 @@ Contents
    installation
    cli
    python-api
+   reference
    contributing
    changelog
 

docs/python-api.rst

@@ -962,7 +962,7 @@ The ``table.analyze_column(column, common_limit=10, value_truncate=None)`` metho
     The name of the column
 
 ``total_rows``
-    The total number of rows in the table`
+    The total number of rows in the table
 
 ``num_null``
     The number of rows for which this column is null

docs/reference.rst

@@ -0,0 +1,69 @@
+===============
+ API Reference
+===============
+
+.. contents:: :local:
+
+.. _reference_db_database:
+
+sqlite_utils.db.Database
+========================
+
+.. autoclass:: sqlite_utils.db.Database
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :special-members: __getitem__
+    :exclude-members: use_counts_table, execute_returning_dicts, resolve_foreign_keys
+
+.. _reference_db_queryable:
+
+sqlite_utils.db.Queryable
+=========================
+
+:ref:`Table <reference_db_table>` and :ref:`View <reference_db_view>` are  both subclasses of ``Queryable``, providing access to the following methods:
+
+.. autoclass:: sqlite_utils.db.Queryable
+    :members:
+    :undoc-members:
+    :exclude-members: execute_count
+
+.. _reference_db_table:
+
+sqlite_utils.db.Table
+=====================
+
+.. autoclass:: sqlite_utils.db.Table
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :exclude-members: guess_foreign_column, value_or_default, build_insert_queries_and_params, insert_chunk, add_missing_columns
+
+.. _reference_db_view:
+
+sqlite_utils.db.View
+====================
+
+.. autoclass:: sqlite_utils.db.View
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. _reference_db_other:
+
+Other
+=====
+
+.. _reference_db_other_column:
+
+sqlite_utils.db.Column
+----------------------
+
+.. autoclass:: sqlite_utils.db.Column
+
+.. _reference_db_other_column_details:
+
+sqlite_utils.db.ColumnDetails
+-----------------------------
+
+.. autoclass:: sqlite_utils.db.ColumnDetails