Doc: Improve reference documentation with descriptions and fix links (#1222)

* Doc: Improve reference documentation with descriptions and fix links

- Add page titles and descriptions to reference docs
- Document ShellAgentConfig in agent configuration
- Add missing model configuration classes
- Fix relative link syntax in bundle and tools config
- Improve documentation consistency across reference pages

Signed-off-by: Joshua Shanks <jjshanks@gmail.com>

* Doc: Address review comments on reference documentation

- Update ShellAgent description to clarify it's invoked with `sweagent sh` for interactive workflows
- Move model config classes (HumanModelConfig, HumanThoughtModelConfig, ReplayModelConfig, InstantEmptySubmitModelConfig) from API LMs section to group with their corresponding model classes in testing sections
- Simplify parsers.md description to concisely explain action parser functionality
- Update template_config.md to better describe how templates format inputs/outputs for LM queries

---------

Signed-off-by: Joshua Shanks <jjshanks@gmail.com>

docs/reference/agent_config.md

@@ -13,11 +13,14 @@ It might be easiest to simply look at some of our example configurations in the
 ```
 </details>
 
-Currently, there are two main agent classes:
+Currently, there are three main agent classes:
 
 * `DefaultAgentConfig`: This is the default agent.
 * `RetryAgentConfig`: A "meta agent" that instantiates multiple agents for multiple attempts and then picks the best solution.
+* `ShellAgentConfig`: Config for `ShellAgent` (invoked with `sweagent sh`), which is an experimental mode for quick & interactive (human-in-the-loop) workflows.
 
 ::: sweagent.agent.agents.RetryAgentConfig
 
-::: sweagent.agent.agents.DefaultAgentConfig
+::: sweagent.agent.agents.DefaultAgentConfig
+
+::: sweagent.agent.agents.ShellAgentConfig

docs/reference/batch_instances.md

@@ -1,3 +1,7 @@
+# Batch instances
+
+This page documents the batch instances functionality for running SWE-agent on multiple problems.
+
 ::: sweagent.run.batch_instances
     options:
         members_order: source

docs/reference/bundle_config.md

@@ -3,7 +3,7 @@
 !!! note "Tool bundle configuration"
 
     This is the page for configuring a tool bundle, not for setting up the tools that are being used for the agent.
-    For the latter, see [tools configuration](./tools_config.md).
+    For the latter, see [tools configuration](tools_config.md).
 
 ::: sweagent.tools.bundle.BundleConfig
 

docs/reference/env.md

@@ -1,5 +1,9 @@
 # The environment class
 
+This page documents the `SWEEnv` class, which provides the environment for the agent to interact with.
+To learn about the configuration objects used to specify the behavior of the environment,
+see the [environment configuration reference page](env_config.md).
+
 ::: sweagent.environment.swe_env.SWEEnv
     options:
       allow_inspection: false

docs/reference/model_config.md

@@ -18,6 +18,7 @@ In most cases, you will want to use the `GenericAPIModelConfig` object.
     options:
         heading_level: 3
 
+
 ## Manual models for testing
 
 The following two models allow you to test your environment by prompting you for actions.
@@ -27,12 +28,28 @@ This can also be very useful to create your first [demonstrations](../config/dem
     options:
         heading_level: 3
 
+::: sweagent.agent.models.HumanModelConfig
+    options:
+        heading_level: 3
+
 ::: sweagent.agent.models.HumanThoughtModel
     options:
         heading_level: 3
 
+::: sweagent.agent.models.HumanThoughtModelConfig
+    options:
+        heading_level: 3
+
 ## Replay model for testing and demonstrations
 
 ::: sweagent.agent.models.ReplayModel
     options:
         heading_level: 3
+
+::: sweagent.agent.models.ReplayModelConfig
+    options:
+        heading_level: 3
+
+::: sweagent.agent.models.InstantEmptySubmitModelConfig
+    options:
+        heading_level: 3

docs/reference/parsers.md

@@ -1,3 +1,5 @@
 # Action parsers
 
+Action parsers interpret the output of the LM and return actions (tool calls/commands to execute) and thoughts (any other output of the LM, e.g., justifying the tool calls).
+
 ::: sweagent.tools.parsing

docs/reference/run_batch_config.md

@@ -1 +1,5 @@
+# Batch run configuration
+
+This page documents the configuration options for running SWE-agent in batch mode on multiple problems.
+
 ::: sweagent.run.run_batch.RunBatchConfig

docs/reference/run_single_config.md

@@ -1,3 +1,7 @@
+# Single run configuration
+
+This page documents the configuration options for running SWE-agent on a single problem.
+
 ::: sweagent.run.run_single.RunSingleConfig
 
 ::: sweagent.run.run_single.RunSingleActionConfig

docs/reference/template_config.md

@@ -1,3 +1,7 @@
 # Template configuration
 
+This page documents the template configuration used by SWE-agent to define message templates and formatting.
+
+Templates are used to format inputs and outputs into prompts/messages to query the LM.
+
 ::: sweagent.agent.agents.TemplateConfig

docs/reference/tools_config.md

@@ -5,7 +5,7 @@ This shows how to configure tools for SWE-agent.
 !!! note "Tool configuration"
 
     This is the page for configuring tools for SWE-agent, not for setting up the tools that are being used for the agent.
-    For the latter, see [tool bundles](./bundle_config.md).
+    For the latter, see [tool bundles](bundle_config.md).
 
 ::: sweagent.tools.tools.ToolConfig