First version

.gitattributes

@@ -0,0 +1 @@
+* text=auto

.github/workflows/build.yml

@@ -0,0 +1,24 @@
+name: build
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+    name: py ${{ matrix.python-version }}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Test with pytest
+        run: |
+          pytest tests

.github/workflows/lint.yml

@@ -0,0 +1,29 @@
+name: lint
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: black-ruff-mypy
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.10"
+    # Installing all dependencies and not just the linters as mypy needs them for type checking
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[dev]
+    - name: Check formatting with black
+      run: |
+        black --diff --color .
+        black --check .
+    - name: Lint with ruff
+      run: |
+        ruff check .
+    - name: Lint with mypy
+      run: |
+        mypy sphinxext_altair tests

.gitignore

@@ -1,3 +1,7 @@
+.vscode
+.DS_Store
+tests/roots/**/_build
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

README.md

@@ -1 +1,57 @@
-# sphinxext-altair
+# sphinxext-altair
+**sphinxext-altair** provides the directive `altair-plot` to insert live-rendered Altair plots within your Sphinx documentation:
+
+```python
+    .. altair-plot::
+        import altair as alt
+        from vega_datasets import data
+
+
+        cars = data.cars()
+
+        alt.Chart(cars).mark_point().encode(
+            x='Horsepower',
+            y='Miles_per_Gallon',
+            color='Origin',
+            shape='Origin'
+        )
+```
+
+<img src="images/example_screenshot.png"  width="70%">
+
+You can enable the extension by adding it to your `conf.py`:
+
+```python
+extensions = [
+    ...
+    "sphinxext_altair.altairplot",
+    ...
+]
+```
+
+You can find all available options in the docstring of `sphinxext_altair/altairplot.py`. For more examples on how to use this extension, see the test Sphinx documentation in `tests/roots/test-altairplot` or the official [Altair documentation](https://github.com/altair-viz/altair/tree/master/doc)
+
+
+# Contributing
+It's recommended to use a virtual environment for development:
+
+```bash
+python -m venv .venv
+# Install the project in editable mode including development dependencies
+pip install -e '.[dev]'
+```
+
+`sphinxext-altair` uses [black](https://github.com/psf/black) for code formatting, [mypy](https://github.com/python/mypy) for static type checking, [ruff](https://github.com/charliermarsh/ruff) for various linting rules, and [pytest](https://github.com/pytest-dev/pytest) for testing. All these tools can be executed by running:
+
+```bash
+hatch run test
+```
+
+As part of those tests, a Sphinx documentation is built at `tests/roots/test-altairplot`. You can manually build this documentation and view it which is very useful during development of a new feature. For example, if you want to add a new option to the `altair-plot` directive, you can add another example in the file `tests/roots/test-altairplot/index.rst` and then build and view the documentation by running:
+
+```bash
+hatch run build-test-docs
+hatch run serve-test-docs
+```
+
+The test documentation can now be viewed at [http://localhost:8000](http://localhost:8000).

pyproject.toml

@@ -0,0 +1,132 @@
+# this file contains:
+# 1 build system configuration
+# 2 project configuration
+# 3 tool configuration, for:
+# - hatch
+# - black
+# - ruff
+# - pytest
+# - mypy
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sphinxext-altair"
+authors = [ {name = "sphinxext-altair Contributors"} ]
+dependencies = [
+    "sphinx",
+    "docutils",
+    "altair>=4.0.0",
+    "typing_extensions>=4.0.1; python_version<\"3.8\"",
+]
+description = "sphinxext-altair: Sphinx extension for embedding Altair charts"
+readme = "README.md"
+keywords = [
+    "altair",
+    "sphinxext"
+]
+requires-python = ">=3.7"
+dynamic = ["version"]
+license-files = { paths = ["LICENSE"] }
+classifiers= [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Plugins",
+    "License :: OSI Approved :: BSD License",
+    "Natural Language :: English",
+    "Framework :: Sphinx :: Extension",
+    "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",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Source = "https://github.com/altair-viz/sphinxext-altair"
+
+[project.optional-dependencies]
+dev = [
+    "hatch",
+    "ruff",
+    "black<24",
+    "pytest",
+    "mypy",
+    "types-docutils",
+    # ipython is only installed for the convenience of the developer
+    "ipython"
+]
+
+[tool.hatch.version]
+path = "sphinxext_altair/__init__.py"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build]
+include = [
+    "/sphinxext_altair",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml"
+]
+
+[tool.hatch.envs.default]
+features = ["dev"]
+
+[tool.hatch.envs.default.scripts]
+test = [
+    "black --diff --color --check .",
+    "ruff check .",
+    "mypy sphinxext_altair tests",
+    "python -m pytest tests"
+]
+
+build-test-docs = ["sphinx-build -b html tests/roots/test-altairplot tests/roots/test-altairplot/_build/html"]
+serve-test-docs = ["(cd tests/roots/test-altairplot/_build/html && python -m http.server)"]
+
+
+[tool.black]
+line-length = 88
+target-version = ["py37", "py38", "py39", "py310", "py311"]
+exclude = '''
+/(
+    \.eggs
+  | \.git
+  | \.mypy_cache
+  | build
+  | dist
+  | .venv
+)/
+'''
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+select = [
+    # flake8-bugbear
+    "B",
+    # flake8-comprehensions
+    "C4",
+    # pycodestyle-error
+    "E",
+    # pycodestyle-warning
+    "W",
+    # pyflakes
+    "F",
+    # flake8-tidy-imports
+    "TID"
+]
+exclude = [
+    ".git",
+    "build",
+    "__pycache__",
+]
+
+[[tool.mypy.overrides]]
+module = [
+    "altair.*"
+]
+ignore_missing_imports = true

sphinxext_altair/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"