chore(docs): initial revision of docs (#74)

Initial version of documentation

Author: cofin

.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Documentation Building
+
+on:
+  release:
+    types: [published]
+  push:
+    branches:
+      - main
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+  build_and_deploy:
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install additional dependencies
+        run: sudo apt-get update && sudo ACCEPT_EULA=Y apt-get install -y msodbcsql18 libmariadb-dev && sudo apt-get autoremove -y  && sudo apt-get clean -y
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Build Release Documentation
+        run: uv run sphinx-build -M html docs dist/docs -E -a -j auto -W --keep-going
+        if: github.event_name == 'release'
+
+      - name: Build Documentation
+        run: uv run sphinx-build -M html docs dist/docs -E -a -j auto -W --keep-going
+        if: github.event_name != 'release'
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist/docs/
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.pre-commit-config.yaml

@@ -19,7 +19,7 @@ repos:
 
   # Ruff replaces black, flake8, autoflake and isort
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.11.6" # make sure this is always consistent with hatch configs
+    rev: "v0.11.7" # make sure this is always consistent with hatch configs
     hooks:
       - id: ruff
         args: [--config, ./pyproject.toml]

CONTRIBUTING.rst

@@ -4,12 +4,7 @@ Contribution guide
 Setting up the environment
 --------------------------
 
-1. ``make install-pipx``
-2. ``make install-hatch``
-3. ``make configure-hatch``
-4. ``make install``
-5. Install `pre-commit <https://pre-commit.com/>`_
-6. ``pre-commit install``
+1. ``make install``
 
 Code contributions
 ------------------
@@ -46,7 +41,7 @@ Guidelines for writing code
 Writing and running tests
 +++++++++++++++++++++++++
 
-.. todo:: Write this section
+Coming soon.
 
 Project documentation
 ---------------------

README.md

@@ -0,0 +1,26 @@
+# Sphinx documentation
+_build/
+.buildinfo
+.doctrees/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environment
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

docs/.gitignore

@@ -0,0 +1,149 @@
+/* Theme color definitions */
+:root {
+  --brand-font-size-xl: 6rem;
+  --brand-font-size-lg: 5rem;
+  --brand-font-size-md: 4rem;
+  --brand-font-size-sm: 2.5rem;
+  --brand-font-size-xs: 1.8rem;
+  --brand-font-size-xxs: 1.6rem;
+
+  --brand-letter-spacing-xl: 0.25em;
+  --brand-letter-spacing-lg: 0.2em;
+  --brand-letter-spacing-md: 0.1em;
+  --brand-letter-spacing-sm: 0.05em;
+  --brand-letter-spacing-xs: 0.03em;
+}
+
+html.light {
+  --sl-color-primary: #202235;
+  --sl-color-secondary: #edb641;
+  --sl-color-accent: #ffd480;
+  --sl-color-text-1: var(--sl-color-primary);
+  --sl-color-text-2: var(--sl-color-secondary);
+  --sy-c-foot-background: #f0f0f0;
+  --yue-c-text: #000;
+  --brand-text-glow: 0 0 10px rgba(32, 34, 53, 0.3),
+    0 0 20px rgba(32, 34, 53, 0.2), 0 0 30px rgba(237, 182, 65, 0.1);
+}
+
+html.dark {
+  --sl-color-text-1: var(--sl-color-secondary);
+  --sy-c-foot-background: black;
+  --yue-c-text: #fff;
+  --brand-text-glow: 0 0 10px rgba(237, 182, 65, 0.4),
+    0 0 20px rgba(237, 182, 65, 0.3), 0 0 30px rgba(237, 182, 65, 0.2);
+}
+
+.title-with-logo {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin: 5rem auto 4rem;
+  width: 100%;
+  padding: 0 2rem;
+  user-select: none;
+  -webkit-user-select: none;
+  -moz-user-select: none;
+  -ms-user-select: none;
+}
+
+html[class] .title-with-logo .brand-text {
+  font-family: var(--sl-font-sans);
+  font-weight: 300;
+  font-size: var(--brand-font-size-lg);
+  letter-spacing: var(--brand-letter-spacing-xl);
+  text-transform: uppercase;
+  text-align: center;
+  line-height: 1.4;
+  max-width: 100%;
+  word-break: break-word;
+  word-wrap: break-word;
+  overflow-wrap: break-word;
+  hyphens: auto;
+  -webkit-hyphens: auto;
+  -ms-hyphens: auto;
+  transition: color var(--sl-transition), text-shadow var(--sl-transition);
+}
+
+html.light .title-with-logo .brand-text {
+  color: var(--sl-color-text-1);
+  text-shadow: var(--brand-text-glow);
+}
+
+html.dark .title-with-logo .brand-text {
+  color: var(--sl-color-text-2);
+  text-shadow: var(--brand-text-glow);
+}
+
+/* Button container wrapping */
+.buttons.wrap {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.buttons.wrap .btn-no-wrap {
+  flex: 0 0 auto;
+}
+
+/* Large screens */
+@media (min-width: 1200px) {
+  html[class] .title-with-logo .brand-text {
+    font-size: var(--brand-font-size-xl);
+  }
+}
+
+/* Medium-small screens */
+@media (max-width: 991px) {
+  html[class] .title-with-logo .brand-text {
+    font-size: var(--brand-font-size-md);
+    letter-spacing: var(--brand-letter-spacing-lg);
+  }
+}
+
+/* Small screens */
+@media (max-width: 767px) {
+  html[class] .title-with-logo .brand-text {
+    font-size: var(--brand-font-size-sm);
+    letter-spacing: var(--brand-letter-spacing-md);
+  }
+
+  html[class] .title-with-logo {
+    margin: 2rem auto 1.5rem;
+  }
+}
+
+/* Extra small screens */
+@media (max-width: 480px) {
+  html[class] .title-with-logo .brand-text {
+    font-size: var(--brand-font-size-xs);
+    letter-spacing: var(--brand-letter-spacing-sm);
+    line-height: 1.2;
+  }
+
+  html[class] .title-with-logo {
+    margin: 1.5rem auto 1rem;
+    padding: 0 1rem;
+  }
+}
+
+/* Smallest screens */
+@media (max-width: 360px) {
+  html[class] .title-with-logo .brand-text {
+    font-size: var(--brand-font-size-xxs);
+    letter-spacing: var(--brand-letter-spacing-xs);
+  }
+}
+
+/* Preserve existing layout styles */
+#badges img {
+  margin-top: 0;
+  margin-bottom: 0;
+}
+
+#badges {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin-bottom: 3em;
+}

docs/__init__.py

@@ -0,0 +1,4 @@
+Changelog
+=========
+
+All notable changes to this project will be documented in this file.

docs/_static/.gitkeep

@@ -0,0 +1,70 @@
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from pytest_databases.__metadata__ import __project__, __version__
+
+sys.path.insert(0, str(Path("..").resolve()))
+
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+current_year = datetime.now().year  # noqa: DTZ005
+
+project = __project__
+copyright = f"{current_year}, Litestar Organization"  # noqa: A001
+author = "Litestar Organization"
+release = __version__
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.githubpages",
+    "sphinx_copybutton",
+    "sphinx_click",
+    "sphinx_design",
+    "auto_pytabs.sphinx_ext",
+    "myst_parser",
+    "sphinx_autodoc_typehints",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "shibuya"
+html_title = "Pytest Databases"
+pygments_style = "dracula"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_logo = "_static/logo.svg"
+html_favicon = "_static/logo.svg"  # Optional: use logo as favicon
+
+# Shibuya theme options: https://shibuya.lepture.com/install/
+html_theme_options = {
+    "accent_color": "amber",
+    "github_url": "https://github.com/litestar-org/pytest-databases",
+    "discord_url": "https://discord.gg/litestar",
+}
+
+# Autodoc settings
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "special-members": "__init__",
+    "undoc-members": True,
+    "exclude-members": "__weakref__",
+}
+
+# Intersphinx settings
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "pytest": ("https://docs.pytest.org/en/latest", None),
+}

docs/_static/custom.css

@@ -0,0 +1,3 @@
+:orphan:
+
+.. include:: ../CONTRIBUTING.rst

docs/_static/logo.svg

@@ -0,0 +1,34 @@
+Basic Usage
+===========
+
+Once a plugin is enabled (e.g., PostgreSQL), you can use its fixtures directly in your tests. There are typically two main types of fixtures:
+
+1.  **Service Fixture** (e.g., `postgres_service`): Provides details about the running database service (host, port, credentials, etc.). Useful for connecting with your own client.
+2.  **Connection Fixture** (e.g., `postgres_connection`): Provides a ready-to-use connection object (where applicable) to the database service.
+
+.. code-block:: python
+
+   # Assuming you have installed pytest-databases[postgres] and enabled the plugin
+   # Also assuming a client like psycopg is installed: pip install psycopg
+   import psycopg
+   from pytest_databases.docker.postgres import PostgresService
+
+   # Example using the Service Fixture
+   def test_connection_with_service_details(postgres_service: PostgresService) -> None:
+       conn_str = (
+           f"postgresql://{postgres_service.user}:{postgres_service.password}@"
+           f"{postgres_service.host}:{postgres_service.port}/{postgres_service.database}"
+       )
+       with psycopg.connect(conn_str, autocommit=True) as conn:
+           with conn.cursor() as cursor:
+               cursor.execute("SELECT 1")
+               assert cursor.fetchone() == (1,)
+
+   # Example using the Connection Fixture
+   def test_with_direct_connection(postgres_connection) -> None:
+      # postgres_connection is often a configured client or connection object
+      with postgres_connection.cursor() as cursor:
+          cursor.execute("CREATE TABLE IF NOT EXISTS users (id INT PRIMARY KEY, name TEXT);")
+          cursor.execute("INSERT INTO users (id, name) VALUES (1, 'Alice');")
+          cursor.execute("SELECT name FROM users WHERE id = 1;")
+          assert cursor.fetchone() == ('Alice',)