From 65f11d7298897153336dd419e03452cf5f362bc7 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Tue, 18 Aug 2026 21:56:45 +0100 Subject: [PATCH 1/5] document markdown docs and llms.txt --- doc/developer_guide.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/doc/developer_guide.md b/doc/developer_guide.md index 7d908cb58..77541f36c 100644 --- a/doc/developer_guide.md +++ b/doc/developer_guide.md @@ -223,6 +223,28 @@ As hvPlot uses notebooks for much of the documentation, this takes a little whil A development version of hvPlot can be found [here](https://holoviz-dev.github.io/hvplot/). You can ask a maintainer if they want to make a dev release for your PR, but there is no guarantee they will say yes. +### Markdown docs and `llms.txt` + +As part of `docs-build`, hvPlot also generates clean Markdown versions of its documentation together with an `llms.txt` index file that points AI assistants at the most relevant pages. + +The build produces: + +- `builtdocs/markdown/` - a Markdown rendering of the documentation +- `builtdocs/llms.txt` - an index of the most useful documentation pages for LLM-assisted development + +#### Using hvPlot with an AI assistant + +The generated `llms.txt` and Markdown docs are designed to be consumed by AI assistants so they can produce correct, idiomatic hvPlot code instead of guessing from stale training data. There are two ways to make use of them: + +- **Point your own assistant at the docs.** Once the site is deployed, `llms.txt` is available at `https://hvplot.holoviz.org/en/docs/latest/llms.txt` and the Markdown pages it links to under `https://hvplot.holoviz.org/en/docs/latest/markdown/`. You can fetch these and give them to your assistant as context. + +- **Use the HoloViz skills.** The [holoviz-skills](https://holoviz-dev.github.io/holoviz-skills/) repository provides a curated collection of [Agent Skills](https://www.anthropic.com/news/skills) for the HoloViz ecosystem, including hvPlot. Install them with: + +```bash +pip install holoviz-skills +holoviz-skills install +``` + ### Link to hvPlot objects ```md From 86c979f0e3e404a03b68081b03ff1604c56dbf45 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Wed, 19 Aug 2026 11:39:05 +0100 Subject: [PATCH 2/5] create how to dir --- doc/how_to/index.md | 12 ++++++++ doc/how_to/use_llms.md | 66 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+) create mode 100644 doc/how_to/index.md create mode 100644 doc/how_to/use_llms.md diff --git a/doc/how_to/index.md b/doc/how_to/index.md new file mode 100644 index 000000000..c83dcbda5 --- /dev/null +++ b/doc/how_to/index.md @@ -0,0 +1,12 @@ +# How-To Guides + +How-to guides are practical, problem-oriented instructions that help you accomplish specific tasks with hvPlot. These guides assume you're already familiar with the basics and want to solve particular problems or achieve specific goals. + +```{toctree} +:titlesonly: +:hidden: +:maxdepth: 2 + +use_llms + +``` diff --git a/doc/how_to/use_llms.md b/doc/how_to/use_llms.md new file mode 100644 index 000000000..da3e0f6e8 --- /dev/null +++ b/doc/how_to/use_llms.md @@ -0,0 +1,66 @@ +# Using hvPlot with an AI assistant + +AI assistants (like Claude, GitHub Copilot, or OpenAI Codex) can write hvPlot code much more reliably when they have access to up-to-date, structured documentation instead of guessing from stale training data. This guide shows you how to give your assistant that context, either by pointing it at hvPlot's generated `llms.txt` and Markdown docs, or by installing the HoloViz Agent Skills. + +## What you'll accomplish + +By the end of this guide you'll be able to: + +- Give your AI assistant a curated index of the most useful hvPlot documentation pages +- Install the HoloViz skills so your assistant follows hvPlot best practices automatically + +## Prerequisites + +- An AI assistant that can read web content or local files (for example Claude, GitHub Copilot, or OpenAI Codex) +- [Python](https://www.python.org/) 3.12+ and `pip` if you want to install the skills + +## Point your assistant at the docs + +hvPlot publishes a machine-friendly index of its documentation that your assistant can fetch directly. + +1. Tell your assistant to fetch the index: + + `https://hvplot.holoviz.org/en/docs/latest/llms.txt` + +2. The index lists the most relevant pages and links to their Markdown versions under: + + `https://hvplot.holoviz.org/en/docs/latest/markdown/` + +3. Ask your assistant to read the pages relevant to your task before writing code. For example, to create a plot you might have it read `tutorials/getting_started.md` and the API reference page for the method you need. + +The Markdown pages are intentionally free of the navigation chrome, CSS, and JavaScript of the full HTML site, so they consume far fewer tokens and are easier for an assistant to parse. + +## Install the HoloViz skills + +The [holoviz-skills](https://holoviz-dev.github.io/holoviz-skills/) repository provides a curated collection of [Agent Skills](https://www.anthropic.com/news/skills) for the HoloViz ecosystem, including hvPlot. Agent Skills are folders of instructions and references that teach an assistant how to work with a library correctly. + +1. Install the package: + + ```bash + pip install holoviz-skills + ``` + +2. Install the skills for your tool: + + ```bash + holoviz-skills install + ``` + + This auto-detects the AI tools on your machine. You can also target a specific tool, for example: + + ```bash + holoviz-skills install --claude-code + holoviz-skills install --copilot + ``` + +3. Restart your assistant so it picks up the newly installed skills. + +## Which approach should I use? + +- **Point your assistant at the docs** is a good fit for a one-off task or when you can't install packages, and it always reflects the latest published docs. +- **Install the HoloViz skills** gives your assistant packaged, opinionated guidance that works offline, but you need to update it as hvPlot evolves. + +## What to do next + +- Browse the full list of skills and usage instructions at [holoviz-dev.github.io/holoviz-skills](https://holoviz-dev.github.io/holoviz-skills/). +- If you're contributing to hvPlot, see the [Developer Guide](../developer_guide.md) for how the Markdown docs and `llms.txt` are built. From ffa92ac61345a823c7a44d6c0f41285af3a9c1d2 Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Wed, 19 Aug 2026 11:39:29 +0100 Subject: [PATCH 3/5] move content --- doc/developer_guide.md | 13 +------------ doc/index.md | 1 + 2 files changed, 2 insertions(+), 12 deletions(-) diff --git a/doc/developer_guide.md b/doc/developer_guide.md index 77541f36c..945443418 100644 --- a/doc/developer_guide.md +++ b/doc/developer_guide.md @@ -232,18 +232,7 @@ The build produces: - `builtdocs/markdown/` - a Markdown rendering of the documentation - `builtdocs/llms.txt` - an index of the most useful documentation pages for LLM-assisted development -#### Using hvPlot with an AI assistant - -The generated `llms.txt` and Markdown docs are designed to be consumed by AI assistants so they can produce correct, idiomatic hvPlot code instead of guessing from stale training data. There are two ways to make use of them: - -- **Point your own assistant at the docs.** Once the site is deployed, `llms.txt` is available at `https://hvplot.holoviz.org/en/docs/latest/llms.txt` and the Markdown pages it links to under `https://hvplot.holoviz.org/en/docs/latest/markdown/`. You can fetch these and give them to your assistant as context. - -- **Use the HoloViz skills.** The [holoviz-skills](https://holoviz-dev.github.io/holoviz-skills/) repository provides a curated collection of [Agent Skills](https://www.anthropic.com/news/skills) for the HoloViz ecosystem, including hvPlot. Install them with: - -```bash -pip install holoviz-skills -holoviz-skills install -``` +See [Using hvPlot with an AI assistant](how_to/use_llms.md) for how to consume these docs with an AI assistant. ### Link to hvPlot objects diff --git a/doc/index.md b/doc/index.md index db66bb12a..99a86f4d4 100644 --- a/doc/index.md +++ b/doc/index.md @@ -415,6 +415,7 @@ align: center Tutorials User Guide +How-To Guides Gallery Reference Developer Guide From 96edd0dc772a86eee56aab6e24e7e82639cd68ce Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Wed, 19 Aug 2026 19:35:40 +0100 Subject: [PATCH 4/5] clean up --- doc/how_to/use_llms.md | 45 +++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/doc/how_to/use_llms.md b/doc/how_to/use_llms.md index da3e0f6e8..ba9ec15ba 100644 --- a/doc/how_to/use_llms.md +++ b/doc/how_to/use_llms.md @@ -12,23 +12,7 @@ By the end of this guide you'll be able to: ## Prerequisites - An AI assistant that can read web content or local files (for example Claude, GitHub Copilot, or OpenAI Codex) -- [Python](https://www.python.org/) 3.12+ and `pip` if you want to install the skills - -## Point your assistant at the docs - -hvPlot publishes a machine-friendly index of its documentation that your assistant can fetch directly. - -1. Tell your assistant to fetch the index: - - `https://hvplot.holoviz.org/en/docs/latest/llms.txt` - -2. The index lists the most relevant pages and links to their Markdown versions under: - - `https://hvplot.holoviz.org/en/docs/latest/markdown/` - -3. Ask your assistant to read the pages relevant to your task before writing code. For example, to create a plot you might have it read `tutorials/getting_started.md` and the API reference page for the method you need. - -The Markdown pages are intentionally free of the navigation chrome, CSS, and JavaScript of the full HTML site, so they consume far fewer tokens and are easier for an assistant to parse. +- A python package installer like `pip` or `uvx` if you want to install the skills ## Install the HoloViz skills @@ -40,6 +24,12 @@ The [holoviz-skills](https://holoviz-dev.github.io/holoviz-skills/) repository p pip install holoviz-skills ``` + OR + + ```bash + uvx install holoviz-skills + ``` + 2. Install the skills for your tool: ```bash @@ -55,12 +45,23 @@ The [holoviz-skills](https://holoviz-dev.github.io/holoviz-skills/) repository p 3. Restart your assistant so it picks up the newly installed skills. +## Point your assistant at the docs + +hvPlot publishes a machine-friendly index of its documentation that your assistant can fetch directly. + +1. Tell your assistant to fetch the index: + + `https://hvplot.holoviz.org/en/docs/latest/llms.txt` + +2. The index lists the most relevant pages and links to their Markdown versions under: + + `https://hvplot.holoviz.org/en/docs/latest/markdown/` + +3. Ask your assistant to read the pages relevant to your task before writing code. For example, to create a plot you might have it read `tutorials/getting_started.md` and the API reference page for the method you need. + +The Markdown pages are intentionally free of the navigation chrome, CSS, and JavaScript of the full HTML site, so they consume far fewer tokens and are easier for an assistant to parse. + ## Which approach should I use? - **Point your assistant at the docs** is a good fit for a one-off task or when you can't install packages, and it always reflects the latest published docs. - **Install the HoloViz skills** gives your assistant packaged, opinionated guidance that works offline, but you need to update it as hvPlot evolves. - -## What to do next - -- Browse the full list of skills and usage instructions at [holoviz-dev.github.io/holoviz-skills](https://holoviz-dev.github.io/holoviz-skills/). -- If you're contributing to hvPlot, see the [Developer Guide](../developer_guide.md) for how the Markdown docs and `llms.txt` are built. From 06cb56b5d7de7447c219feaeb17adf9b04cbf4df Mon Sep 17 00:00:00 2001 From: Isaiah Akorita Date: Wed, 19 Aug 2026 23:34:40 +0100 Subject: [PATCH 5/5] review --- doc/how_to/use_llms.md | 51 +++++++++++++++++++++++------------------- 1 file changed, 28 insertions(+), 23 deletions(-) diff --git a/doc/how_to/use_llms.md b/doc/how_to/use_llms.md index ba9ec15ba..50bb202dc 100644 --- a/doc/how_to/use_llms.md +++ b/doc/how_to/use_llms.md @@ -6,44 +6,49 @@ AI assistants (like Claude, GitHub Copilot, or OpenAI Codex) can write hvPlot co By the end of this guide you'll be able to: -- Give your AI assistant a curated index of the most useful hvPlot documentation pages - Install the HoloViz skills so your assistant follows hvPlot best practices automatically +- Give your AI assistant a curated index of the most useful hvPlot documentation pages ## Prerequisites +- A python package installer like `pip` or `uv` if you want to install the skills - An AI assistant that can read web content or local files (for example Claude, GitHub Copilot, or OpenAI Codex) -- A python package installer like `pip` or `uvx` if you want to install the skills ## Install the HoloViz skills The [holoviz-skills](https://holoviz-dev.github.io/holoviz-skills/) repository provides a curated collection of [Agent Skills](https://www.anthropic.com/news/skills) for the HoloViz ecosystem, including hvPlot. Agent Skills are folders of instructions and references that teach an assistant how to work with a library correctly. -1. Install the package: +::::{tab-set} + +:::{tab-item} uv + +```bash +uvx holoviz-skills@latest install +``` - ```bash - pip install holoviz-skills - ``` +::: - OR +:::{tab-item} pip +```bash +pip install holoviz-skills +``` - ```bash - uvx install holoviz-skills - ``` +::: -2. Install the skills for your tool: +:::: - ```bash - holoviz-skills install - ``` +```bash +holoviz-skills install +``` - This auto-detects the AI tools on your machine. You can also target a specific tool, for example: +The `install` command auto-detects the AI tools on your machine. You can also target a specific tool, for example: - ```bash - holoviz-skills install --claude-code - holoviz-skills install --copilot - ``` +```bash +holoviz-skills install --claude-code +holoviz-skills install --copilot +``` -3. Restart your assistant so it picks up the newly installed skills. +You may need to restart your assistant so it picks up the newly installed skills. ## Point your assistant at the docs @@ -55,13 +60,13 @@ hvPlot publishes a machine-friendly index of its documentation that your assista 2. The index lists the most relevant pages and links to their Markdown versions under: - `https://hvplot.holoviz.org/en/docs/latest/markdown/` + `https://hvplot.holoviz.org/en/docs/latest/markdown/`, for example, `https://hvplot.holoviz.org/en/docs/latest/markdown/tutorials/getting_started.md` -3. Ask your assistant to read the pages relevant to your task before writing code. For example, to create a plot you might have it read `tutorials/getting_started.md` and the API reference page for the method you need. +3. Ask your assistant to read the pages relevant to your task before writing code. For example, to create a plot you might have it read the Getting Started tutorial and the API reference page for the method you need. On its own, it will read the appropriate Markdown pages. The Markdown pages are intentionally free of the navigation chrome, CSS, and JavaScript of the full HTML site, so they consume far fewer tokens and are easier for an assistant to parse. ## Which approach should I use? - **Point your assistant at the docs** is a good fit for a one-off task or when you can't install packages, and it always reflects the latest published docs. -- **Install the HoloViz skills** gives your assistant packaged, opinionated guidance that works offline, but you need to update it as hvPlot evolves. +- **Install the HoloViz skills** gives your assistant packaged, opinionated guidance that works offline, but you need to update it as hvPlot evolves. Once the skills are installed, pointing to the Markdown docs should no longer be needed if you want your agent to be able to fetch the latest docs, as the skills already teach the agent how to do that.