✨ NEW: Initial implementation

Author: chrisjsewell

.github/workflows/tests.yml

@@ -0,0 +1,68 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*'
+  pull_request:
+
+jobs:
+
+  pre-commit:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v1
+      with:
+        python-version: "3.8"
+    - uses: pre-commit/[email protected]
+
+  tests:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        os: ['ubuntu-latest']
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -e .[dev]
+    - name: Test with pytest
+      run: pytest -vv --cov=sphinx_sqlalchemy
+      env:
+        SQLALCHEMY_WARN_20: 1
+
+  publish:
+
+    name: Publish to PyPi
+    needs: [pre-commit, tests]
+    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout source
+      uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+    - name: Build package
+      run: |
+        pip install wheel
+        python setup.py sdist bdist_wheel
+    - name: Publish
+      uses: pypa/[email protected]
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_KEY }}

.gitignore

@@ -127,3 +127,5 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+.vscode/

.pre-commit-config.yaml

@@ -0,0 +1,65 @@
+ci:
+    autoupdate_schedule: monthly
+    autofix_prs: true
+
+exclude: &exclude_files >
+  (?x)^(
+    performance-benchmarks/.*/.*\.py
+  )$
+
+repos:
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.0.1
+    hooks:
+    - id: check-json
+    - id: check-yaml
+    - id: end-of-file-fixer
+    - id: trailing-whitespace
+
+  - repo: https://github.com/asottile/setup-cfg-fmt
+    rev: v1.17.0
+    hooks:
+    - id: setup-cfg-fmt
+
+  - repo: https://github.com/mgedmin/check-manifest
+    rev: "0.46"
+    hooks:
+    - id: check-manifest
+      args: [--no-build-isolation]
+      additional_dependencies: [setuptools>=46.4.0]
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.9.3
+    hooks:
+    - id: isort
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v2.25.0
+    hooks:
+    - id: pyupgrade
+      args: [--py37-plus]
+
+  - repo: https://github.com/psf/black
+    rev: 21.7b0
+    hooks:
+    - id: black
+
+  - repo: https://github.com/PyCQA/flake8
+    rev: '3.9.2'
+    hooks:
+    - id: flake8
+      additional_dependencies:
+      - flake8-bugbear==20.1.4
+      - flake8-builtins==1.5.3
+      - flake8-comprehensions==3.2.3
+      - flake8-rst-docstrings==0.0.14
+      - flake8-markdown==0.2.0
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v0.910-1
+    hooks:
+    - id: mypy
+      additional_dependencies:
+      - "sqlalchemy[mypy]==1.4.22"
+      files: ^(sphinx_sqlalchemy/.*py)$

.readthedocs.yml

@@ -0,0 +1,13 @@
+version: 2
+
+python:
+  version: "3.8"
+  install:
+      - method: pip
+        path: .
+        extra_requirements:
+          - docs
+
+sphinx:
+  builder: html
+  fail_on_warning: true

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## v0.1.0 (November 2021)
+
+Initial release.

MANIFEST.in

@@ -0,0 +1,12 @@
+exclude docs
+recursive-exclude docs *
+exclude tests
+recursive-exclude tests *
+
+exclude .pre-commit-config.yaml
+exclude tox.ini
+exclude .readthedocs.yml
+
+include LICENSE
+include CHANGELOG.md
+include README.md

README.md

@@ -1,2 +1,3 @@
 # sphinx-sqlalchemy
+
 Sphinx extension for documenting SQLAlchemy ORMs

docs/conf.py

@@ -0,0 +1,10 @@
+"""Sphinx configuration file."""
+import os
+import sys
+
+# add example module to the python path
+sys.path.insert(0, os.path.dirname(__file__))
+
+extensions = ["sphinx_sqlalchemy"]
+
+html_theme = "furo"

docs/example/__init__.py

@@ -0,0 +1 @@
+"""An example module."""

docs/example/models.py

@@ -0,0 +1,27 @@
+"""Example SQLAlchemy ORM models."""
+from sqlalchemy import CheckConstraint, Column, ForeignKey, UniqueConstraint, orm, types
+
+Base = orm.declarative_base()
+
+
+class User(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.")
+
+
+class Address(Base):
+    """An address."""
+
+    __tablename__ = "addresses"
+    __table_args__ = (CheckConstraint("number>0", name="check1"),)
+    pk = Column(types.Integer, primary_key=True)
+    number = Column(types.Integer, nullable=False, doc="The number of the address.")
+    postcode = Column(types.String, nullable=False)
+    user_id = Column(types.Integer, ForeignKey("dbusers.pk"))
+    user = orm.relationship("User")