# 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="https://raw.githubusercontent.com/altair-viz/sphinxext-altair/main/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).
You can install the extension with:
```bash
pip install sphinxext-altair
```
# 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).
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinxext-altair",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "altair,sphinxext",
"author": "sphinxext-altair Contributors",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ea/2c/41b5f3079481f4e49a9451be1a429fda3dec1e51786875e104ef3c95d836/sphinxext_altair-0.2.0.tar.gz",
"platform": null,
"description": "# sphinxext-altair\n**sphinxext-altair** provides the directive `altair-plot` to insert live-rendered Altair plots within your Sphinx documentation:\n\n```python\n .. altair-plot::\n import altair as alt\n from vega_datasets import data\n\n\n cars = data.cars()\n\n alt.Chart(cars).mark_point().encode(\n x='Horsepower',\n y='Miles_per_Gallon',\n color='Origin',\n shape='Origin'\n )\n```\n\n<img src=\"https://raw.githubusercontent.com/altair-viz/sphinxext-altair/main/images/example_screenshot.png\" width=\"70%\">\n\nYou can enable the extension by adding it to your `conf.py`:\n\n```python\nextensions = [\n ...\n \"sphinxext_altair.altairplot\",\n ...\n]\n```\n\nYou 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).\n\nYou can install the extension with:\n\n```bash\npip install sphinxext-altair\n```\n\n\n# Contributing\nIt's recommended to use a virtual environment for development:\n\n```bash\npython -m venv .venv\n# Install the project in editable mode including development dependencies\npip install -e '.[dev]'\n```\n\n`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:\n\n```bash\nhatch run test\n```\n\nAs 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:\n\n```bash\nhatch run build-test-docs\nhatch run serve-test-docs\n```\n\nThe test documentation can now be viewed at [http://localhost:8000](http://localhost:8000).\n",
"bugtrack_url": null,
"license": null,
"summary": "sphinxext-altair: Sphinx extension for embedding Altair charts",
"version": "0.2.0",
"project_urls": {
"Source": "https://github.com/altair-viz/sphinxext-altair"
},
"split_keywords": [
"altair",
"sphinxext"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "81c915bd3bf427be9dc4f4d06bb7fcc4b0b7fb82aef07e25c5026bb52c819380",
"md5": "b7700e446fd40542adda3c51afd288d0",
"sha256": "4a307add6a530586794ba80204d724305009b5f499782cf1f828af0fc1d056b9"
},
"downloads": -1,
"filename": "sphinxext_altair-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b7700e446fd40542adda3c51afd288d0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7786,
"upload_time": "2023-05-15T17:32:28",
"upload_time_iso_8601": "2023-05-15T17:32:28.791182Z",
"url": "https://files.pythonhosted.org/packages/81/c9/15bd3bf427be9dc4f4d06bb7fcc4b0b7fb82aef07e25c5026bb52c819380/sphinxext_altair-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ea2c41b5f3079481f4e49a9451be1a429fda3dec1e51786875e104ef3c95d836",
"md5": "4ec37c58815f710ffd30fddd243edda9",
"sha256": "eac920f97fdc9d44b669f442c24f6d96ea4f236179b96c25df41a8cd4385e5f6"
},
"downloads": -1,
"filename": "sphinxext_altair-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "4ec37c58815f710ffd30fddd243edda9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8648,
"upload_time": "2023-05-15T17:32:26",
"upload_time_iso_8601": "2023-05-15T17:32:26.109310Z",
"url": "https://files.pythonhosted.org/packages/ea/2c/41b5f3079481f4e49a9451be1a429fda3dec1e51786875e104ef3c95d836/sphinxext_altair-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-15 17:32:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "altair-viz",
"github_project": "sphinxext-altair",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinxext-altair"
}
JSON
