diff --git a/.github/utils/create_unstable_docs_docusaurus.py b/.github/utils/create_unstable_docs_docusaurus.py index 97b96a88d7..1bd4dab0dc 100644 --- a/.github/utils/create_unstable_docs_docusaurus.py +++ b/.github/utils/create_unstable_docs_docusaurus.py @@ -57,7 +57,11 @@ if __name__ == "__main__": ### Docusaurus updates # copy docs to versioned_docs/version-target_unstable - shutil.copytree("docs-website/docs", f"docs-website/versioned_docs/version-{target_unstable}") + shutil.copytree( + src="docs-website/docs", + dst=f"docs-website/versioned_docs/version-{target_unstable}", + ignore=shutil.ignore_patterns("AGENTS.md"), + ) # copy reference to reference_versioned_docs/version-target_unstable shutil.copytree("docs-website/reference", f"docs-website/reference_versioned_docs/version-{target_unstable}") diff --git a/AGENTS.md b/AGENTS.md index bb7018e1a7..7da20a2e2f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -94,7 +94,8 @@ Also see directory-specific guidelines: - Keep inline comments and private-helper docs to what is non-obvious — remove restatements, keep durable caveats and rationale - Keep docstrings current with signatures and behavior, in the existing Haystack style: each public `:param` by meaning, default, and constraints; `:returns:` contracts; exceptions in the existing `:raises ValueError:` style; aliases like `ToolsType` reflected — stale docs mislead users and assistants - Keep doc examples minimal, runnable, and local: default constructors with required env vars like `OPENAI_API_KEY` noted nearby, only the imports the snippet uses, no restated defaults (name a model only for model-specific behavior), expected output as comments, generally `# >> ...` -- When behavior, fields, or names change, update every surface in the same PR: `haystack/components/` docstrings and examples, `docs-website/docs/` plus the current `versioned_docs/version-*/` page (e.g. `concepts/data-classes.mdx`), and `experimental` wording, `pydoc` IDs, and generated markdown filenames when promoting features +- When behavior, fields, or names change, update every relevant surface in the same PR: `haystack/components/` docstrings and examples, documentation pages, and `experimental` wording, `pydoc` IDs, and generated markdown filenames when promoting features +- Choose which documentation versions to update: update `docs-website/docs/` by default; also update the latest stable `versioned_docs/version-X.Y/` pages for corrections to stable docs or already-released core integration features. ## Code Style diff --git a/docs-website/versioned_docs/version-3.2/AGENTS.md b/docs-website/versioned_docs/version-3.2/AGENTS.md deleted file mode 100644 index 0f7e01ae2a..0000000000 --- a/docs-website/versioned_docs/version-3.2/AGENTS.md +++ /dev/null @@ -1,9 +0,0 @@ -# docs-website/docs/ Guidelines - -## Documentation - -- Edit `docs-website/docs/pipeline-components/` pages only for outdated, incorrect, or materially useful guidance; keep examples concise and `Agent`-level and polish prose before merge — avoids churn while keeping docs copyable -- Add `## Overview` near the top of `docs-website/docs/pipeline-components/**` pages — explains what the component does and why to use it before details -- Document component outputs, extractor side effects, and exact `doc.meta` keys; link producers, API references, and the authoritative reference for any partial config summary -- Use current chat APIs in new docs pipelines — `ChatPromptBuilder`, `ChatMessage`, chat generators, and `result["last_message"]` for agent output — matching wiring, edge names like `prompt`, and declared variables; keep YAML examples on current default model names -- Mark joiners/adapters optional where smart pipeline connections already handle the composition diff --git a/docs-website/versioned_docs/version-3.3/AGENTS.md b/docs-website/versioned_docs/version-3.3/AGENTS.md deleted file mode 100644 index 0f7e01ae2a..0000000000 --- a/docs-website/versioned_docs/version-3.3/AGENTS.md +++ /dev/null @@ -1,9 +0,0 @@ -# docs-website/docs/ Guidelines - -## Documentation - -- Edit `docs-website/docs/pipeline-components/` pages only for outdated, incorrect, or materially useful guidance; keep examples concise and `Agent`-level and polish prose before merge — avoids churn while keeping docs copyable -- Add `## Overview` near the top of `docs-website/docs/pipeline-components/**` pages — explains what the component does and why to use it before details -- Document component outputs, extractor side effects, and exact `doc.meta` keys; link producers, API references, and the authoritative reference for any partial config summary -- Use current chat APIs in new docs pipelines — `ChatPromptBuilder`, `ChatMessage`, chat generators, and `result["last_message"]` for agent output — matching wiring, edge names like `prompt`, and declared variables; keep YAML examples on current default model names -- Mark joiners/adapters optional where smart pipeline connections already handle the composition