This should (mostly) complete the documentation transition

.readthedocs.yaml

@@ -11,6 +11,10 @@ build:
   tools:
     python: "3.11"
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/conf.py
+mkdocs:
+  configuration: mkdocs.yml
+
+python:
+  install:
+    - method: pip
+      path: .[docs]

dbkit/__init__.py

@@ -548,7 +548,7 @@ def connect(module, *args, **kwargs):
     """
     Connect to a database using the given DB-API driver module. Returns a
     database context representing that connection. Any arguments or keyword
-    arguments are passed the module's :py:func:`connect` function.
+    arguments are passed the driver module's connect() function.
     """
     mdr = SingleConnectionMediator(module, _make_connect(module, args, kwargs))
     return Context(module, mdr)
@@ -621,7 +621,7 @@ def transactional(wrapped):
     is to be ran in a transaction.
 
     The following code is equivalent to the example for
-    [dbkit.transaction]:
+    [dbkit.transaction][]:
 
     ```python
     import sqlite3

docs/examples.md

@@ -13,8 +13,7 @@ examples/counters.py
 
 ## pools.py {#pools-py-example}
 
-A small web application, built using [web.py](http://webpy.org/),
-[pystache](https://github.com/defunkt/pystache), and
+A small web application, built using [Bottle](bottlepy.org/) and
 [psycopg2](http://initd.org/psycopg/), to say that prints "Hello, *name*"
 based on the URL fetched, and which records how many times it's said hello to
 a particular name.

docs/index.md

@@ -1,6 +1,6 @@
-# dbkit: taking the pain out of database access in Python
+# dbkit
 
-*dbkit* is a library that abstracts away at least part of the pain
-involved in dealing with [DB-API 2] compatible database drivers.
+*dbkit* is a library that abstracts away at least part of the pain involved in
+dealing with [DB-API 2] compatible database drivers.
 
 [DB-API 2]: http://www.python.org/dev/peps/pep-0249/

docs/reference.md

@@ -7,7 +7,7 @@
 ## Contexts
 
 Contexts wrap a notional database connection. They're returned by the
-`dbkit.connect` function. Methods are for the internal use of dbkit only though
+[dbkit.connect][] function. Methods are for the internal use of dbkit only though
 it does expose a method for closing the database connection when you're done
 with it and contains references for each of the exceptions exposed by the
 connection's database driver. For a list of these exceptions, see
@@ -65,9 +65,9 @@ Result generators are generator functions that are used internally by dbkit to
 take the results from a database cursor and turn them into a form that's easier
 to deal with programmatically, such a sequence of tuples or a sequence of
 dictionaries, where each tuple or dictionary represents a row of the result
-set. By default, `dbkit.TupleFactory` is used as the result generator, but you
-can change this by assigning another, such as `dbkit.DictFactory` to
-`dbkit.Context.default_factory` function.
+set. By default, [dbkit.TupleFactory][] is used as the result generator, but you
+can change this by assigning another, such as [dbkit.DictFactory][] to
+[dbkit.Context.default_factory][] function.
 
 Some query functions allow you to specify the result generator to be used for
 the result, which is passed in using the `factory` parameter.

docs/tutorial.md

@@ -43,13 +43,13 @@ value = query_value(
 
 And we don't need to worry about the database connection we're actually dealing
 with. With that in mind, here's how we'd implement getting a counter's value
-with `dbkit.query_value`:
+with [dbkit.query_value][]:
 
 ```python
 --8<-- "examples/counters.py:get_counter"
 ```
 
-To perform updates, there's the `dbkit.execute` function. Here's how we
+To perform updates, there's the [dbkit.execute][] function. Here's how we
 increment a counter's value:
 
 ```python
@@ -60,8 +60,9 @@ execute(
 ```
 
 dbkit also makes dealing with transactions very easy. It provides two
-mechanisms: the `dbkit.transaction` context manager and `dbkit.transactional`
-decorator. Let's implement incrementing the counter using the context manager:
+mechanisms: the [dbkit.transaction][] context manager and
+[dbkit.transactional][] decorator. Let's implement incrementing the counter
+using the context manager:
 
 ```python
 def increment_counter(counter, by):
@@ -92,15 +93,15 @@ Deleting a counter:
 ```
 
 dbkit also has ways to query for result sets. Once of these is
-`dbkit.query_column`, which returns an iterable of the first column in the
+[dbkit.query_column][], which returns an iterable of the first column in the
 result set. Thus, to get a list of counters, we'd do this:
 
 ```python
 --8<-- "examples/counters.py:list_counters"
 ```
 
 One last thing that our tool ought to be able to do is dump the contents of the
-_counters_ table. To do this, we can use `dbkit.query`:
+_counters_ table. To do this, we can use [dbkit.query][]:
 
 ```python
 --8<-- "examples/counters.py:dump_counters"
@@ -114,7 +115,7 @@ This will return a sequence of result set rows you can iterate over like so:
 
 By default, `query()` will use tuples for each result set row, but if you'd
 prefer dictionaries, all you have to do is pass in a different row factory when
-you call `dbkit.query` using the `factory` parameter:
+you call [dbkit.query][] using the `factory` parameter:
 
 ```python
 def dump_counter_dict():
@@ -124,10 +125,10 @@ def dump_counter_dict():
     )
 ```
 
-`dbkit.DictFactory` is a row factory that generates a result set where each row
-is a dictionary. The default row factory is `dbkit.TupleFactory`, which yields
-tuples for each row in the result set. Using `dbkit.DictFactory`, we'd print
-the counters and values like so:
+[dbkit.DictFactory][] is a row factory that generates a result set where each
+row is a dictionary. The default row factory is [dbkit.TupleFactory][], which
+yields tuples for each row in the result set. Using [dbkit.DictFactory][], we'd
+print the counters and values like so:
 
 ```python
 def print_counters_and_values():
@@ -139,7 +140,7 @@ Now we have enough for our counter management application, so lets start on the
 main function. We'll have the following subcommands: `set`, `get`, `del`,
 `list`, `incr`, `list`, and `dump`. The `dispatch()` function below deals with
 calling the right function based on the command line arguments, so all we need
-to create a database connection context with `dbkit.connect`. It takes the
+to create a database connection context with [dbkit.connect][]. It takes the
 database driver module as its first argument, and any parameters you'd pass to
 that module's `connect()` function to create a new connection as its remaining
 arguments:

pyproject.toml

@@ -28,6 +28,16 @@ classifiers = [
 [project.urls]
 Homepage = "https://github.com/kgaughan/dbkit/"
 
+[project.optional-dependencies]
+docs = [
+	"mkdocs-material==9.1.15",
+	"mkdocs-autorefs==0.4.1",
+	"mkdocstrings[python]==0.20.0",
+	"mkdocs-redirects==1.2.0",
+	"pymdown-extensions==10.0.1",
+	"Pygments==2.15.1",
+]
+
 [tool.hatch.version]
 path = "dbkit/__init__.py"
 
@@ -81,19 +91,16 @@ fmt = [
 ]
 
 [tool.hatch.envs.docs]
-dependencies = [
-	"mkdocs-material==9.1.15",
-	"mkdocs-autorefs==0.4.1",
-	"mkdocstrings[python]==0.20.0",
-	"mkdocs-redirects==1.2.0",
-	"pymdown-extensions==10.0.1",
-	"Pygments==2.15.1",
-]
+dependencies = []
+features = ["docs"]
 
 [tool.hatch.envs.docs.scripts]
 build = [
 	"mkdocs build",
 ]
+serve = [
+	"mkdocs serve",
+]
 
 [tool.isort]
 profile = "black"