Modernize RTD site with Furo theme, improved structure, and new extensions

- Switch from Alabaster to Furo theme for modern look, dark mode, and
  responsive layout
- Add sphinx-copybutton, sphinx-design, intersphinx, and opengraph extensions
- Refactor comparison section to use tabbed layouts instead of long
  sequential code blocks
- Fix user_guide.rst title mismatch (was "Installation", now "User Guide")
- Replace redundant modules.rst/cruds.rst chain with single api.rst
- Add CI, RTD, and PyPI version badges to index page
- Use code-block:: console for shell commands (proper highlighting)
- Expand development.rst with testing, code quality, and issue filing sections
- Fix copyright year to be dynamic (2020-current)
- Fix project.urls to use https for RTD links
- Configure .readthedocs.yaml to install package with [rtd] extras

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: johnbrandborg

.readthedocs.yaml

@@ -1,35 +1,19 @@
 # Read the Docs configuration file for Sphinx projects
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
 version: 2
 
-# Set the OS, Python version and other tools you might need
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
-    # You can also specify other tool versions:
-    # nodejs: "20"
-    # rust: "1.70"
-    # golang: "1.20"
+    python: "3.12"
 
-# Build documentation in the "docs/" directory with Sphinx
 sphinx:
   configuration: docs/conf.py
-  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
-  # builder: "dirhtml"
-  # Fail on all warnings to avoid broken references
-  # fail_on_warning: true
 
-# Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#   - pdf
-#   - epub
-
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#   install:
-#     - requirements: docs/requirements.txt
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - rtd

docs/_static/.gitkeep

@@ -1,45 +1,43 @@
-cruds package
+.. _api-reference:
+
+=============
+API Reference
 =============
 
-Submodules
-----------
+This section documents the public API of the CRUDs package.
 
-cruds.auth module
------------------
+Client
+======
 
-.. automodule:: cruds.auth
+.. autoclass:: cruds.Client
    :members:
    :undoc-members:
    :show-inheritance:
 
-cruds.core module
------------------
+Authentication
+==============
 
-.. automodule:: cruds.core
+.. autoclass:: cruds.core.AuthABC
    :members:
-   :undoc-members:
    :show-inheritance:
 
-cruds.exception module
-----------------------
-
-.. automodule:: cruds.exception
+.. automodule:: cruds.auth
    :members:
    :undoc-members:
    :show-inheritance:
 
-cruds.interface module
-----------------------
+Exceptions
+==========
 
-.. automodule:: cruds.interface
+.. automodule:: cruds.exception
    :members:
    :undoc-members:
    :show-inheritance:
 
-Module contents
----------------
+Interfaces
+==========
 
-.. automodule:: cruds
+.. automodule:: cruds.interface
    :members:
    :undoc-members:
    :show-inheritance:

docs/cruds.rst docs/api.rstdocs/cruds.rst renamed to docs/api.rst

@@ -4,6 +4,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 import os
 import sys
+from datetime import datetime
 
 sys.path.insert(0, os.path.abspath("../src"))
 
@@ -13,7 +14,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "CRUDs"
-copyright = "2024, John Brandborg"
+copyright = f"2020–{datetime.now().year}, John Brandborg"
 author = "John Brandborg"
 version = cruds.__version__
 release = cruds.__version__
@@ -23,8 +24,12 @@
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+    "sphinx_design",
+    "sphinxext.opengraph",
 ]
 
 templates_path = ["_templates"]
@@ -34,12 +39,27 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "alabaster"
+html_theme = "furo"
 html_static_path = ["_static"]
 html_theme_options = {
-    "description": "API interaction made easy",
-    "github_user": "johnbrandborg",
-    "github_repo": "cruds",
-    "github_banner": True,
-    "fixed_sidebar": True,
+    "source_repository": "https://github.com/johnbrandborg/cruds",
+    "source_branch": "main",
+    "source_directory": "docs/",
 }
+
+# -- Intersphinx mapping ----------------------------------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "urllib3": ("https://urllib3.readthedocs.io/en/stable/", None),
+}
+
+# -- Copy button settings ----------------------------------------------------
+
+copybutton_prompt_text = r"^\$ "
+copybutton_prompt_is_regexp = True
+
+# -- Open Graph settings -----------------------------------------------------
+
+ogp_site_url = "https://cruds.readthedocs.io/en/latest/"
+ogp_description_length = 200

docs/conf.py

@@ -1,11 +1,13 @@
 .. _development:
 
+===========
 Development
 ===========
 
-At this time because the CRUDs code base is located on a repository not located
-under an Organization, to contribute it is recommended that you create a fork of
-CRUDs and then `Create a PR <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_
+Contributions are welcome! At this time because the CRUDs code base is located on
+a repository not located under an Organization, to contribute it is recommended
+that you create a fork of CRUDs and then `Create a PR
+<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_
 from there.
 
 Setup
@@ -15,23 +17,67 @@ It is highly recommended to create a virtual environment of Python.  There are
 multiple ways to do this.  The standard way is using Pythons very own
 `venv <https://docs.python.org/3/library/venv.html>`_.
 
-Once you have a forked the CRUD repository and obtained a local copy of the
-source code use the develop target to install the package in edit mode and the
-extra packages used for development.
+Once you have forked the CRUDs repository and obtained a local copy of the
+source code, use the develop target to install the package in edit mode and the
+extra packages used for development:
 
 .. code-block:: console
 
     $ cd cruds
     $ make develop
 
 The reason for using the Makefile is that the targets within it are also used by
-the Github Actions when testing, and linting.  By making these available on the
+the Github Actions when testing and linting.  By making these available on the
 command line it's easy to run the same commands and ensure everything passes before
-commiting the code.
+committing the code.
 
 To display the menu of the Makefile, run ``make`` with no target (argument).
 
 .. tip::
 
     If you don't use Make you can run the commands manually, by opening the Makefile
     and copying the commands under the relevant targets into a terminal.
+
+Running Tests
+-------------
+
+CRUDs uses `pytest <https://docs.pytest.org/>`_ for testing with coverage
+reporting enabled by default:
+
+.. code-block:: console
+
+    $ make test
+
+To generate an XML coverage report (used by CI):
+
+.. code-block:: console
+
+    $ make test-report
+
+Code Quality
+------------
+
+Linting and formatting are handled by `Ruff <https://docs.astral.sh/ruff/>`_:
+
+.. code-block:: console
+
+    $ make lint
+    $ make format
+
+Static type checking is done with `ty <https://docs.astral.sh/ty/>`_:
+
+.. code-block:: console
+
+    $ make typecheck
+
+Filing Issues
+-------------
+
+If you find a bug or have a feature request, please open an issue on the
+`GitHub issue tracker <https://github.com/johnbrandborg/cruds/issues>`_.
+When reporting bugs, include:
+
+- Python version and OS
+- CRUDs version (``python -c "import cruds; print(cruds.__version__)"``  )
+- A minimal reproducible example
+- The full traceback if applicable

docs/development.rst

@@ -1,14 +1,13 @@
-.. CRUDs documentation master file, created by
-   sphinx-quickstart on Thu Aug  8 10:58:11 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-====
+=====
 CRUDs
-====
+=====
 
 Release v\ |version|
 
+.. image:: https://img.shields.io/pypi/v/cruds
+    :target: https://pypi.org/project/cruds/
+    :alt: PyPI Version
+
 .. image:: https://img.shields.io/pypi/pyversions/cruds?logo=python&logoColor=FFE873
     :target: https://pypi.org/project/cruds/
     :alt: Supported Python Version
@@ -17,6 +16,14 @@ Release v\ |version|
     :target: https://pypistats.org/packages/cruds
     :alt: PyPI downloads
 
+.. image:: https://github.com/johnbrandborg/cruds/actions/workflows/development.yml/badge.svg
+    :target: https://github.com/johnbrandborg/cruds/actions/workflows/development.yml
+    :alt: CI Status
+
+.. image:: https://readthedocs.org/projects/cruds/badge/?version=latest
+    :target: https://cruds.readthedocs.io/en/latest/
+    :alt: Documentation Status
+
 .. image:: https://img.shields.io/pypi/l/cruds.svg
     :target: https://github.com/johnbrandborg/cruds/blob/main/LICENSE
     :alt: License Badge
@@ -29,7 +36,9 @@ and delete with zero boilerplate.
 Quickstart
 ----------
 
-Install from PyPI::
+Install from PyPI:
+
+.. code-block:: console
 
     $ pip install cruds
 
@@ -110,13 +119,10 @@ User Guide
 API Reference
 -------------
 
-For developers searching for information relating more closely to code
-
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
-   modules
+   api
 
 Indices and tables
 ==================