Add reference page to documentation using Sphinx autodoc

[simonw]

Refs #311.

[simonw]

On Python 3.6:

sqlite_utils/db.py:366: in Database
    def tables(self) -> List[Table]:
E   NameError: name 'Table' is not defined

Python 3.7 can fix this with from __future__ import annotations but since we still support 3.6 I'll have to use a string instead.

[simonw]

I'm going to get Read The Docs to build the docs for this branch too - on https://readthedocs.org/projects/sqlite-utils/versions/ I am clicking this button:

I then set it to "active" (so pushes to the branch will build it) and "hidden" (so it wouldn't show up in search or in the navigation menu). https://docs.readthedocs.io/en/stable/versions.html#version-states

[codecov]

Codecov Report

Merging #312 (43bc064) into main (ee469e3) will decrease coverage by 0.02%.
The diff coverage is 96.84%.

@@            Coverage Diff             @@
##             main     #312      +/-   ##
==========================================
- Coverage   96.30%   96.28%   -0.03%     
==========================================
  Files           5        5              
  Lines        2168     2179      +11     
==========================================
+ Hits         2088     2098      +10     
- Misses         80       81       +1     

Impacted Files	Coverage Δ
sqlite_utils/db.py	97.91% <96.84%> (-0.08%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ee469e3...43bc064. Read the comment docs.

[simonw]

Docs are now building at https://sqlite-utils.datasette.io/en/autodoc/reference.html

But there's a problem! The page is semi-blank:

I need to teach Read The Docs how to ensure sqlite_utils is available for introspection.

[simonw]

https://sphinx-rtd-tutorial.readthedocs.io/en/latest/sphinx-config.html#autodoc-configuration says do something like this at the top of conf.py:

import os
import sys
sys.path.insert(0, os.path.abspath('../../simpleble/'))

[simonw]

Reading the rest of https://sphinx-rtd-tutorial.readthedocs.io/en/latest/sphinx-config.html#autodoc-configuration it suggests using a requirements.txt file to install dependencies - but I use setup.py for that so I need to figure out a different pattern here.

[simonw]

From https://docs.readthedocs.io/en/stable/config-file/v2.html#packages it looks like I can tell Read The Docs to run pip install -e . using a .readthedocs.yaml configuration:

version: 2

sphinx:
   configuration: docs/conf.py

python:
  version: "3.9"
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

[simonw]

That worked! https://sqlite-utils.datasette.io/en/autodoc/reference.html

[simonw]

Adding type signatures to create_table() and .create_table_sql() is a bit too involved, I'll do that in a separate issue.

[simonw]

Spotted a rogue backtick:

[simonw]

Need to file a bug report about this so I can mention it in the release notes.