Add llms-full.txt, AGENTS.md, context7.json and a machine-readable API reference

.github/workflows/docs.yml

@@ -24,6 +24,12 @@ jobs:
       with:
         python-version: '3.13'
 
+    # vhdl-dump-ast generates the machine-readable VHDL API reference (tools/build_api_reference.py)
+    - name: '⚙️ Setup vhdl-dump-ast'
+      run: |
+        cargo install vhdl-dump-ast --version 0.1.0 --locked
+        echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+
     - name: Install dependencies
       run: |
         pip install -U pip --progress-bar off

AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md
+
+Guidance for AI coding agents working on the VUnit repository.
+
+To *use* VUnit rather than develop it, read the [documentation](https://vunit.github.io), all of it as plain text in
+[llms-full.txt](https://vunit.github.io/llms-full.txt), and the machine-readable
+[VHDL API](https://vunit.github.io/api/vunit_lib.json) and [Python API](https://vunit.github.io/api/python.json).
+
+## Repository layout
+
+- `vunit/`: the Python package, with the run script API in `vunit/ui/`, the simulator interfaces in `vunit/sim_if/` and the test runner in `vunit/test/`.
+- `vunit/vhdl/`: the VHDL libraries compiled into `vunit_lib` (`run`, `check`, `logging`, `com`, `data_types`, `verification_components`, ...). `vunit/vhdl/osvvm` is a third-party git submodule.
+- `vunit/verilog/`: the SystemVerilog support.
+- `tests/unit/`, `tests/acceptance/`, `tests/lint/`: see "Testing" in `docs/contributing.rst`.
+- `examples/`, `docs/` (Sphinx) and `tools/` (documentation and release scripts).
+
+## Commands
+
+- **Unit tests:** `pytest tests/unit/`, or `tox -e py313-unit`.
+- **Lint** (pycodestyle, pylint, mypy, license headers): `tox -e py313-lint`.
+- **Formatting:** black, with the line length from `pyproject.toml`. Check only the files you changed, e.g. `python -m black --check <files>`. `tox -e py313-fmt` formats every file in the repository.
+- **Acceptance tests with a simulator:** `tox -e py313-acceptance-<simulator>`, where `<simulator>` is `activehdl`, `ghdl`, `modelsim`, `nvc` or `rivierapro`.
+- **Verification components:** `tox -e py313-vcomponents-<simulator>`.
+- **Documentation:** `tox -e py313-docs`.
+  - The build needs the git tags for the release notes.
+  - It needs `vhdl-dump-ast` for the API reference (`cargo install vhdl-dump-ast --version 0.1.0 --locked`). Set `VUNIT_DOCS_SKIP_API=1` to build without it.
+- **All tox environments:** `tox -l`.
+
+## Rules
+
+Details are in `docs/contributing.rst`.
+
+- **News fragments:** a change visible to users needs a news fragment `docs/news.d/<issue or pull request number>.<type>.rst`. `<type>` is one of `breaking`, `bugfix`, `doc`, `deprecation`, `feature` or `misc`.
+- **License header:** Python, VHDL and Verilog source files start with the Mozilla Public License 2.0 header with the copyright assigned to Lars Asplund. Copy it from a file next to the new one. `tests/lint/test_license.py` checks it.
+- **Tests:** new functionality comes with tests.
+
+## Generated files
+
+Change the generator and run it again instead of editing its output by hand:
+
+- `vunit/vhdl/check/tools/generate_check_equal.py`, `generate_check_equal_2008p.py` and `generate_check_match.py` generate parts of `vunit/vhdl/check/src/check_api*.vhd` and `check*.vhd`, and their testbenches.
+- `vunit/vhdl/data_types/tools/generate_dict.py` generates the typed `set_*`/`get_*` subprograms and their aliases in `dict_pkg`.
+
+## Pitfalls
+
+- Running a `run.py` inside the repository creates a `vunit_out/` directory next to it. Do not commit it.

context7.json

@@ -1,4 +1,22 @@
 {
+  "$schema": "https://context7.com/schema/context7.json",
   "url": "https://context7.com/vunit/vunit",
-  "public_key": "pk_lFI1bFQ8pHgYDeBRtvnEp"
+  "public_key": "pk_lFI1bFQ8pHgYDeBRtvnEp",
+  "projectTitle": "VUnit",
+  "description": "Unit testing framework for VHDL and SystemVerilog: a Python test runner (run.py) and VHDL libraries for checks, logging, message passing, data types and verification components.",
+  "folders": [
+    "docs",
+    "examples"
+  ],
+  "excludeFolders": [
+    "docs/blog",
+    "docs/release_notes",
+    "docs/news.d"
+  ],
+  "excludeFiles": [],
+  "rules": [
+    "Complete VHDL API signatures: https://vunit.github.io/api/vunit_lib.json",
+    "Complete Python API signatures: https://vunit.github.io/api/python.json",
+    "All documentation as plain text, including the VHDL package headers: https://vunit.github.io/llms-full.txt"
+  ]
 }

docs/news.d/1222.doc.rst

@@ -0,0 +1,3 @@
+The website now publishes, for AI agents, all documentation and the declarations of all VHDL packages as plain text in
+``llms-full.txt``, and a machine-readable reference of the VHDL and Python APIs (``api/vunit_lib.json`` and
+``api/python.json``). ``AGENTS.md`` and ``context7.json`` were added to the repository.

pyproject.toml

@@ -103,7 +103,9 @@ isolated_build = True
 
 [testenv]
 recreate=True
-passenv=ALDEC_LICENSE_FILE
+passenv=
+    ALDEC_LICENSE_FILE
+    VUNIT_DOCS_SKIP_API
 
 deps=
     fmt: black
@@ -136,7 +138,9 @@ commands=
     fmt:         {envpython} -m black ./ --exclude .eggs|.git|.hg|.mypy_cache|.nox|.tox|.venv|_build|buck-out|build|dist' {posargs}
     unit:        {envpython} -m pytest -v -ra tests/unit {posargs}
     lint:        {envpython} -m pytest -v -ra tests/lint {posargs}
+    docs:        {envpython} -m pytest -ra tests/unit/test_api_reference.py
     docs:        {envpython} tools/build_docs.py {envtmpdir}/docsbuild {posargs}
+    docs:        {envpython} tools/build_api_reference.py {envtmpdir}/docsbuild
     acceptance:  {envpython} -m pytest -v -ra tests/acceptance {posargs}
     vcomponents: {envpython} vunit/vhdl/verification_components/run.py --clean
     coverage:    {envpython} -m coverage run --branch --source vunit/ -m pytest tests/