Doc: Include code/data/output files where helpful (#556)

docs/config/config.md

@@ -75,6 +75,14 @@ In the [`config/`](https://github.com/princeton-nlp/SWE-agent/tree/main/config)
     Relative paths in config files are resolved to the `SWE_AGENT_CONFIG_ROOT` environment variable (if set)
     or the SWE-agent repository root.
 
+<details>
+<summary><code>default_from_url.yaml</code></summary>
+
+```yaml
+--8<-- "config/default_from_url.yaml"
+```
+</details>
+
 ## How a Configuration File is Processed
 Some notes on processing that occurs on config fields when SWE-agent is run:
 

docs/config/demonstrations.md

@@ -27,5 +27,6 @@ Here's how you can make a demo from an existing trajectory file (like the one cr
 3. Edit the demo by hand to make it work for your particular use case and configuration.
 4. (Optional) Run `python run_replay.py --traj_path <path to demo> --config_file <path to config file>` to execute the actions of the demo, have the system generate the execution output, and ensure that it works as expected.
 5. Inspect the resulting trajectory to ensure it was executed correctly.
+6. Specify the path to your demonstration in your [config file](config.md)
 
 {% include-markdown "../_footer.md" %}

docs/config/docker.md

@@ -9,11 +9,17 @@ There are two reasons to build your own Docker image
 
 There are three steps involved:
 
-1. Modify the [`swe.Dockerfile` Dockerfile](https://github.com/princeton-nlp/SWE-agent/blob/main/docker/swe.Dockerfile).
+1. Modify the [`swe.Dockerfile` Dockerfile](https://github.com/princeton-nlp/SWE-agent/blob/main/docker/swe.Dockerfile) (also shown below).
    We provide some extended explanation of the Dockerfile [here](https://github.com/princeton-nlp/SWE-agent/blob/main/docker/README.md).
 2. Build the image. One way is to simply run `./setup.sh`. Alternatively, especially if you want to change the default tag (`sweagent/swe-agent:latest`), run
    ```bash
    docker build -t "YOUR TAG HERE" -f docker/swe.Dockerfile \
      --build-arg TARGETARCH=$(uname -m) .
    ```
-3. Make sure you use the new image by passing the `--image_name` flag to `run.py`.
+3. Make sure you use the new image by passing the `--image_name` flag to `run.py`.
+
+Default Dockerfile:
+
+```Dockerfile
+--8<-- "docker/swe.Dockerfile"
+```

docs/installation/docker.md

@@ -21,6 +21,14 @@ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock \
   --config_file config/default_from_url.yaml  --skip_existing=False
 ```
 
+<details>
+<summary>Output</summary>
+
+```json
+--8<-- "docs/usage/cl_tutorial_cmd_1_output.log"
+```
+</details>
+
 !!! tip "Windows"
     If you're using docker on Windows, use `-v //var/run/docker.sock:/var/run/docker.sock`
     (double slash) to escape it ([more information](https://stackoverflow.com/a/47229180/)).

docs/usage/cl_tutorial.md

@@ -18,6 +18,14 @@ python run.py \
   --per_instance_cost_limit 2.00
 ```
 
+<details>
+<summary>Output</summary>
+
+```json
+--8<-- "docs/usage/cl_tutorial_cmd_1_output.log"
+```
+</details>
+
 Here,
 
 * `--model_name` sets the language model that is used by SWE-agent (with `gpt4` being the default). More information on the available models in our [FAQ](usage_faq.md)
@@ -99,11 +107,10 @@ python run.py \
 
 This time, `pip install -e .` is called before SWE-agent gets to work, installing the package defined in the repository.
 
-Let's take a look at the config file
+Let's take a look at the `py310_default.yaml` config file
 
 ```yaml
-python: '3.10'
-install: 'uv pip install -e . || (python -m pip install --upgrade pip && python -m pip install -e .)'
+--8<-- "config/environment_setup/py310_default.yaml"
 ```
 
 Here, `install` is an arbitrary command that is run, while `python` will be the required python version.

docs/usage/trajectories.md

@@ -2,6 +2,14 @@
 
 The [`trajectories/`](https://github.com/princeton-nlp/SWE-agent/tree/main/trajectories) folder is the default location that experiment results (invocations of [`run.py`](cl_tutorial.md)) will be written to.
 
+<details>
+<summary>Example trajectory</summary>
+
+```json
+--8<-- "trajectories/demonstrations/replay__marshmallow-code__marshmallow-1867__default__t-0.20__p-0.95__c-2.00__install-1___install_from_source/marshmallow-code__marshmallow-1867.traj"
+```
+</details>
+
 At a high level, the experiments folder is organized in the following manner:
 ```
 trajectories

mkdocs.yml

@@ -40,6 +40,7 @@ markdown_extensions:
   - footnotes
   - attr_list
   - md_in_html
+  - pymdownx.snippets
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg