chore: update docs again (#77)

.github/workflows/deploy_docs.yaml

@@ -0,0 +1,36 @@
+name: Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - main  # Trigger deployment on pushes to main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.x'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install mkdocs mkdocs-material
+
+    - name: Build the documentation
+      run: mkdocs build
+
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./site

CONTRIBUTING.md

@@ -2,7 +2,6 @@
 
 <p>
 <a href="#prerequisites">Prerequisites</a> •
-<a href="#evaluations">Evaluations</a> •
 <a href="#developing-and-testing">Developing and testing</a> •
 <a href="#building-from-source">Building from source</a> •
 <a href="#developing-goose-plugins">Developing goose-plugins</a> •
@@ -37,7 +36,7 @@ Plugins added directly to Goose are subject to rigorous review. This is because
 
 Plugins in `goose-plugins` undergo less detailed reviews and are more modular or experimental. They can prove their value through usage or iteration over time and may be eventually moved over to Goose.
 
-To see how to add a toolkit, see the [toolkits documentation][toolkits].
+To see how to add a toolkit, see the [toolkits documentation][adding-toolkit].
 
 ### Running tests
 ```sh
@@ -123,4 +122,4 @@ This project follows the [Conventional Commits](https://www.conventionalcommits.
 [uv]: https://docs.astral.sh/uv/
 [ruff]: https://docs.astral.sh/ruff/
 [just]: https://github.com/casey/just
-[toolkits]: docs/docs/toolkits.md
+[adding-toolkit]: https://square.github.io/goose/configuration.html#adding-a-toolkit

README.md

@@ -144,15 +144,17 @@ file is meant to provide additional context about your project. The context can
 user-specific or at the project level in which case, you
 can commit it to git. `.goosehints` file is Jinja templated so you could have something
 like this:
+
 ```
 Here is an overview of how to contribute:
-{% include 'CONTRIBUTING.md' %}
+{% include 'CONTRIBUTING.md' %}
 
 The following justfile shows our common commands:
-```just
-{% include 'justfile' %}
+{% include 'justfile' %}
 ```
 
+
+
 ### Examples
 #### provider as `anthropic`
 

docs/configuration.md

@@ -1,47 +1,5 @@
 # Configuring Goose
 
-## Adding a toolkit
-To make a toolkit available to Goose, add it to your project's pyproject.toml. For example in the Goose pyproject.toml file:
-```
-[project.entry-points."goose.toolkit"]
-developer = "goose.toolkit.developer:Developer"
-github = "goose.toolkit.github:Github"
-# Add a line like this - the key becomes the name used in profiles
-my-new-toolkit = "goose.toolkit.my_toolkits:MyNewToolkit"  # this is the path to the class that implements the toolkit
-```
-
-Then to set up a profile that uses it, add something to `~/.config/goose/profiles.yaml`:
-```yaml
-my-profile:
-  provider: openai
-  processor: gpt-4o
-  accelerator: gpt-4o-mini
-  moderator: passive
-  toolkits:  # new toolkit gets added here
-    - developer
-    - my-new-toolkit
-```
-
-And now you can run Goose with this new profile to use the new toolkit!
-
-```sh
-goose session start --profile my-profile
-```
-
-Or, if you're developing a new toolkit and want to test it:
-```sh
-uv run goose session start --profile my-profile
-```
-
-## Tuning it to your repo
-
-Goose ships with the ability to read in the contents of a file named `.goosehints` from your repo. If you find yourself repeating the same information across sessions to Goose, this file is the right place to add this information.
-
-This file will be read into the Goose system prompt if it is present in the current working directory.
-
-> [!NOTE] 
-> `.goosehints` follows [jinja templating rules][jinja-guide] in case you want to leverage templating to insert file contents or variables.
-
 ## Profiles
 
 If you need to customize goose, one way is via editing: `~/.config/goose/profiles.yaml`.
@@ -146,3 +104,46 @@ unit-test-gen:
 ```
 
 [jinja-guide]: https://jinja.palletsprojects.com/en/3.1.x/
+
+
+## Adding a toolkit
+To make a toolkit available to Goose, add it to your project's pyproject.toml. For example in the Goose pyproject.toml file:
+```
+[project.entry-points."goose.toolkit"]
+developer = "goose.toolkit.developer:Developer"
+github = "goose.toolkit.github:Github"
+# Add a line like this - the key becomes the name used in profiles
+my-new-toolkit = "goose.toolkit.my_toolkits:MyNewToolkit"  # this is the path to the class that implements the toolkit
+```
+
+Then to set up a profile that uses it, add something to `~/.config/goose/profiles.yaml`:
+```yaml
+my-profile:
+  provider: openai
+  processor: gpt-4o
+  accelerator: gpt-4o-mini
+  moderator: passive
+  toolkits:  # new toolkit gets added here
+    - developer
+    - my-new-toolkit
+```
+
+And now you can run Goose with this new profile to use the new toolkit!
+
+```sh
+goose session start --profile my-profile
+```
+
+Or, if you're developing a new toolkit and want to test it:
+```sh
+uv run goose session start --profile my-profile
+```
+
+## Tuning Goose to your repo
+
+Goose ships with the ability to read in the contents of a file named `.goosehints` from your repo. If you find yourself repeating the same information across sessions to Goose, this file is the right place to add this information.
+
+This file will be read into the Goose system prompt if it is present in the current working directory.
+
+> [!NOTE] 
+> `.goosehints` follows [jinja templating rules][jinja-guide] in case you want to leverage templating to insert file contents or variables.

docs/contributing.md

@@ -0,0 +1 @@
+../CONTRIBUTING.md

docs/docs/contributing.md

@@ -1 +0,0 @@
-../../CONTRIBUTING.md

docs/docs/index.md

@@ -1,18 +0,0 @@
-# Goose
-
-Github: [`square/goose`][square/goose]
-
-
-### goose
-* PyPi package name: [`goose-ai`][goose-ai]
-* GitHub: [square/goose]
-
-### exchange
-* PyPi package name: [`ai-exchange`][ai-exchange]
-* GitHub: [square/exchange]
-
-[goose-ai]: https://pypi.org/project/goose-ai/
-[square/goose]: https://github.com/square/goose
-[ai-exchange]: https://pypi.org/project/ai-exchange/
-[square/exchange]: https://github.com/square/exchange
-[install]: installation.md

docs/docs/providers.md

@@ -1,3 +0,0 @@
-# Providers
-
-Providers in Goose mean "LLM providers" that Goose can interact with. Providers are defined in the Exchange library for the most part, but you can define your own. 

docs/docs/tips.md

@@ -1,20 +0,0 @@
-## tips
-
-Here are some collected tips we have for working efficiently with `goose`
-
-- **`goose` can and will edit files**. Use a git strategy to avoid losing anything - such as staging your
-personal edits and leaving `goose` edits unstaged until reviewed. Or consider using individual commits which can be reverted.
-- **`goose` can and will run commands**. You can ask it to check with you first if you are concerned. It will check commands for safety as well.
-- You can interrupt `goose` with `CTRL+C` to correct it or give it more info.
-- `goose` works best when solving concrete problems - experiment with how far you need to break that problem
-down to get `goose` to solve it. Be specific! E.g. it will likely fail to `"create a banking app"`,
-but probably does a good job if prompted with `"create a Fastapi app with an endpoint for deposit and withdrawal and with account balances stored in mysql keyed by id"`
-- If `goose` doesn't have enough context to start with, it might go down the wrong direction. Tell it
-to read files that you are referring to or search for objects in code. Even better, ask it to summarize
-them for you, which will help it set up its own next steps.
-- Refer to any objects in files with something that is easy to search for, such as `"the MyExample class"
-- `goose` *loves* to know how to run tests to get a feedback loop going, just like you do. If you tell it how you test things locally and quickly, it can make use of that when working on your project
-- You can use `goose` for tasks that would require scripting at times, even looking at your screen and correcting designs/helping you fix bugs, try asking it to help you in a way you would ask a person.
-- `goose` will make mistakes, and go in the wrong direction from times, feel free to correct it, or start again.
-- You can tell `goose` to run things for you continuously (and it will iterate, try, retry) but you can also tell it to check with you before doing things (and then later on tell it to go off on its own and do its best to solve).
-- `goose` can run anywhere, doesn't have to be in a repo, just ask it!

docs/docs/toolkits.md

@@ -1,202 +0,0 @@
-# Toolkits
-
-This page contains information about building and using toolkits in Goose. Toolkits are a way to extend Goose's capabilities by adding new tools and functionalities. You can create your own toolkits or use the existing ones provided by Goose.
-
-## Using Toolkits
-
-Use `goose toolkit list` to list the available toolkits.
-
-### Toolkits defined in Goose
-
-Using Goose with toolkits is simple. You can add toolkits to your profile in the `profiles.yaml` file. Here's an example of how to add `my-toolkit` toolkit to your profile:
-
-```yaml
-my-profile:
-  provider: openai
-  processor: gpt-4o
-  accelerator: gpt-4o-mini
-  moderator: passive
-  toolkits:
-    - my-toolkit
-```
-
-Then run Goose with the specified profile:
-
-```sh
-goose session start --profile my-profile
-```
-
-### Toolkits defined in Goose Plugins
-
-1. First make sure that `goose-plugins` is intalled with Goose:
-```sh
-pipx install goose-ai --preinstall goose-plugins
-```
-2. Update the `profiles.yaml` file to include the desired toolkit:
-```yaml
-my-profile:
-  provider: openai
-  processor: gpt-4o
-  accelerator: gpt-4o-mini
-  moderator: passive
-  toolkits:
-    - my-goose-plugins-toolkit
-```
-
-## Building a Toolkit
-
-To add a toolkit, in your code (which doesn't necessarily need to be in the Goose package thanks to [plugin metadata][plugin]!), create a class that derives from the `Toolkit` class.
-
-### Example toolkit class
-Below is an example of a simple toolkit called `Demo` that derives from the `Toolkit` class. This toolkit provides an `authenticate` tool that outputs an authentication code for a user. It also provides system instructions for the model. 
-```python
-import os
-import platform
-
-from goose.toolkit.base import Toolkit, tool
-
-
-class Demo(Toolkit):
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-
-    # Provide any additional tools as needed!
-    # The docstring of the tool provides instructions to the LLM, so they are important to tune
-    # you do not have to provide any tools, but any function decorated with @tool will be available
-    @tool
-    def authenticate(self, user: str):
-        """Output an authentication code for this user
-
-        Args:
-            user (str): The username to authenticate for
-        """
-        # notifier supports any rich renderable https://rich.readthedocs.io/en/stable/introduction.html#quick-start
-        self.notifier.log(f"[bold red]auth: {str(hash(user))}[/]")
-
-    # Provide any system instructions for the model
-    # This can be generated dynamically, and is run at startup time
-    def system(self) -> str:
-        print("new")
-        return f"""**You must preceed your first message by using the authenticate tool for the current user**
-
-        ```
-        platform: {platform.system()}
-        cwd: {os.getcwd()}
-        user: {os.environ.get('USER')}
-        ```
-        """
-```
-
-### Exposing the new toolkit to Goose
-
-To make the toolkit available, add it to the `pyproject.toml` file and then update your `profiles.yaml` file.
-
-#### Update the `pyproject.toml` file
-If you're adding the new toolkit to Goose or the Goose Plugins repo, simply find the `[project.entry-points."goose.toolkit"]` section in `pyproject.toml` and add a line like this:
-```toml
-[project.entry-points."goose.toolkit"]
-developer = "goose.toolkit.developer:Developer"
-github = "goose.toolkit.github:Github"
-# Add a line like this - the key becomes the name used in profiles
-demo = "goose.toolkit.demo:Demo"
-```
-
-If you are adding the toolkit to a different package, see the docs for `goose-plugins` for more information on how to create a plugins repository that can be used by Goose.
-
-#### Update the `profiles.yaml` file
-And then to set up a profile that uses it, add something to ~/.config/goose/profiles.yaml
-```yaml
-default:
-  provider: openai
-  processor: gpt-4o
-  accelerator: gpt-4o-mini
-  moderator: passive
-  toolkits:
-    - name: developer
-      requires: {}
-demo:
-  provider: openai
-  processor: gpt-4o
-  accelerator: gpt-4o-mini
-  moderator: passive
-  toolkits:
-    - developer
-    - demo
-```
-
-And now you can run goose with this new profile to use the new toolkit!
-
-```sh
-goose session start --profile demo
-```
-
-> [!NOTE]
-> If you're using a plugin from `goose-plugins`, make sure `goose-plugins` is installed in your environment. You can install it via pip: 
-> 
-> `pipx install goose-ai --preinstall goose-plugins`
-
-## Available Toolkits in Goose
-
-To see the available toolkits to you, run `goose toolkit list`, this will show the toolkits defined below as well as any other Goose modules you have installed (for example, `goose-plugins`).
-
-Goose provides a variety of toolkits designed to help developers with different tasks. Here's an overview of each available toolkit and its functionalities:
-
-### 1. Developer Toolkit
-
-The **Developer** toolkit offers general-purpose development capabilities, including:
-
-- **System Configuration Details:** Retrieves system configuration details.
-- **Task Management:** Update the plan by overwriting all current tasks.
-- **File Operations:**
-    - `patch_file`: Patch a file by replacing specific content.
-    - `read_file`: Read the content of a specified file.
-    - `write_file`: Write content to a specified file.
-- **Shell Command Execution:** Execute shell commands with safety checks.
-
-### 2. GitHub Toolkit
-
-The **GitHub** toolkit provides detailed configuration and procedural guidelines for GitHub operations.
-
-### 3. Lint Toolkit
-
-The **Lint** toolkit ensures that all toolkits have proper documentation. It performs the following checks:
-
-- Toolkit must have a docstring.
-- The first line of the docstring should contain more than 5 words and fewer than 12 words.
-- The first letter of the docstring should be capitalized.
-
-### 4. RepoContext Toolkit
-
-The **RepoContext** toolkit provides context about the current repository. It includes:
-
-- **Repository Size:** Get the size of the repository.
-- **Monorepo Check:** Determine if the repository is a monorepo.
-- **Project Summarization:** Summarize the current project based on the repository or the current project directory.
-
-### 5. Screen Toolkit
-
-The **Screen** toolkit assists users in taking screenshots for debugging or designing purposes. It provides:
-
-- **Take Screenshot:** Capture a screenshot and provide the path to the screenshot file.
-- **System Instructions:** Instructions on how to work with screenshots.
-
-### 6. SummarizeRepo Toolkit
-
-The **SummarizeRepo** toolkit helps in summarizing a repository. It includes:
-
-- **Summarize Repository:** Clone the repository (if not already cloned) and summarize the files based on specified extensions.
-
-### 7. SummarizeProject Toolkit
-
-The **SummarizeProject** toolkit generates or retrieves a summary of a project directory based on specified file extensions. It includes:
-
-- **Get Project Summary:** Generate or retrieve a summary of the project in the specified directory.
-
-### 8. SummarizeFile Toolkit
-
-The **SummarizeFile** toolkit helps in summarizing a specific file. It includes:
-
-- **Summarize File:** Summarize the contents of a specified file with optional instructions.
-
-[plugin]: https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/#using-package-metadata
-[goose-plugins]: https://github.com/square/goose-plugins

docs/guidance/applications.md

@@ -0,0 +1,15 @@
+## Uses of Goose so Far
+
+We've been using Goose to help us with a variety of tasks. Here are some examples:
+
+- Conduct code migrations like:
+    - Ember to React
+    - Ruby to Kotlin
+    - Prefect-1 to Prefect-2
+- Dive into a new project in an unfamiliar coding language
+- Transition a code-base from field-based injection to constructor-based injection in a dependency injection framework
+- Conduct performance benchmarks for a build command using a build automation tool
+- Increasing code coverage above a specific threshold
+- Scaffolding an API for data retention
+- Creating Datadog monitors
+- Removing or adding feature flags

docs/guidance/getting-started.md

@@ -0,0 +1,140 @@
+# Your first run with Goose
+
+This page contains two sections that will help you get started with Goose:
+
+1. [Configuring Goose with the `profiles.yaml` file](#configuring-goose-with-the-profilesyaml-file): how to set up Goose with the right LLMs and toolkits.
+2. [Working with Goose](#working-with-goose): how to guide Goose through a task, and how to provide context for Goose to work with.
+
+## Configuring Goose with the `profiles.yaml` file
+On the first run, Goose will detect what LLMs are available from your environment, and generate a configuration file at `~/.config/goose/profiles.yaml`. You can edit those profiles to further configure goose. 
+
+Here’s what the default `profiles.yaml` could look like if Goose detects an OpenAI API key:
+
+```yaml
+default:
+  provider: openai
+  processor: gpt-4o
+  accelerator: gpt-4o-mini
+  moderator: truncate
+  toolkits:
+    - name: developer
+      requires: {}
+```
+
+You can edit this configuration file to use different LLMs and toolkits in Goose. Check out the [configuration docs][configuration] to better understand the different fields of the `profiles.yaml` file! You can add new profiles with different settings to change how goose works from one section to the next - use `goose session start --profile {profile}` to select which to use.
+
+### LLM provider access setup
+
+Goose works on top of LLMs.  You'll need to configure one before using it. By default, Goose uses `openai` as the LLM provider but you can customize it as needed. You need to set OPENAI_API_KEY as an environment variable if you would like to use `openai`.
+
+To learn more about providers and modes of access, check out the [provider docs][providers].
+```sh
+export OPENAI_API_KEY=your_open_api_key
+```
+
+## Working with Goose
+
+Goose works best with some amount of context or instructions for a given task. You can guide goose through gathering the context it needs by giving it instructions or asking it to explore with its tools. But to make this easier, context in Goose can be extended a few additional ways:
+
+1. User-directed input
+2. A `.goosehints` file
+3. Toolkits
+4. Plans
+
+### User-directed input
+
+Directing Goose to read a specific file before requesting changes ensures that the file's contents are loaded into its operational context. Similarly, asking Goose to summarize the current project before initiating changes across multiple files provides a detailed overview of the project structure, including the locations of specific classes, functions, and other components.
+
+### `.goosehints`
+
+If you are using the `developer` toolkit, `goose` adds the content from `.goosehints` file in the working directory to the system prompt. The hints file is meant to provide additional context about your project. The context can be user-specific or at the project level in which case, you can commit it to git. `.goosehints` file is Jinja templated so you could have something like this:
+
+```
+Here is an overview of how to contribute:
+{% include 'CONTRIBUTING.md' %}
+
+The following justfile shows our common commands:
+{% include 'justfile' %}
+
+Write all code comments in French
+```
+
+### Toolkits
+
+Toolkits expand Goose’s capabilities and tailor its functionality to specific development tasks. Toolkits provide Goose with additional contextual information and interactive abilities, allowing for a more comprehensive and efficient workflow. 
+
+Here are some out-of-the-box examples:
+
+* `developer`: for general-purpose development capabilities, including plan management, shell execution, and file operations, with default shell strategies like using ripgrep.
+* `screen`: for letting goose take a look at your screen to help debug or work on designs (gives goose eyes)
+* `github`: for suggestions on how to use Github
+* `repo_context`: for summarizing and understanding a repository you are working in.
+* `jira`: for working with JIRA (issues, backlogs, tasks, bugs etc.)
+
+You can see the current toolkits available to Goose [here][available-toolkits]. There's also a [public plugins repository where toolkits are defined][goose-plugins] for Goose that has toolkits you can try out.
+
+### Plans
+
+Goose creates plans for itself to execute to achieve its goals. In some cases, you may already have a plan in mind for Goose — this is where you can define your own `plan.md` file, and it will set the first message and also hard code Goose's initial plan.
+
+The plan.md file can be text in any format and uses `jinja` templating, and the last group of lines that start with “-” will be considered the plan.
+
+Here are some examples:
+
+#### Basic example plan
+
+```md
+Your goal is to refactor this fastapi application to use a sqlite database. Use `pytest -s -v -x` to run the tests when needed. 
+
+- Use ripgrep to find the fastapi app and its tests in this directory
+- read the files you found
+- Add sqlalchemy and alembic as dependencies with poetry
+- Run alembic init to set up the basic configuration
+- Add sqlite dependency with Poetry
+- Create new module for database code and include sqlalchemy and alembic setup 
+- Define an accounts table with SQLAlchemy
+- Implement CRUD operations for accounts table  
+- Update main.py to integrate with SQLite database and use CRUD operation
+- Use alembic to create the table
+- Use conftest to set up a test database with a new DB URL
+- Run existing test suite and ensure all tests pass. Do not edit the test case behavior, instead use tests to find issues.
+```
+
+The starting plan is specified with the tasks. Each list entry is a different step in the plan. This is a pretty detailed set of tasks, but is really just a break-down of the conversation we had in the previous section. 
+
+The kickoff message is what gets set as the first user message when goose starts running (with the plan). This message should contain the overall goal of the tasks and could also contain extra context you want to include for this problem. In our case, we are just mentioning the test command we want to use to run the tests.
+
+To run Goose with this plan:
+
+``` sh
+goose session start --plan plan.md
+```
+
+#### Injecting arguments into a plan
+
+You can also inject arguments into your plan. `plan.md` files can be templated with `jinja` and can include variables that are passed in when you start the session.
+
+The kickoff message gives Goose directions to use poetry and a dependency, and then a plan is to open a file, run a test, and set up a repo:
+
+```md
+Here is the python repo
+
+- use {{ dep }}
+- use poetry
+
+Here is the plan:
+
+- Open a file
+- Run a test
+- Set up {{ repo }}
+```
+
+To run Goose with this plan with the arguments `dep=pytest,repo=github`, you would run the following command:
+
+```sh
+goose session start --plan plan.md --args dep=pytest,repo=github
+```
+
+[configuration]: ../configuration.md
+[available-toolkits]: ../plugins/available-toolkits.md
+[providers]: ../plugins/providers.md

docs/guidance/tips.md

@@ -0,0 +1,20 @@
+##  Tips for working with Goose:
+
+Here are some collected tips we have for working efficiently with Goose
+
+- **Goose can and will edit files**. Use a git strategy to avoid losing anything - such as staging your
+personal edits and leaving Goose edits unstaged until reviewed. Or consider using individual commits which can be reverted.
+- **Goose can and will run commands**. You can ask it to check with you first if you are concerned. It will check commands for safety as well.
+- You can interrupt Goose with `CTRL+C` to correct it or give it more info.
+- Goose works best when solving concrete problems - experiment with how far you need to break that problem
+down to get Goose to solve it. Be specific! E.g. it will likely fail to `"create a banking app"`,
+but probably does a good job if prompted with `"create a Fastapi app with an endpoint for deposit and withdrawal and with account balances stored in mysql keyed by id"`
+- If Goose doesn't have enough context to start with, it might go down the wrong direction. Tell it
+to read files that you are referring to or search for objects in code. Even better, ask it to summarize
+them for you, which will help it set up its own next steps.
+- Refer to any objects in files with something that is easy to search for, such as `"the MyExample class"
+- Goose *loves* to know how to run tests to get a feedback loop going, just like you do. If you tell it how you test things locally and quickly, it can make use of that when working on your project
+- You can use Goose for tasks that would require scripting at times, even looking at your screen and correcting designs/helping you fix bugs, try asking it to help you in a way you would ask a person.
+- Goose will make mistakes, and go in the wrong direction from times, feel free to correct it, or start again.
+- You can tell Goose to run things for you continuously (and it will iterate, try, retry) but you can also tell it to check with you before doing things (and then later on tell it to go off on its own and do its best to solve).
+- Goose can run anywhere, doesn't have to be in a repo, just ask it!

docs/index.md

@@ -0,0 +1 @@
+../README.md

docs/plugins/providers.md

@@ -0,0 +1,14 @@
+# Providers
+
+Providers in Goose mean "LLM providers" that Goose can interact with. Providers are defined in the [Exchange library][exchange-providers] for the most part, but you can define your own. 
+
+**Currently available providers:**
+
+* Anthropic
+* Azure
+* Bedrock
+* Databricks
+* Ollama
+* OpenAI
+
+[exchange-providers]: https://github.com/square/exchange/tree/main/src/exchange/providers

docs/reference/goose/build.md

@@ -0,0 +1 @@
+::: goose.build

docs/reference/goose/cli/config.md

@@ -0,0 +1 @@
+::: goose.cli.config

docs/reference/goose/cli/index.md

@@ -0,0 +1 @@
+::: goose.cli

docs/reference/goose/cli/main.md

@@ -0,0 +1 @@
+::: goose.cli.main

docs/reference/goose/cli/prompt/completer.md

@@ -0,0 +1 @@
+::: goose.cli.prompt.completer

docs/reference/goose/cli/prompt/create.md

@@ -0,0 +1 @@
+::: goose.cli.prompt.create

docs/reference/goose/cli/prompt/goose_prompt_session.md

@@ -0,0 +1 @@
+::: goose.cli.prompt.goose_prompt_session

docs/reference/goose/cli/prompt/index.md

@@ -0,0 +1 @@
+::: goose.cli.prompt

docs/reference/goose/cli/prompt/lexer.md

@@ -0,0 +1 @@
+::: goose.cli.prompt.lexer

docs/reference/goose/cli/prompt/prompt_validator.md

@@ -0,0 +1 @@
+::: goose.cli.prompt.prompt_validator

docs/reference/goose/cli/prompt/user_input.md

@@ -0,0 +1 @@
+::: goose.cli.prompt.user_input

docs/reference/goose/cli/session.md

@@ -0,0 +1 @@
+::: goose.cli.session

docs/reference/goose/command/base.md

@@ -0,0 +1 @@
+::: goose.command.base

docs/reference/goose/command/file.md

@@ -0,0 +1 @@
+::: goose.command.file

docs/reference/goose/command/index.md

@@ -0,0 +1 @@
+::: goose.command

docs/reference/goose/index.md

@@ -0,0 +1 @@
+::: goose

docs/reference/goose/notifier.md

@@ -0,0 +1 @@
+::: goose.notifier

docs/reference/goose/profile.md

@@ -0,0 +1 @@
+::: goose.profile

docs/reference/goose/toolkit/base.md

@@ -0,0 +1 @@
+::: goose.toolkit.base

docs/reference/goose/toolkit/developer.md

@@ -0,0 +1 @@
+::: goose.toolkit.developer

docs/reference/goose/toolkit/github.md

@@ -0,0 +1 @@
+::: goose.toolkit.github

docs/reference/goose/toolkit/index.md

@@ -0,0 +1 @@
+::: goose.toolkit

docs/reference/goose/toolkit/lint.md

@@ -0,0 +1 @@
+::: goose.toolkit.lint

docs/reference/goose/toolkit/repo_context/index.md

@@ -0,0 +1 @@
+::: goose.toolkit.repo_context

docs/reference/goose/toolkit/repo_context/repo_context.md

@@ -0,0 +1 @@
+::: goose.toolkit.repo_context.repo_context

docs/reference/goose/toolkit/repo_context/utils.md

@@ -0,0 +1 @@
+::: goose.toolkit.repo_context.utils

docs/reference/goose/toolkit/screen.md

@@ -0,0 +1 @@
+::: goose.toolkit.screen

docs/reference/goose/toolkit/summarization/index.md

@@ -0,0 +1 @@
+::: goose.toolkit.summarization

docs/reference/goose/toolkit/summarization/summarize_file.md

@@ -0,0 +1 @@
+::: goose.toolkit.summarization.summarize_file

docs/reference/goose/toolkit/summarization/summarize_project.md

@@ -0,0 +1 @@
+::: goose.toolkit.summarization.summarize_project

docs/reference/goose/toolkit/summarization/summarize_repo.md

@@ -0,0 +1 @@
+::: goose.toolkit.summarization.summarize_repo

docs/reference/goose/toolkit/summarization/utils.md

@@ -0,0 +1 @@
+::: goose.toolkit.summarization.utils

docs/reference/goose/toolkit/utils.md

@@ -0,0 +1 @@
+::: goose.toolkit.utils

docs/reference/goose/utils/ask.md

@@ -0,0 +1 @@
+::: goose.utils.ask

docs/reference/goose/utils/check_shell_command.md

@@ -0,0 +1 @@
+::: goose.utils.check_shell_command

docs/reference/goose/utils/diff.md

@@ -0,0 +1 @@
+::: goose.utils.diff

docs/reference/goose/utils/file_utils.md

@@ -0,0 +1 @@
+::: goose.utils.file_utils

docs/reference/goose/utils/index.md

@@ -0,0 +1 @@
+::: goose.utils

docs/reference/goose/utils/session_file.md

@@ -0,0 +1 @@
+::: goose.utils.session_file

docs/reference/goose/view.md

@@ -0,0 +1 @@
+::: goose.view

docs/reference/index.md

@@ -0,0 +1,39 @@
+# Reference Documentation
+
+## Goose
+- [goose.build](goose/build.md)
+- [goose.notifier](goose/notifier.md)
+- [goose.profile](goose/profile.md)
+- [goose.view](goose/view.md)
+
+## Command
+- [goose.command.base](goose/command/base.md)
+- [goose.command.file](goose/command/file.md)
+
+## CLI
+- [goose.cli.config](goose/cli/config.md)
+- [goose.cli.main](goose/cli/main.md)
+- [goose.cli.prompt.create](goose/cli/prompt/create.md)
+- [goose.cli.prompt.goose_prompt_session](goose/cli/prompt/goose_prompt_session.md)
+- [goose.cli.session](goose/cli/session.md)
+
+## Toolkits
+ [goose.toolkit.base](goose/toolkit/base.md)
+- [goose.toolkit.developer](goose/toolkit/developer.md)
+- [goose.toolkit.github](goose/toolkit/github.md)
+- [goose.toolkit.repo_context.repo_context](goose/toolkit/repo_context/repo_context.md)
+- [goose.toolkit.repo_context.utils](goose/toolkit/repo_context/utils.md)
+- [goose.toolkit.screen](goose/toolkit/screen.md)
+- [goose.toolkit.summarization.summarize_file](goose/toolkit/summarization/summarize_file.md)
+- [goose.toolkit.summarization.summarize_project](goose/toolkit/summarization/summarize_project.md)
+- [goose.toolkit.summarization.summarize_repo](goose/toolkit/summarization/summarize_repo.md)
+- [goose.toolkit.summarization.utils](goose/toolkit/summarization/utils.md)
+- [goose.toolkit.utils](goose/toolkit/utils.md)
+
+## Utils
+- [goose.utils](goose/utils/index.md)
+- [goose.utils.ask](goose/utils/ask.md)
+- [goose.utils.check_shell_command](goose/utils/check_shell_command.md)
+- [goose.utils.diff](goose/utils/diff.md)
+- [goose.utils.file_utils](goose/utils/file_utils.md)
+- [goose.utils.session_file](goose/utils/session_file.md)

docs/scripts/gen_ref_pages.py

@@ -1,5 +1,3 @@
-"""Generate the code reference pages and navigation."""
-
 from pathlib import Path
 
 import mkdocs_gen_files
@@ -9,9 +7,16 @@ nav = mkdocs_gen_files.Nav()
 root = Path(__file__).parent.parent.parent
 src = root / "src"
 
+# Collecting all modules for the index page
+module_links = []
+core_modules = []
+toolkit_modules = []
+utils_modules = []
+
 for path in sorted(src.rglob("*.py")):
-    module_path = path.relative_to(src).with_suffix("")
-    doc_path = path.relative_to(src).with_suffix(".md")
+    module_path = path.relative_to(src).with_suffix("")  # Removes the '.py' suffix
+    doc_path = path.relative_to(src).with_suffix(".md")  # Creates .md path
+
     full_doc_path = Path("reference", doc_path)
 
     parts = tuple(module_path.parts)
@@ -23,13 +28,41 @@ for path in sorted(src.rglob("*.py")):
     elif parts[-1] == "__main__":
         continue
 
-    nav[parts] = doc_path.as_posix()
+    # Construct a dynamic identifier based on module path
+    ident = ".".join(parts)
 
+    # Organize modules into categories
+    if "toolkit" in ident:
+        toolkit_modules.append(f"- [{ident}]({doc_path})")
+    elif "utils" in ident:
+        utils_modules.append(f"- [{ident}]({doc_path})")
+    else:
+        core_modules.append(f"- [{ident}]({doc_path})")
+
+    # Generate the markdown file for each module
     with mkdocs_gen_files.open(full_doc_path, "w") as fd:
-        ident = ".".join(parts)
         fd.write(f"::: {ident}")
 
-    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
+    nav[parts] = doc_path.as_posix()
 
+# Write the enhanced SUMMARY.md with categories
 with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
-    nav_file.writelines(nav.build_literate_nav())
+    nav_file.write("# Reference Documentation Summary\n\n")
+
+    nav_file.write("## Core Modules\n")
+    nav_file.write("\n".join(core_modules) + "\n\n")
+
+    nav_file.write("## Toolkit Modules\n")
+    nav_file.write("\n".join(toolkit_modules) + "\n\n")
+
+    nav_file.write("## Utility Modules\n")
+    nav_file.write("\n".join(utils_modules) + "\n\n")
+
+# Create an index.md file for the reference section
+with mkdocs_gen_files.open("reference/index.md", "w") as index_file:
+    index_file.write("# Reference Documentation\n\n")
+    index_file.write("Welcome to the reference documentation for the project's Python modules.\n\n")
+    index_file.write("Below is a list of available modules:\n\n")
+    index_file.write("\n".join(core_modules + toolkit_modules + utils_modules))
+
+

justfile

@@ -17,7 +17,8 @@ coverage *FLAGS:
   uv run coverage lcov -o lcov.info
 
 docs:
-  cd docs && uv sync && uv run mkdocs serve
+  uv sync && uv run mkdocs serve
+
 
 ai-exchange-version:
   curl -s https://pypi.org/pypi/ai-exchange/json | jq -r .info.version

mkdocs.yml

@@ -1,10 +1,13 @@
 site_name: Goose Documentation
 site_author: Block
 site_description: Documentation for Goose
-repo_url: https://github.com/square/goose
+repo_url: https://github.com/block-open-source/goose
 repo_name: "square/goose"
-edit_uri: "https://github.com/square/goose/blob/main/docs/docs/"
-# site_url: https://goose-docs.squarecloudservices.com
+edit_uri: "https://github.com/block-open-source/goose/blob/main/docs/"
+site_url: 'https://block-open-source.github.io/goose/'
+use_directory_urls: false
+
+# theme
 theme:
   name: material
   features:
@@ -36,14 +39,29 @@ theme:
   favicon: assets/logo.ico
   icon:
     logo: assets/logo.ico
+
+# plugins
 plugins:
   - include-markdown
   - callouts
   - glightbox
+  - mkdocstrings:
+        handlers:
+          python:
+            setup_commands:
+              - "import sys; sys.path.append('src')"  # Add src folder to Python path
   - search:
       separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
   - redirects:
       redirect_maps:
+  - git-committers:  # Show git committers
+      branch: main
+      enabled: !ENV [ ENV_PROD, false ]
+      repository: square/goose
+  - git-revision-date-localized:  # Show git revision date
+      enable_creation_date: true
+      enabled: !ENV [ ENV_PROD, false ]
+
 extra:
   annotate:
     json:
@@ -52,6 +70,7 @@ extra:
   analytics:
     provider: google
     property: !ENV GOOGLE_ANALYTICS_KEY
+
 markdown_extensions:
   - abbr
   - admonition
@@ -92,19 +111,26 @@ markdown_extensions:
   - pymdownx.tilde
   - toc:
       permalink: true
+
 nav:
   - Home: index.md
   - 'Installation': installation.md
-  - 'Configuration': configuration.md
   - 'Contributing': contributing.md
+  - Guidance:
+      - 'Getting Started': guidance/getting-started.md
+      - 'Quick Tips': guidance/tips.md
+      - 'Applications of Goose': guidance/applications.md
   - Plugins:
-    - 'Overview': plugins.md
+    - 'Overview': plugins/plugins.md
     - Toolkits:
-        - 'Using Toolkits': using-toolkits.md
-        - 'Creating a New Toolkit': creating-a-new-toolkit.md
-        - 'Available Toolkits': available-toolkits.md
+        - 'Using Toolkits': plugins/using-toolkits.md
+        - 'Creating a New Toolkit': plugins/creating-a-new-toolkit.md
+        - 'Available Toolkits': plugins/available-toolkits.md
     - CLI Commands:
-        - 'Available CLI Commands': cli.md
+        - 'Available CLI Commands': plugins/cli.md
     - Providers:
-        - 'Available Providers': providers.md
-  - 'Tips': tips.md
+        - 'Available Providers': plugins/providers.md
+  - Advanced:
+      - Configuration: configuration.md
+  - 'Reference':
+      - 'API Docs': reference/index.md

pyproject.toml

@@ -61,4 +61,7 @@ dev-dependencies = [
     "mkdocs-redirects>=1.2.1",
     "mkdocs-include-markdown-plugin>=6.2.2",
     "mkdocs-callouts>=1.14.0",
+    "mkdocs-git-authors-plugin>=0.9.0",
+    "mkdocs-git-revision-date-localized-plugin>=1.2.9",
+    "mkdocs-git-committers-plugin>=0.2.3",
 ]