Merge pull request #16 from cjw296/docs

Initial documentation

Author: cjw296

.github/workflows/ci.yml

@@ -88,7 +88,7 @@ jobs:
           cache-suffix: ${{ matrix.uv-resolution }}
 
       - name: Install the project and dependencies
-        run: uv sync --all-extras --dev --resolution ${{ matrix.uv-resolution }}
+        run: uv sync --dev --resolution ${{ matrix.uv-resolution }}
 
       - name: Run tests
         run: |
@@ -134,7 +134,7 @@ jobs:
           cache-dependency-glob: "**/pyproject.toml"
 
       - name: Install the project
-        run: uv sync --all-extras --dev
+        run: uv sync --dev
 
       - name: Run tests
         run: uv run mypy pytest_sqlalchemy.py tests

.readthedocs.yaml

@@ -0,0 +1,20 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    create_environment:
+       - asdf plugin add uv
+       - asdf install uv latest
+       - asdf global uv latest
+    install:
+       - uv sync --group docs
+    build:
+       html:
+            - uv run sphinx-build -T -b html docs $READTHEDOCS_OUTPUT/html
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true

README.md

@@ -0,0 +1,90 @@
+pytest-sqlalchemy
+=================
+
+|Docs|_  |PyPI|_ |Git|_
+
+.. |Docs| image:: https://readthedocs.org/projects/pytest-sqlalchemy/badge/?version=latest
+.. _Docs: https://pytest-sqlalchemy.readthedocs.io/
+
+.. |PyPI| image:: https://badge.fury.io/py/pytest-sqlalchemy.svg
+.. _PyPI: https://pypi.org/project/pytest-sqlalchemy/
+
+.. |Git| image:: https://github.com/toirl/pytest-sqlalchemy/actions/workflows/ci.yml/badge.svg
+.. _Git: https://github.com/toirl/pytest-sqlalchemy
+
+SQLAlchemy related fixtures to handle connections and transactions with SQLAlchemy in tests.
+
+Fixtures
+--------
+This plugin provides the following fixtures which gives access to the SQLAlchemy objects of the same 
+name.
+
+* **engine** The engine used to connect to the database. Scope is "module".
+* **connection** An open connection to the database. Scope is "module".
+
+See `Working with Engines and Connections`__ on how to use these fixtures.
+
+__ http://docs.sqlalchemy.org/en/latest/core/connections.html#module-sqlalchemy.engine
+
+* **transaction** A started transaction on the connection. Transaction will be rolled back.
+  No Scope.
+
+See `Using Transactions`__ on how to use this fixtures
+
+__ http://docs.sqlalchemy.org/en/latest/core/connections.html#using-transactions
+
+* **dbsession** A sqlalchemy session *not* bound to any model. No scope.
+
+See `Session Basics`__ to learn about how to use sessions.
+
+__ http://docs.sqlalchemy.org/en/latest/orm/session_basics.html#session-basics
+
+Usage
+-----
+The fixtures can be used in your tests like any other `Pytest Fixtures`__.
+
+__ https://docs.pytest.org/en/3.6.1/fixture.html
+
+**Example**:
+
+.. code-block:: python
+
+    import pytest
+    from pytest_sqlalchemy import connection
+    
+    def test_connection(connection):
+        # Do fancy stuff with the connection.
+        # Note you will not need to close the connection. This is done
+        # automatically when the scope (module) of the fixtures ends.
+        assert connection
+
+Invoke
+------
+You need to provide the connection URL for the engine when invoking the pytest command:
+
+.. code-block:: bash
+
+    pytest --sqlalchemy-connect-url="postgresql://scott:tiger@localhost:5432/mydatabase"
+    
+Or override the ``sqlalchemy_connect_url`` fixture on your ``conftest.py`` file:
+
+.. code-block:: python
+
+    @pytest.fixture(scope="session")
+    def sqlalchemy_connect_url():
+        return 'postgresql://scott:tiger@localhost:5432/mydatabase'
+
+Development
+----------
+
+To get going, in a checkout:
+
+.. code-block:: bash
+
+    uv sync
+
+You can then run the tests with:
+
+.. code-block:: bash
+
+    uv run pytest

README.rst

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= uv run sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/Makefile

@@ -0,0 +1,25 @@
+from importlib import metadata
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+]
+
+intersphinx_mapping = {
+    'python': ('http://docs.python.org', None),
+}
+
+project = 'pytest-sqlalchemy'
+author = 'Torsten Irländer'
+release = metadata.version(project)
+copyright = f'2015 onwards {author}'
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+autodoc_member_order = 'bysource'
+
+html_theme = 'furo'
+
+nitpicky = True
+nitpick_ignore: list[tuple[str, str]] = []

docs/conf.py

@@ -0,0 +1 @@
+.. include:: ../README.rst

docs/index.rst

@@ -32,6 +32,11 @@ dev = [
     "mypy>=1.15.0",
     "pytest-xdist>=3.6.1",
 ]
+docs = [
+    "furo>=2024.8.6",
+    # work around https://github.com/astral-sh/uv/issues/12737
+    "sphinx>=7.4.7",
+]
 
 [build-system]
 requires = ["setuptools>=61.0"]