DSPy: The framework for programming—not prompting—language models
Python
Add api/ category index pages to stop directory-URL 404s (#9902)
Michal Migurskie6cda7614818
diff --git a/docs/docs/api/adapters/index.md b/docs/docs/api/adapters/index.mdnew file mode 100644index 000000000..e73a7bf26--- /dev/null+++ b/docs/docs/api/adapters/index.md@@ -0,0 +1,11 @@+# Adapters++API reference for DSPy adapters. Select a page below.++<!-- START_API_INDEX -->+- [Adapter](Adapter.md)+- [ChatAdapter](ChatAdapter.md)+- [JSONAdapter](JSONAdapter.md)+- [TwoStepAdapter](TwoStepAdapter.md)+- [XMLAdapter](XMLAdapter.md)+<!-- END_API_INDEX -->diff --git a/docs/docs/api/evaluation/index.md b/docs/docs/api/evaluation/index.mdnew file mode 100644index 000000000..7c367dfbf--- /dev/null+++ b/docs/docs/api/evaluation/index.md@@ -0,0 +1,12 @@+# Evaluation++API reference for DSPy evaluation. Select a page below.++<!-- START_API_INDEX -->+- [answer_exact_match](answer_exact_match.md)+- [answer_passage_match](answer_passage_match.md)+- [CompleteAndGrounded](CompleteAndGrounded.md)+- [Evaluate](Evaluate.md)+- [EvaluationResult](EvaluationResult.md)+- [SemanticF1](SemanticF1.md)+<!-- END_API_INDEX -->diff --git a/docs/docs/api/experimental/index.md b/docs/docs/api/experimental/index.mdnew file mode 100644index 000000000..26678917e--- /dev/null+++ b/docs/docs/api/experimental/index.md@@ -0,0 +1,8 @@+# Experimental++API reference for DSPy experimental. Select a page below.++<!-- START_API_INDEX -->+- [Citations](Citations.md)+- [Document](Document.md)+<!-- END_API_INDEX -->diff --git a/docs/docs/api/models/index.md b/docs/docs/api/models/index.mdnew file mode 100644index 000000000..d603ebf73--- /dev/null+++ b/docs/docs/api/models/index.md@@ -0,0 +1,9 @@+# Models++API reference for DSPy models. Select a page below.++<!-- START_API_INDEX -->+- [BaseLM](BaseLM.md)+- [Embedder](Embedder.md)+- [LM](LM.md)+<!-- END_API_INDEX -->diff --git a/docs/docs/api/modules/index.md b/docs/docs/api/modules/index.mdnew file mode 100644index 000000000..70646b958--- /dev/null+++ b/docs/docs/api/modules/index.md@@ -0,0 +1,17 @@+# Modules++API reference for DSPy modules. Select a page below.++<!-- START_API_INDEX -->+- [BestOfN](BestOfN.md)+- [ChainOfThought](ChainOfThought.md)+- [CodeAct](CodeAct.md)+- [Module](Module.md)+- [MultiChainComparison](MultiChainComparison.md)+- [Parallel](Parallel.md)+- [Predict](Predict.md)+- [ProgramOfThought](ProgramOfThought.md)+- [ReAct](ReAct.md)+- [Refine](Refine.md)+- [RLM](RLM.md)+<!-- END_API_INDEX -->diff --git a/docs/docs/api/optimizers/index.md b/docs/docs/api/optimizers/index.mdnew file mode 100644index 000000000..bdff46795--- /dev/null+++ b/docs/docs/api/optimizers/index.md@@ -0,0 +1,20 @@+# Optimizers++API reference for DSPy optimizers. Select a page below.++<!-- START_API_INDEX -->+- [BetterTogether](BetterTogether.md)+- [BootstrapFewShot](BootstrapFewShot.md)+- [BootstrapFewShotWithRandomSearch](BootstrapFewShotWithRandomSearch.md)+- [BootstrapFinetune](BootstrapFinetune.md)+- [BootstrapRS](BootstrapRS.md)+- [COPRO](COPRO.md)+- [Ensemble](Ensemble.md)+- [GEPA](GEPA/overview.md)+- [InferRules](InferRules.md)+- [KNN](KNN.md)+- [KNNFewShot](KNNFewShot.md)+- [LabeledFewShot](LabeledFewShot.md)+- [MIPROv2](MIPROv2.md)+- [SIMBA](SIMBA.md)+<!-- END_API_INDEX -->diff --git a/docs/docs/api/primitives/index.md b/docs/docs/api/primitives/index.mdnew file mode 100644index 000000000..c7102ccc8--- /dev/null+++ b/docs/docs/api/primitives/index.md@@ -0,0 +1,14 @@+# Primitives++API reference for DSPy primitives. Select a page below.++<!-- START_API_INDEX -->+- [Audio](Audio.md)+- [Code](Code.md)+- [Example](Example.md)+- [History](History.md)+- [Image](Image.md)+- [Prediction](Prediction.md)+- [Tool](Tool.md)+- [ToolCalls](ToolCalls.md)+<!-- END_API_INDEX -->diff --git a/docs/docs/api/signatures/index.md b/docs/docs/api/signatures/index.mdnew file mode 100644index 000000000..df855ffee--- /dev/null+++ b/docs/docs/api/signatures/index.md@@ -0,0 +1,9 @@+# Signatures++API reference for DSPy signatures. Select a page below.++<!-- START_API_INDEX -->+- [InputField](InputField.md)+- [OutputField](OutputField.md)+- [Signature](Signature.md)+<!-- END_API_INDEX -->diff --git a/docs/docs/api/tools/index.md b/docs/docs/api/tools/index.mdnew file mode 100644index 000000000..91c829e96--- /dev/null+++ b/docs/docs/api/tools/index.md@@ -0,0 +1,9 @@+# Tools++API reference for DSPy tools. Select a page below.++<!-- START_API_INDEX -->+- [ColBERTv2](ColBERTv2.md)+- [Embeddings](Embeddings.md)+- [PythonInterpreter](PythonInterpreter.md)+<!-- END_API_INDEX -->diff --git a/docs/docs/api/utils/index.md b/docs/docs/api/utils/index.mdnew file mode 100644index 000000000..e72bdbbd2--- /dev/null+++ b/docs/docs/api/utils/index.md@@ -0,0 +1,21 @@+# Utils++API reference for DSPy utils. Select a page below.++<!-- START_API_INDEX -->+- [asyncify](asyncify.md)+- [configure](configure.md)+- [configure_cache](configure_cache.md)+- [context](context.md)+- [disable_litellm_logging](disable_litellm_logging.md)+- [disable_logging](disable_logging.md)+- [enable_litellm_logging](enable_litellm_logging.md)+- [enable_logging](enable_logging.md)+- [Errors](Errors.md)+- [inspect_history](inspect_history.md)+- [load](load.md)+- [StatusMessage](StatusMessage.md)+- [StatusMessageProvider](StatusMessageProvider.md)+- [streamify](streamify.md)+- [StreamListener](StreamListener.md)+<!-- END_API_INDEX -->diff --git a/docs/mkdocs.yml b/docs/mkdocs.ymlindex 30fb53dd4..0c2121b14 100644--- a/docs/mkdocs.yml+++ b/docs/mkdocs.yml@@ -100,12 +100,14 @@ nav:- API Reference:- API Reference: api/index.md- Adapters:+ - api/adapters/index.md- Adapter: api/adapters/Adapter.md- ChatAdapter: api/adapters/ChatAdapter.md- XMLAdapter: api/adapters/XMLAdapter.md- JSONAdapter: api/adapters/JSONAdapter.md- TwoStepAdapter: api/adapters/TwoStepAdapter.md- Evaluation:+ - api/evaluation/index.md- CompleteAndGrounded: api/evaluation/CompleteAndGrounded.md- Evaluate: api/evaluation/Evaluate.md- EvaluationResult: api/evaluation/EvaluationResult.md@@ -113,13 +115,16 @@ nav:- answer_exact_match: api/evaluation/answer_exact_match.md- answer_passage_match: api/evaluation/answer_passage_match.md- Experimental:+ - api/experimental/index.md- Citations: api/experimental/Citations.md- Document: api/experimental/Document.md- Models:+ - api/models/index.md- BaseLM: api/models/BaseLM.md- Embedder: api/models/Embedder.md- LM: api/models/LM.md- Modules:+ - api/modules/index.md- BestOfN: api/modules/BestOfN.md- ChainOfThought: api/modules/ChainOfThought.md- CodeAct: api/modules/CodeAct.md@@ -132,6 +137,7 @@ nav:- Refine: api/modules/Refine.md- RLM: api/modules/RLM.md- Optimizers:+ - api/optimizers/index.md- GEPA:- 1. GEPA Overview: api/optimizers/GEPA/overview.md- 2. GEPA Advanced: api/optimizers/GEPA/GEPA_Advanced.md@@ -149,6 +155,7 @@ nav:- MIPROv2: api/optimizers/MIPROv2.md- SIMBA: api/optimizers/SIMBA.md- Primitives:+ - api/primitives/index.md- Audio: api/primitives/Audio.md- Code: api/primitives/Code.md- Example: api/primitives/Example.md@@ -158,14 +165,17 @@ nav:- Tool: api/primitives/Tool.md- ToolCalls: api/primitives/ToolCalls.md- Signatures:+ - api/signatures/index.md- InputField: api/signatures/InputField.md- OutputField: api/signatures/OutputField.md- Signature: api/signatures/Signature.md- Tools:+ - api/tools/index.md- ColBERTv2: api/tools/ColBERTv2.md- Embeddings: api/tools/Embeddings.md- PythonInterpreter: api/tools/PythonInterpreter.md- Utils:+ - api/utils/index.md- Errors: api/utils/Errors.md- configure: api/utils/configure.md- context: api/utils/context.mddiff --git a/docs/scripts/generate_api_docs.py b/docs/scripts/generate_api_docs.pyindex 3dcf351a9..de2e88365 100644--- a/docs/scripts/generate_api_docs.py+++ b/docs/scripts/generate_api_docs.py@@ -317,6 +317,85 @@ def remove_empty_dirs(path: Path):path.rmdir()+API_INDEX_START = "<!-- START_API_INDEX -->"+API_INDEX_END = "<!-- END_API_INDEX -->"+++def read_existing_index_content(file_path: Path) -> tuple[str, str]:+ """Split an existing index file around the auto-generated link list.++ Returns (content_before_list, content_after_list) so any prose a maintainer+ added outside the markers is preserved across regenerations.+ """+ if not file_path.exists():+ return "", ""++ content = file_path.read_text()++ start = content.find(API_INDEX_START)+ if start == -1:+ return content, ""++ end = content.find(API_INDEX_END)+ if end == -1:+ end = len(content)+ else:+ end = end + len(API_INDEX_END)++ return content[:start].rstrip(), content[end:].lstrip()+++def build_index_links(category_dir: Path) -> str:+ """Build a sorted bullet list of links to every page in a category dir."""+ entries = []+ for child in sorted(category_dir.iterdir(), key=lambda p: p.name.lower()):+ if child.name == "index.md":+ continue+ if child.is_dir():+ # Link to a representative page so mkdocs can resolve the link; the+ # bare directory URL still works via navigation.indexes / redirects.+ target = None+ for candidate in ("index.md", "overview.md"):+ if (child / candidate).exists():+ target = f"{child.name}/{candidate}"+ break+ if target is None:+ sub_pages = sorted(child.glob("*.md"), key=lambda p: p.name.lower())+ if not sub_pages:+ continue+ target = f"{child.name}/{sub_pages[0].name}"+ entries.append(f"- [{child.name}]({target})")+ elif child.suffix == ".md":+ entries.append(f"- [{child.stem}]({child.name})")+ return "\n".join(entries)+++def generate_category_index(category: str, category_dir: Path):+ """Write an index.md landing page for an api category directory.++ Without this, directory URLs like ``/api/optimizers/`` return a 404 when a+ user trims a child page's URL upward. The link list is regenerated between+ markers; any prose outside the markers is preserved.+ """+ if not category_dir.is_dir():+ return++ links = build_index_links(category_dir)+ if not links:+ return++ title = category.capitalize()+ api_content = f"{API_INDEX_START}\n{links}\n{API_INDEX_END}"++ index_path = category_dir / "index.md"+ pre_content, post_content = read_existing_index_content(index_path)+ if not pre_content:+ pre_content = f"# {title}\n\nAPI reference for DSPy {category}. Select a page below."++ full_content = f"{pre_content}\n\n{api_content}\n{post_content}".strip() + "\n"+ index_path.write_text(full_content)++if __name__ == "__main__":api_dir = Path("docs/api")api_dir.mkdir(parents=True, exist_ok=True)@@ -331,3 +410,7 @@ if __name__ == "__main__":# Clean up empty directoriesremove_empty_dirs(api_dir)++ # Generate a landing page per category so directory URLs don't 404.+ for category in API_MAPPING.keys():+ generate_category_index(category, api_dir / category)