⬆️ Update sphinx version to 5,6,7

.github/dependabot.yml

@@ -0,0 +1,19 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    commit-message:
+      prefix: ⬆️
+    schedule:
+      interval: monthly
+  - package-ecosystem: pip
+    directory: /
+    commit-message:
+      prefix: ⬆️
+    schedule:
+      interval: monthly

.github/workflows/tests.yml

@@ -21,12 +21,21 @@ jobs:
     - uses: pre-commit/action@v2.0.0
 
   tests:
+    name: tests on py${{ matrix.python-version }} with sphinx~=${{ matrix.sphinx-version }}
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        sphinx-version: ["7.0"]
         os: ['ubuntu-latest']
+        include:
+          - python-version: "3.8"
+            sphinx-version: "5.0"
+            os: 'ubuntu-latest'
+          - python-version: "3.8"
+            sphinx-version: "6.0"
+            os: 'ubuntu-latest'
 
     steps:
     - uses: actions/checkout@v2
@@ -38,12 +47,31 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e .[dev]
+        pip install sphinx~=${{ matrix.sphinx-version }} -e .[dev]
     - name: Test with pytest
       run: pytest -vv --cov=sphinx_sqlalchemy
       env:
         SQLALCHEMY_WARN_20: 1
 
+  all-good:
+
+    # This job does nothing and is only used for the branch protection
+    # see https://github.com/marketplace/actions/alls-green#why
+
+    if: always()
+
+    needs:
+    - pre-commit
+    - tests
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Decide whether the needed jobs succeeded or failed
+      uses: re-actors/alls-green@release/v1
+      with:
+        jobs: ${{ toJSON(needs) }}
+
   publish:
 
     name: Publish to PyPi

.readthedocs.yml

@@ -1,12 +1,16 @@
 version: 2
 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.8"
+
 python:
-  version: "3.8"
   install:
-      - method: pip
-        path: .
-        extra_requirements:
-          - docs
+  - method: pip
+    path: .
+    extra_requirements:
+      - docs
 
 sphinx:
   builder: html

docs/conf.py

@@ -7,4 +7,5 @@
 
 extensions = ["sphinx_sqlalchemy"]
 
+html_title = "sphinx-sqlalchemy documentation"
 html_theme = "furo"

docs/index.rst

@@ -3,6 +3,23 @@ sphinx-sqlalchemy
 
 Sphinx extension for documenting SQLAlchemy ORMs.
 
+Usage
+-----
+
+Install ``sphinx_sqlalchemy``:
+
+.. code-block:: bash
+
+    pip install sphinx_sqlalchemy
+
+Add ``sphinx_sqlalchemy`` to your ``conf.py``:
+
+.. code-block:: python
+
+    extensions = [
+        'sphinx_sqlalchemy',
+    ]
+
 Example
 -------
 

pyproject.toml

@@ -17,16 +17,17 @@ classifiers = [
     "Operating System :: Microsoft :: Windows",
     "Operating System :: POSIX :: Linux",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.7",
     "Programming Language :: Python :: 3.8",
     "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: Implementation :: CPython",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 keywords = ["sphinx", "extension"]
-requires-python = "~=3.7"
+requires-python = "~=3.8"
 dependencies = [
-    "sphinx>=3,<5",
+    "sphinx>=5,<8",
     "sqlalchemy~=1.4.22",
 ]
 
@@ -38,8 +39,10 @@ Documentation = "https://sphinx-sqlalchemy.readthedocs.io"
 dev = [
     "pytest",
     "pytest-cov",
+    "sphinx-pytest",
+    "syrupy~=4.0",
 ]
-docs = ["furo==2021.11.23"]
+docs = ["furo"]
 
 [tool.ruff]
 line-length = 100

tests/__snapshots__/test_basic.ambr

@@ -0,0 +1,77 @@
+# serializer version: 1
+# name: test_basic
+  '''
+  <document source="<src>/index.rst">
+      <definition_list classes="simple sqla">
+          <definition_list_item>
+              <term>
+                  module1.TestUser
+                   (
+                  <emphasis>
+                      dbusers
+                  )
+              <definition>
+                  <paragraph>
+                      A
+                      <literal>
+                          user
+                      .
+                  <rubric>
+                      Columns:
+                  <table align="left" classes="colwidths-auto">
+                      <tgroup cols="3">
+                          <colspec>
+                          <colspec>
+                          <colspec>
+                          <tbody>
+                              <row>
+                                  <entry>
+                                      <paragraph>
+                                          <emphasis>
+                                              pk*
+                                  <entry>
+                                      <paragraph>
+                                          INTEGER
+                                  <entry>
+                                      <paragraph>
+                              <row>
+                                  <entry>
+                                      <paragraph>
+                                          first_name
+                                  <entry>
+                                      <paragraph>
+                                          VARCHAR?
+                                  <entry>
+                                      <paragraph>
+                                          The name of the user.
+                              <row>
+                                  <entry>
+                                      <paragraph>
+                                          last_name
+                                  <entry>
+                                      <paragraph>
+                                          VARCHAR(255)?
+                                  <entry>
+                                      <paragraph>
+                                          The surname of the user.
+                              <row>
+                                  <entry>
+                                      <paragraph>
+                                          dob
+                                  <entry>
+                                      <paragraph>
+                                          DATE
+                                  <entry>
+                                      <paragraph>
+                                          The date of birth.
+                  <rubric>
+                      Constraints:
+                  <bullet_list>
+                      <list_item>
+                          <paragraph>
+                              PRIMARY KEY (pk)
+                      <list_item>
+                          <paragraph>
+                              UNIQUE (first_name, last_name)
+  '''
+# ---

tests/modules/module1.py

@@ -0,0 +1,14 @@
+from sqlalchemy import Column, UniqueConstraint, orm, types
+
+Base = orm.declarative_base()
+
+
+class TestUser(Base):
+    """A ``user``."""
+
+    __tablename__ = "dbusers"
+    __table_args__ = (UniqueConstraint("first_name", "last_name"),)
+    pk = Column(types.Integer, primary_key=True)
+    first_name = Column(types.String, doc="The name of the user.")
+    last_name = Column(types.String(255), doc="The surname of the user.")
+    dob = Column(types.Date, nullable=False, doc="The date of birth.")

tests/test_basic.py

@@ -1,6 +1,14 @@
 """Basic tests"""
+import os.path
+import sys
 
+from sphinx_pytest.plugin import CreateDoctree
 
-def test_basic():
+
+def test_basic(sphinx_doctree_no_tr: CreateDoctree, snapshot):
     """Basic test"""
-    assert True
+    sys.path.insert(0, os.path.join(os.path.dirname(__file__), "modules"))
+    sphinx_doctree_no_tr.set_conf({"extensions": ["sphinx_sqlalchemy"]})
+    result = sphinx_doctree_no_tr(".. sqla-model:: module1.TestUser")
+    assert not result.warnings
+    assert "\n".join([li.rstrip() for li in result.pformat().splitlines()]) == snapshot

tox.ini

@@ -9,12 +9,10 @@ envlist = py38
 [testenv]
 usedevelop = true
 
-[testenv:py{37,38,39,310}]
+[testenv:py{38,39,310,311}]
 description = Run unit tests with this Python version
 extras =
     dev
-deps =
-    black
 setenv =
     SQLALCHEMY_WARN_20 = 1
 commands = pytest {posargs}