Skip to content

armgit / dspy

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.yml
index 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.md
diff --git a/docs/scripts/generate_api_docs.py b/docs/scripts/generate_api_docs.py
index 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 directories
remove_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)