Add doc style guide and make docs adhere to it (#5983)

Co-authored-by: Engel Nyst <[email protected]>

docs/DOC_STYLE_GUIDE.md

@@ -0,0 +1,48 @@
+# Documentation Style Guide
+
+## General Writing Principles
+
+- **Clarity & Conciseness**: Always prioritize clarity and brevity. Avoid unnecessary jargon or overly complex explanations.
+Keep sentences short and to the point.
+- **Gradual Complexity**: Start with the simplest, most basic setup, and then gradually introduce more advanced
+concepts and configurations.
+
+## Formatting Guidelines
+
+### Headers
+
+Use **Title Case** for the first and second level headers.
+
+Example:
+  - **Basic Usage**
+  - **Advanced Configuration Options**
+
+### Lists
+
+When listing items or options, use bullet points to enhance readability.
+
+Example:
+  - Option A
+  - Option B
+  - Option C
+
+### Procedures
+
+For instructions or processes that need to be followed in a specific order, use numbered steps.
+
+Example:
+  1. Step one: Do this.
+  2. Step two: Complete this action.
+  3. Step three: Verify the result.
+
+### Code Blocks
+
+* Use code blocks for multi-line inputs, outputs, commands and code samples.
+
+Example:
+```bash
+docker run -it \
+    -e THIS=this \
+    -e THAT=that
+    ...
+```

docs/modules/usage/about.md

@@ -4,22 +4,24 @@
 
 Achieving full replication of production-grade applications with LLMs is a complex endeavor. Our strategy involves:
 
-1. **Core Technical Research:** Focusing on foundational research to understand and improve the technical aspects of code generation and handling
-2. **Specialist Abilities:** Enhancing the effectiveness of core components through data curation, training methods, and more
-3. **Task Planning:** Developing capabilities for bug detection, codebase management, and optimization
-4. **Evaluation:** Establishing comprehensive evaluation metrics to better understand and improve our models
+- **Core Technical Research:** Focusing on foundational research to understand and improve the technical aspects of code generation and handling.
+- **Task Planning:** Developing capabilities for bug detection, codebase management, and optimization.
+- **Evaluation:** Establishing comprehensive evaluation metrics to better understand and improve our agents.
 
 ## Default Agent
 
 Our default Agent is currently the [CodeActAgent](agents), which is capable of generating code and handling files.
 
 ## Built With
 
-OpenHands is built using a combination of powerful frameworks and libraries, providing a robust foundation for its development. Here are the key technologies used in the project:
+OpenHands is built using a combination of powerful frameworks and libraries, providing a robust foundation for its
+development. Here are the key technologies used in the project:
 
 ![FastAPI](https://img.shields.io/badge/FastAPI-black?style=for-the-badge) ![uvicorn](https://img.shields.io/badge/uvicorn-black?style=for-the-badge) ![LiteLLM](https://img.shields.io/badge/LiteLLM-black?style=for-the-badge) ![Docker](https://img.shields.io/badge/Docker-black?style=for-the-badge) ![Ruff](https://img.shields.io/badge/Ruff-black?style=for-the-badge) ![MyPy](https://img.shields.io/badge/MyPy-black?style=for-the-badge) ![LlamaIndex](https://img.shields.io/badge/LlamaIndex-black?style=for-the-badge) ![React](https://img.shields.io/badge/React-black?style=for-the-badge)
 
-Please note that the selection of these technologies is in progress, and additional technologies may be added or existing ones may be removed as the project evolves. We strive to adopt the most suitable and efficient tools to enhance the capabilities of OpenHands.
+Please note that the selection of these technologies is in progress, and additional technologies may be added or
+existing ones may be removed as the project evolves. We strive to adopt the most suitable and efficient tools to
+enhance the capabilities of OpenHands.
 
 ## License
 

docs/modules/usage/configuration-options.md

@@ -11,7 +11,7 @@ take precedence.
 
 # Table of Contents
 
-1. [Core Configuration](#core-configuration)
+- [Core Configuration](#core-configuration)
    - [API Keys](#api-keys)
    - [Workspace](#workspace)
    - [Debugging and Logging](#debugging-and-logging)
@@ -21,7 +21,7 @@ take precedence.
    - [Task Management](#task-management)
    - [Sandbox Configuration](#sandbox-configuration)
    - [Miscellaneous](#miscellaneous)
-2. [LLM Configuration](#llm-configuration)
+- [LLM Configuration](#llm-configuration)
    - [AWS Credentials](#aws-credentials)
    - [API Configuration](#api-configuration)
    - [Custom LLM Provider](#custom-llm-provider)
@@ -30,20 +30,20 @@ take precedence.
    - [Model Selection](#model-selection)
    - [Retrying](#retrying)
    - [Advanced Options](#advanced-options)
-3. [Agent Configuration](#agent-configuration)
+- [Agent Configuration](#agent-configuration)
    - [Microagent Configuration](#microagent-configuration)
    - [Memory Configuration](#memory-configuration)
    - [LLM Configuration](#llm-configuration-2)
    - [ActionSpace Configuration](#actionspace-configuration)
    - [Microagent Usage](#microagent-usage)
-4. [Sandbox Configuration](#sandbox-configuration-2)
+- [Sandbox Configuration](#sandbox-configuration)
    - [Execution](#execution)
    - [Container Image](#container-image)
    - [Networking](#networking)
    - [Linting and Plugins](#linting-and-plugins)
    - [Dependencies and Environment](#dependencies-and-environment)
    - [Evaluation](#evaluation)
-5. [Security Configuration](#security-configuration)
+- [Security Configuration](#security-configuration)
    - [Confirmation Mode](#confirmation-mode)
    - [Security Analyzer](#security-analyzer)
 

docs/modules/usage/feedback.md

@@ -1,10 +1,14 @@
 # ✅ Providing Feedback
 
-When using OpenHands, you will encounter cases where things work well, and others where they don't. We encourage you to provide feedback when you use OpenHands to help give feedback to the development team, and perhaps more importantly, create an open corpus of coding agent training examples -- Share-OpenHands!
+When using OpenHands, you will encounter cases where things work well, and others where they don't. We encourage you to
+provide feedback when you use OpenHands to help give feedback to the development team, and perhaps more importantly,
+create an open corpus of coding agent training examples -- Share-OpenHands!
 
 ## 📝 How to Provide Feedback
 
-Providing feedback is easy! When you are using OpenHands, you can press the thumbs-up or thumbs-down button at any point during your interaction. You will be prompted to provide your email address (e.g. so we can contact you if we want to ask any follow-up questions), and you can choose whether you want to provide feedback publicly or privately.
+Providing feedback is easy! When you are using OpenHands, you can press the thumbs-up or thumbs-down button at any point
+during your interaction. You will be prompted to provide your email address
+(e.g. so we can contact you if we want to ask any follow-up questions), and you can choose whether you want to provide feedback publicly or privately.
 
 <iframe width="560" height="315" src="https://www.youtube.com/embed/5rFx-StMVV0?si=svo7xzp6LhGK_GXr" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
@@ -14,8 +18,11 @@ Providing feedback is easy! When you are using OpenHands, you can press the thum
 
 When you submit data, you can submit it either publicly or privately.
 
-* **Public** data will be distributed under the MIT License, like OpenHands itself, and can be used by the community to train and test models. Obviously, feedback that you can make public will be more valuable for the community as a whole, so when you are not dealing with sensitive information, we would encourage you to choose this option!
-* **Private** data will only be shared with the OpenHands team for the purpose of improving OpenHands.
+- **Public** data will be distributed under the MIT License, like OpenHands itself, and can be used by the community to
+train and test models. Obviously, feedback that you can make public will be more valuable for the community as a whole,
+so when you are not dealing with sensitive information, we would encourage you to choose this option!
+- **Private** data will be made available to the OpenHands team for the purpose of improving OpenHands.
+However, a link with a unique ID will still be created that you can share publicly with others.
 
 ### Who collects and stores the data?
 
@@ -27,13 +34,17 @@ The public data will be released when we hit fixed milestones, such as 1,000 pub
 At this time, we will follow the following release process:
 
 1. All people who contributed public feedback will receive an email describing the data release and being given an opportunity to opt out.
-2. The person or people in charge of the data release will perform quality control of the data, removing low-quality feedback, removing email submitter email addresses, and attempting to remove any sensitive information.
+2. The person or people in charge of the data release will perform quality control of the data, removing low-quality feedback,
+removing email submitter email addresses, and attempting to remove any sensitive information.
 3. The data will be released publicly under the MIT license through commonly used sites such as github or Hugging Face.
 
 ### What if I want my data deleted?
 
 For data on the All Hands AI servers, we are happy to delete it at request:
 
-**One Piece of Data:** If you want one piece of data deleted, we will shortly be adding a mechanism to delete pieces of data using the link and password that is displayed on the interface when you submit data.
+**One Piece of Data:** If you want one piece of data deleted, we will shortly be adding a mechanism to delete pieces of
+data using the link and password that is displayed on the interface when you submit data.
 
-**All Data:** If you would like all pieces of your data deleted, or you do not have the ID and password that you received when submitting the data, please contact `[email protected]` from the email address that you registered when you originally submitted the data.
+**All Data:** If you would like all pieces of your data deleted, or you do not have the ID and password that you
+received when submitting the data, please contact `[email protected]` from the email address that you registered
+when you originally submitted the data.

docs/modules/usage/getting-started.mdx

@@ -44,7 +44,7 @@ For example, we might build a TODO app:
 
 We can keep iterating on the app once the skeleton is there:
 
-> Please allow adding an optional due date to every task
+> Please allow adding an optional due date to every task.
 
 Just like with normal development, it's good to commit and push your code frequently.
 This way you can always revert back to an old state if the agent goes off track.
@@ -59,15 +59,15 @@ OpenHands can also do a great job adding new code to an existing code base.
 
 For example, you can ask OpenHands to add a new GitHub action to your project
 which lints your code. OpenHands may take a peek at your codebase to see what language
-it should use, but then it can just drop a new file into `./github/workflows/lint.yml`
+it should use and then drop a new file into `./github/workflows/lint.yml`.
 
-> Please add a GitHub action that lints the code in this repository
+> Please add a GitHub action that lints the code in this repository.
 
 Some tasks might require a bit more context. While OpenHands can use `ls` and `grep`
 to search through your codebase, providing context up front allows it to move faster,
 and more accurately. And it'll cost you fewer tokens!
 
-> Please modify ./backend/api/routes.js to add a new route that returns a list of all tasks
+> Please modify ./backend/api/routes.js to add a new route that returns a list of all tasks.
 
 > Please add a new React component that displays a list of Widgets to the ./frontend/components
 > directory. It should use the existing Widget component.
@@ -78,34 +78,34 @@ OpenHands does great at refactoring existing code, especially in small chunks.
 You probably don't want to try rearchitecting your whole codebase, but breaking up
 long files and functions, renaming variables, etc. tend to work very well.
 
-> Please rename all the single-letter variables in ./app.go
+> Please rename all the single-letter variables in ./app.go.
 
-> Please break the function `build_and_deploy_widgets` into two functions, `build_widgets` and `deploy_widgets` in widget.php
+> Please break the function `build_and_deploy_widgets` into two functions, `build_widgets` and `deploy_widgets` in widget.php.
 
-> Please break ./api/routes.js into separate files for each route
+> Please break ./api/routes.js into separate files for each route.
 
 ## Bug Fixes
 
-OpenHands can also help you track down and fix bugs in your code. But, as any
+OpenHands can also help you track down and fix bugs in your code. But as any
 developer knows, bug fixing can be extremely tricky, and often OpenHands will need more context.
 It helps if you've diagnosed the bug, but want OpenHands to figure out the logic.
 
 > Currently the email field in the `/subscribe` endpoint is rejecting .io domains. Please fix this.
 
 > The `search_widgets` function in ./app.py is doing a case-sensitive search. Please make it case-insensitive.
 
-It often helps to do test-driven development when bugfixing with an agent.
+It often helps to do test-driven development when bug fixing with an agent.
 You can ask the agent to write a new test, and then iterate until it fixes the bug:
 
 > The `hello` function crashes on the empty string. Please write a test that reproduces this bug, then fix the code so it passes.
 
 ## More
 
-OpenHands is capable of helping out on just about any coding task. But it takes some practice
+OpenHands is capable of helping out on just about any coding task but it takes some practice
 to get the most out of it. Remember to:
-* Keep your tasks small
-* Be as specific as possible
-* Provide as much context as possible
-* Commit and push frequently
+* Keep your tasks small.
+* Be as specific as possible.
+* Provide as much context as possible.
+* Commit and push frequently.
 
 See [Prompting Best Practices](./prompting/prompting-best-practices) for more tips on how to get the most out of OpenHands.

docs/modules/usage/how-to/cli-mode.md

@@ -26,9 +26,9 @@ To run OpenHands in CLI mode with Docker:
 
 1. Set the following environmental variables in your terminal:
 
-* `WORKSPACE_BASE` to the directory you want OpenHands to edit (Ex: `export WORKSPACE_BASE=$(pwd)/workspace`).
-* `LLM_MODEL` to the model to use (Ex: `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`).
-* `LLM_API_KEY` to the API key (Ex: `export LLM_API_KEY="sk_test_12345"`).
+- `WORKSPACE_BASE` to the directory you want OpenHands to edit (Ex: `export WORKSPACE_BASE=$(pwd)/workspace`).
+- `LLM_MODEL` to the model to use (Ex: `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`).
+- `LLM_API_KEY` to the API key (Ex: `export LLM_API_KEY="sk_test_12345"`).
 
 2. Run the following Docker command:
 

docs/modules/usage/how-to/custom-sandbox-guide.md

@@ -9,8 +9,8 @@ as python and Node.js but may need other software installed by default.
 
 You have two options for customization:
 
-1. Use an existing image with the required software.
-2. Create your own custom Docker image.
+- Use an existing image with the required software.
+- Create your own custom Docker image.
 
 If you choose the first option, you can skip the `Create Your Docker Image` section.
 
@@ -58,7 +58,3 @@ sandbox_base_container_image="custom-image"
 ### Run
 
 Run OpenHands by running ```make run``` in the top level directory.
-
-## Technical Explanation
-
-Please refer to [custom docker image section of the runtime documentation](https://docs.all-hands.dev/modules/usage/architecture/runtime#advanced-how-openhands-builds-and-maintains-od-runtime-images) for more details.

docs/modules/usage/how-to/github-action.md

@@ -21,10 +21,10 @@ the [README for the OpenHands Resolver](https://github.com/All-Hands-AI/OpenHand
 ### Iterative resolution
 
 1. Create an issue in the repository.
-2. Add the `fix-me` label to the issue, or leave a comment starting with `@openhands-agent`
-3. Review the attempt to resolve the issue by checking the pull request
-4. Follow up with feedback through general comments, review comments, or inline thread comments
-5. Add the `fix-me` label to the pull request, or address a specific comment by starting with `@openhands-agent`
+2. Add the `fix-me` label to the issue, or leave a comment starting with `@openhands-agent`.
+3. Review the attempt to resolve the issue by checking the pull request.
+4. Follow up with feedback through general comments, review comments, or inline thread comments.
+5. Add the `fix-me` label to the pull request, or address a specific comment by starting with `@openhands-agent`.
 
 ### Label versus Macro