diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..a30a1ea --- /dev/null +++ b/.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 diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 8518336..00614ae 100644 --- a/.github/workflows/tests.yml +++ b/.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 diff --git a/.readthedocs.yml b/.readthedocs.yml index 0d0b035..6bc68f3 100644 --- a/.readthedocs.yml +++ b/.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 diff --git a/docs/conf.py b/docs/conf.py index 930caab..4da73c7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -7,4 +7,5 @@ extensions = ["sphinx_sqlalchemy"] +html_title = "sphinx-sqlalchemy documentation" html_theme = "furo" diff --git a/docs/index.rst b/docs/index.rst index 4e016fd..838bfcf 100644 --- a/docs/index.rst +++ b/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 ------- diff --git a/pyproject.toml b/pyproject.toml index c4ccb42..998a621 100644 --- a/pyproject.toml +++ b/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 diff --git a/tests/__snapshots__/test_basic.ambr b/tests/__snapshots__/test_basic.ambr new file mode 100644 index 0000000..4f361f3 --- /dev/null +++ b/tests/__snapshots__/test_basic.ambr @@ -0,0 +1,77 @@ +# serializer version: 1 +# name: test_basic + ''' + + + + + module1.TestUser + ( + + dbusers + ) + + + A + + user + . + + Columns: + + + + + + + + + + + pk* + + + INTEGER + + + + + + first_name + + + VARCHAR? + + + The name of the user. + + + + last_name + + + VARCHAR(255)? + + + The surname of the user. + + + + dob + + + DATE + + + The date of birth. + + Constraints: + + + + PRIMARY KEY (pk) + + + UNIQUE (first_name, last_name) + ''' +# --- diff --git a/tests/modules/module1.py b/tests/modules/module1.py new file mode 100644 index 0000000..b0b0df6 --- /dev/null +++ b/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.") diff --git a/tests/test_basic.py b/tests/test_basic.py index 1d15f76..286e50f 100644 --- a/tests/test_basic.py +++ b/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 diff --git a/tox.ini b/tox.ini index 8ec9c3b..3ee1d48 100644 --- a/tox.ini +++ b/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}