fix mkdoc warnings (#8480)

TomeHirata · web-flow · commit b74b387c99b1 · 2025-07-04T09:18:38.000+09:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -89,7 +89,7 @@ Once the pull request is approved, a team member will take care of merging.
 
 ## Environment Setup
 
-Python 3.9 or later is required.
+Python 3.10 or later is required.
 
 Setting up your DSPy development environment requires you to fork the DSPy repository and clone it locally.
 If you are not familiar with the GitHub fork process, please refer to [Fork a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo). After creating the fork, clone
diff --git a/docs/docs/api/adapters/Adapter.md b/docs/docs/api/adapters/Adapter.md
@@ -24,4 +24,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/adapters/ChatAdapter.md b/docs/docs/api/adapters/ChatAdapter.md
@@ -27,4 +27,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/adapters/JSONAdapter.md b/docs/docs/api/adapters/JSONAdapter.md
@@ -27,4 +27,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/adapters/TwoStepAdapter.md b/docs/docs/api/adapters/TwoStepAdapter.md
@@ -24,4 +24,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/evaluation/CompleteAndGrounded.md b/docs/docs/api/evaluation/CompleteAndGrounded.md
@@ -32,4 +32,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/evaluation/Evaluate.md b/docs/docs/api/evaluation/Evaluate.md
@@ -14,4 +14,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/evaluation/SemanticF1.md b/docs/docs/api/evaluation/SemanticF1.md
@@ -32,4 +32,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/evaluation/answer_exact_match.md b/docs/docs/api/evaluation/answer_exact_match.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/evaluation/answer_passage_match.md b/docs/docs/api/evaluation/answer_passage_match.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/models/Embedder.md b/docs/docs/api/models/Embedder.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/models/LM.md b/docs/docs/api/models/LM.md
@@ -26,4 +26,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/modules/BestOfN.md b/docs/docs/api/modules/BestOfN.md
@@ -32,4 +32,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/modules/ChainOfThought.md b/docs/docs/api/modules/ChainOfThought.md
@@ -33,4 +33,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/modules/Module.md b/docs/docs/api/modules/Module.md
@@ -31,4 +31,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/modules/MultiChainComparison.md b/docs/docs/api/modules/MultiChainComparison.md
@@ -32,4 +32,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/modules/Parallel.md b/docs/docs/api/modules/Parallel.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/modules/Predict.md b/docs/docs/api/modules/Predict.md
@@ -36,4 +36,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/modules/ProgramOfThought.md b/docs/docs/api/modules/ProgramOfThought.md
@@ -32,4 +32,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/modules/ReAct.md b/docs/docs/api/modules/ReAct.md
@@ -34,4 +34,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/modules/Refine.md b/docs/docs/api/modules/Refine.md
@@ -32,4 +32,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/BetterTogether.md b/docs/docs/api/optimizers/BetterTogether.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/BootstrapFewShot.md b/docs/docs/api/optimizers/BootstrapFewShot.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/BootstrapFewShotWithRandomSearch.md b/docs/docs/api/optimizers/BootstrapFewShotWithRandomSearch.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/BootstrapFinetune.md b/docs/docs/api/optimizers/BootstrapFinetune.md
@@ -17,4 +17,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/BootstrapRS.md b/docs/docs/api/optimizers/BootstrapRS.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/COPRO.md b/docs/docs/api/optimizers/COPRO.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/Ensemble.md b/docs/docs/api/optimizers/Ensemble.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/InferRules.md b/docs/docs/api/optimizers/InferRules.md
@@ -20,4 +20,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/KNN.md b/docs/docs/api/optimizers/KNN.md
@@ -14,4 +14,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/KNNFewShot.md b/docs/docs/api/optimizers/KNNFewShot.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/LabeledFewShot.md b/docs/docs/api/optimizers/LabeledFewShot.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/optimizers/MIPROv2.md b/docs/docs/api/optimizers/MIPROv2.md
@@ -17,6 +17,7 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
 
 ## Example Usage
diff --git a/docs/docs/api/primitives/Example.md b/docs/docs/api/primitives/Example.md
@@ -23,4 +23,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/primitives/History.md b/docs/docs/api/primitives/History.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/primitives/Image.md b/docs/docs/api/primitives/Image.md
@@ -21,4 +21,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/primitives/Prediction.md b/docs/docs/api/primitives/Prediction.md
@@ -26,4 +26,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/primitives/Tool.md b/docs/docs/api/primitives/Tool.md
@@ -22,4 +22,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/signatures/InputField.md b/docs/docs/api/signatures/InputField.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/signatures/OutputField.md b/docs/docs/api/signatures/OutputField.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/signatures/Signature.md b/docs/docs/api/signatures/Signature.md
@@ -22,4 +22,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/tools/ColBERTv2.md b/docs/docs/api/tools/ColBERTv2.md
@@ -14,4 +14,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/tools/Embeddings.md b/docs/docs/api/tools/Embeddings.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/tools/PythonInterpreter.md b/docs/docs/api/tools/PythonInterpreter.md
@@ -16,4 +16,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/StatusMessage.md b/docs/docs/api/utils/StatusMessage.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/StatusMessageProvider.md b/docs/docs/api/utils/StatusMessageProvider.md
@@ -19,4 +19,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/StreamListener.md b/docs/docs/api/utils/StreamListener.md
@@ -15,4 +15,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/asyncify.md b/docs/docs/api/utils/asyncify.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/configure_cache.md b/docs/docs/api/utils/configure_cache.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/disable_litellm_logging.md b/docs/docs/api/utils/disable_litellm_logging.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/disable_logging.md b/docs/docs/api/utils/disable_logging.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/enable_litellm_logging.md b/docs/docs/api/utils/enable_litellm_logging.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/enable_logging.md b/docs/docs/api/utils/enable_logging.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/inspect_history.md b/docs/docs/api/utils/inspect_history.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/load.md b/docs/docs/api/utils/load.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/api/utils/streamify.md b/docs/docs/api/utils/streamify.md
@@ -12,4 +12,5 @@
         show_object_full_path: false
         separate_signature: false
         inherited_members: true
+:::
 <!-- END_API_REF -->
diff --git a/docs/docs/faqs.md b/docs/docs/faqs.md
@@ -19,7 +19,7 @@ The **DSPy** philosophy and abstraction differ significantly from other librarie
 
 ## Basic Usage
 
-**How should I use DSPy for my task?** We wrote a [eight-step guide](/building-blocks/solving_your_task) on this. In short, using DSPy is an iterative process. You first define your task and the metrics you want to maximize, and prepare a few example inputs — typically without labels (or only with labels for the final outputs, if your metric requires them). Then, you build your pipeline by selecting built-in layers (`modules`) to use, giving each layer a `signature` (input/output spec), and then calling your modules freely in your Python code. Lastly, you use a DSPy `optimizer` to compile your code into high-quality instructions, automatic few-shot examples, or updated LM weights for your LM.
+**How should I use DSPy for my task?** We wrote a [eight-step guide](learn/index.md) on this. In short, using DSPy is an iterative process. You first define your task and the metrics you want to maximize, and prepare a few example inputs — typically without labels (or only with labels for the final outputs, if your metric requires them). Then, you build your pipeline by selecting built-in layers (`modules`) to use, giving each layer a `signature` (input/output spec), and then calling your modules freely in your Python code. Lastly, you use a DSPy `optimizer` to compile your code into high-quality instructions, automatic few-shot examples, or updated LM weights for your LM.
 
 **How do I convert my complex prompt into a DSPy pipeline?** See the same answer above.
 
@@ -34,11 +34,11 @@ You can specify multiple output fields. For the short-form signature, you can li
 
 - **How do I define my own metrics? Can metrics return a float?**
 
-You can define metrics as simply Python functions that process model generations and evaluate them based on user-defined requirements. Metrics can compare existent data (e.g. gold labels) to model predictions or they can be used to assess various components of an output using validation feedback from LMs (e.g. LLMs-as-Judges). Metrics can return `bool`, `int`, and `float` types scores. Check out the official [Metrics docs](/building-blocks/5-metrics) to learn more about defining custom metrics and advanced evaluations using AI feedback and/or DSPy programs.
+You can define metrics as simply Python functions that process model generations and evaluate them based on user-defined requirements. Metrics can compare existent data (e.g. gold labels) to model predictions or they can be used to assess various components of an output using validation feedback from LMs (e.g. LLMs-as-Judges). Metrics can return `bool`, `int`, and `float` types scores. Check out the official [Metrics docs](learn/evaluation/metrics.md) to learn more about defining custom metrics and advanced evaluations using AI feedback and/or DSPy programs.
 
 - **How expensive or slow is compiling??**
 
-To reflect compiling metrics, we highlight an experiment for reference, compiling the [`SimplifiedBaleen`](/tutorials/simplified-baleen) using the [`dspy.BootstrapFewShotWithRandomSearch`](/deep-dive/teleprompter/bootstrap-fewshot) optimizer on the `gpt-3.5-turbo-1106` model over 7 candidate programs and 10 threads. We report that compiling this program takes around 6 minutes with 3200 API calls, 2.7 million input tokens and 156,000 output tokens, reporting a total cost of $3 USD (at the current pricing of the OpenAI model).
+To reflect compiling metrics, we highlight an experiment for reference, compiling a program using the [BootstrapFewShotWithRandomSearch](api/optimizers/BootstrapFewShotWithRandomSearch.md) optimizer on the `gpt-3.5-turbo-1106` model over 7 candidate programs and 10 threads. We report that compiling this program takes around 6 minutes with 3200 API calls, 2.7 million input tokens and 156,000 output tokens, reporting a total cost of $3 USD (at the current pricing of the OpenAI model).
 
 Compiling DSPy `optimizers` naturally will incur additional LM calls, but we substantiate this overhead with minimalistic executions with the goal of maximizing performance. This invites avenues to enhance performance of smaller models by compiling DSPy programs with larger models to learn enhanced behavior during compile-time and propagate such behavior to the tested smaller model during inference-time.  
 
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -374,7 +374,7 @@ Given a few tens or hundreds of representative _inputs_ of your task and a _metr
         optimized_rag = tp.compile(RAG(), trainset=trainset, max_bootstrapped_demos=2, max_labeled_demos=2)
         ```
 
-        For a complete RAG example that you can run, start this [tutorial](/tutorials/rag/). It improves the quality of a RAG system over a subset of StackExchange communities by 10% relative gain.
+        For a complete RAG example that you can run, start this [tutorial](tutorials/rag/index.ipynb). It improves the quality of a RAG system over a subset of StackExchange communities by 10% relative gain.
 
     === "Optimizing weights for Classification"
         <details><summary>Click to show dataset setup code.</summary>
@@ -447,4 +447,4 @@ Compared to monolithic LMs, DSPy's modular paradigm enables a large community to
 
 The DSPy research effort started at Stanford NLP in Feb 2022, building on what we had learned from developing early [compound LM systems](https://bair.berkeley.edu/blog/2024/02/18/compound-ai-systems/) like [ColBERT-QA](https://arxiv.org/abs/2007.00814), [Baleen](https://arxiv.org/abs/2101.00436), and [Hindsight](https://arxiv.org/abs/2110.07752). The first version was released as [DSP](https://arxiv.org/abs/2212.14024) in Dec 2022 and evolved by Oct 2023 into [DSPy](https://arxiv.org/abs/2310.03714). Thanks to [250 contributors](https://github.com/stanfordnlp/dspy/graphs/contributors), DSPy has introduced tens of thousands of people to building and optimizing modular LM programs.
 
-Since then, DSPy's community has produced a large body of work on optimizers, like [MIPROv2](https://arxiv.org/abs/2406.11695), [BetterTogether](https://arxiv.org/abs/2407.10930), and [LeReT](https://arxiv.org/abs/2410.23214), on program architectures, like [STORM](https://arxiv.org/abs/2402.14207), [IReRa](https://arxiv.org/abs/2401.12178), and [DSPy Assertions](https://arxiv.org/abs/2312.13382), and on successful applications to new problems, like [PAPILLON](https://arxiv.org/abs/2410.17127), [PATH](https://arxiv.org/abs/2406.11706), [WangLab@MEDIQA](https://arxiv.org/abs/2404.14544), [UMD's Prompting Case Study](https://arxiv.org/abs/2406.06608), and [Haize's Red-Teaming Program](https://blog.haizelabs.com/posts/dspy/), in addition to many open-source projects, production applications, and other [use cases](/community/use-cases).
+Since then, DSPy's community has produced a large body of work on optimizers, like [MIPROv2](https://arxiv.org/abs/2406.11695), [BetterTogether](https://arxiv.org/abs/2407.10930), and [LeReT](https://arxiv.org/abs/2410.23214), on program architectures, like [STORM](https://arxiv.org/abs/2402.14207), [IReRa](https://arxiv.org/abs/2401.12178), and [DSPy Assertions](https://arxiv.org/abs/2312.13382), and on successful applications to new problems, like [PAPILLON](https://arxiv.org/abs/2410.17127), [PATH](https://arxiv.org/abs/2406.11706), [WangLab@MEDIQA](https://arxiv.org/abs/2404.14544), [UMD's Prompting Case Study](https://arxiv.org/abs/2406.06608), and [Haize's Red-Teaming Program](https://blog.haizelabs.com/posts/dspy/), in addition to many open-source projects, production applications, and other [use cases](community/use-cases.md).
diff --git a/docs/docs/learn/optimization/optimizers.md b/docs/docs/learn/optimization/optimizers.md
diff --git a/docs/docs/learn/programming/modules.md b/docs/docs/learn/programming/modules.md
diff --git a/docs/docs/production/index.md b/docs/docs/production/index.md
diff --git a/docs/docs/roadmap.md b/docs/docs/roadmap.md
diff --git a/docs/docs/tutorials/build_ai_program/index.md b/docs/docs/tutorials/build_ai_program/index.md
diff --git a/docs/docs/tutorials/core_development/index.md b/docs/docs/tutorials/core_development/index.md
diff --git a/docs/docs/tutorials/index.md b/docs/docs/tutorials/index.md
diff --git a/docs/docs/tutorials/observability/index.md b/docs/docs/tutorials/observability/index.md
diff --git a/docs/docs/tutorials/optimize_ai_program/index.md b/docs/docs/tutorials/optimize_ai_program/index.md
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
diff --git a/docs/scripts/generate_api_docs.py b/docs/scripts/generate_api_docs.py
diff --git a/dspy/primitives/base_module.py b/dspy/primitives/base_module.py
diff --git a/dspy/primitives/module.py b/dspy/primitives/module.py
