Skip to content

Commit 4de6c78

Browse files
mamoodienyst
andauthored
Add doc style guide and make docs adhere to it (OpenHands#5983)
Co-authored-by: Engel Nyst <[email protected]>
1 parent 9fef6f9 commit 4de6c78

21 files changed

Lines changed: 277 additions & 218 deletions

docs/DOC_STYLE_GUIDE.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Documentation Style Guide
2+
3+
## General Writing Principles
4+
5+
- **Clarity & Conciseness**: Always prioritize clarity and brevity. Avoid unnecessary jargon or overly complex explanations.
6+
Keep sentences short and to the point.
7+
- **Gradual Complexity**: Start with the simplest, most basic setup, and then gradually introduce more advanced
8+
concepts and configurations.
9+
10+
## Formatting Guidelines
11+
12+
### Headers
13+
14+
Use **Title Case** for the first and second level headers.
15+
16+
Example:
17+
- **Basic Usage**
18+
- **Advanced Configuration Options**
19+
20+
### Lists
21+
22+
When listing items or options, use bullet points to enhance readability.
23+
24+
Example:
25+
- Option A
26+
- Option B
27+
- Option C
28+
29+
### Procedures
30+
31+
For instructions or processes that need to be followed in a specific order, use numbered steps.
32+
33+
Example:
34+
1. Step one: Do this.
35+
2. Step two: Complete this action.
36+
3. Step three: Verify the result.
37+
38+
### Code Blocks
39+
40+
* Use code blocks for multi-line inputs, outputs, commands and code samples.
41+
42+
Example:
43+
```bash
44+
docker run -it \
45+
-e THIS=this \
46+
-e THAT=that
47+
...
48+
```

docs/modules/usage/about.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,24 @@
44

55
Achieving full replication of production-grade applications with LLMs is a complex endeavor. Our strategy involves:
66

7-
1. **Core Technical Research:** Focusing on foundational research to understand and improve the technical aspects of code generation and handling
8-
2. **Specialist Abilities:** Enhancing the effectiveness of core components through data curation, training methods, and more
9-
3. **Task Planning:** Developing capabilities for bug detection, codebase management, and optimization
10-
4. **Evaluation:** Establishing comprehensive evaluation metrics to better understand and improve our models
7+
- **Core Technical Research:** Focusing on foundational research to understand and improve the technical aspects of code generation and handling.
8+
- **Task Planning:** Developing capabilities for bug detection, codebase management, and optimization.
9+
- **Evaluation:** Establishing comprehensive evaluation metrics to better understand and improve our agents.
1110

1211
## Default Agent
1312

1413
Our default Agent is currently the [CodeActAgent](agents), which is capable of generating code and handling files.
1514

1615
## Built With
1716

18-
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:
17+
OpenHands is built using a combination of powerful frameworks and libraries, providing a robust foundation for its
18+
development. Here are the key technologies used in the project:
1919

2020
![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)
2121

22-
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.
22+
Please note that the selection of these technologies is in progress, and additional technologies may be added or
23+
existing ones may be removed as the project evolves. We strive to adopt the most suitable and efficient tools to
24+
enhance the capabilities of OpenHands.
2325

2426
## License
2527

docs/modules/usage/configuration-options.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ take precedence.
1111

1212
# Table of Contents
1313

14-
1. [Core Configuration](#core-configuration)
14+
- [Core Configuration](#core-configuration)
1515
- [API Keys](#api-keys)
1616
- [Workspace](#workspace)
1717
- [Debugging and Logging](#debugging-and-logging)
@@ -21,7 +21,7 @@ take precedence.
2121
- [Task Management](#task-management)
2222
- [Sandbox Configuration](#sandbox-configuration)
2323
- [Miscellaneous](#miscellaneous)
24-
2. [LLM Configuration](#llm-configuration)
24+
- [LLM Configuration](#llm-configuration)
2525
- [AWS Credentials](#aws-credentials)
2626
- [API Configuration](#api-configuration)
2727
- [Custom LLM Provider](#custom-llm-provider)
@@ -30,20 +30,20 @@ take precedence.
3030
- [Model Selection](#model-selection)
3131
- [Retrying](#retrying)
3232
- [Advanced Options](#advanced-options)
33-
3. [Agent Configuration](#agent-configuration)
33+
- [Agent Configuration](#agent-configuration)
3434
- [Microagent Configuration](#microagent-configuration)
3535
- [Memory Configuration](#memory-configuration)
3636
- [LLM Configuration](#llm-configuration-2)
3737
- [ActionSpace Configuration](#actionspace-configuration)
3838
- [Microagent Usage](#microagent-usage)
39-
4. [Sandbox Configuration](#sandbox-configuration-2)
39+
- [Sandbox Configuration](#sandbox-configuration)
4040
- [Execution](#execution)
4141
- [Container Image](#container-image)
4242
- [Networking](#networking)
4343
- [Linting and Plugins](#linting-and-plugins)
4444
- [Dependencies and Environment](#dependencies-and-environment)
4545
- [Evaluation](#evaluation)
46-
5. [Security Configuration](#security-configuration)
46+
- [Security Configuration](#security-configuration)
4747
- [Confirmation Mode](#confirmation-mode)
4848
- [Security Analyzer](#security-analyzer)
4949

docs/modules/usage/feedback.md

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,14 @@
11
# ✅ Providing Feedback
22

3-
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!
3+
When using OpenHands, you will encounter cases where things work well, and others where they don't. We encourage you to
4+
provide feedback when you use OpenHands to help give feedback to the development team, and perhaps more importantly,
5+
create an open corpus of coding agent training examples -- Share-OpenHands!
46

57
## 📝 How to Provide Feedback
68

7-
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.
9+
Providing feedback is easy! When you are using OpenHands, you can press the thumbs-up or thumbs-down button at any point
10+
during your interaction. You will be prompted to provide your email address
11+
(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.
812

913
<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>
1014

@@ -14,8 +18,11 @@ Providing feedback is easy! When you are using OpenHands, you can press the thum
1418

1519
When you submit data, you can submit it either publicly or privately.
1620

17-
* **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!
18-
* **Private** data will only be shared with the OpenHands team for the purpose of improving OpenHands.
21+
- **Public** data will be distributed under the MIT License, like OpenHands itself, and can be used by the community to
22+
train and test models. Obviously, feedback that you can make public will be more valuable for the community as a whole,
23+
so when you are not dealing with sensitive information, we would encourage you to choose this option!
24+
- **Private** data will be made available to the OpenHands team for the purpose of improving OpenHands.
25+
However, a link with a unique ID will still be created that you can share publicly with others.
1926

2027
### Who collects and stores the data?
2128

@@ -27,13 +34,17 @@ The public data will be released when we hit fixed milestones, such as 1,000 pub
2734
At this time, we will follow the following release process:
2835

2936
1. All people who contributed public feedback will receive an email describing the data release and being given an opportunity to opt out.
30-
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.
37+
2. The person or people in charge of the data release will perform quality control of the data, removing low-quality feedback,
38+
removing email submitter email addresses, and attempting to remove any sensitive information.
3139
3. The data will be released publicly under the MIT license through commonly used sites such as github or Hugging Face.
3240

3341
### What if I want my data deleted?
3442

3543
For data on the All Hands AI servers, we are happy to delete it at request:
3644

37-
**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.
45+
**One Piece of Data:** If you want one piece of data deleted, we will shortly be adding a mechanism to delete pieces of
46+
data using the link and password that is displayed on the interface when you submit data.
3847

39-
**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.
48+
**All Data:** If you would like all pieces of your data deleted, or you do not have the ID and password that you
49+
received when submitting the data, please contact `[email protected]` from the email address that you registered
50+
when you originally submitted the data.

docs/modules/usage/getting-started.mdx

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ For example, we might build a TODO app:
4444
4545
We can keep iterating on the app once the skeleton is there:
4646

47-
> Please allow adding an optional due date to every task
47+
> Please allow adding an optional due date to every task.
4848
4949
Just like with normal development, it's good to commit and push your code frequently.
5050
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.
5959

6060
For example, you can ask OpenHands to add a new GitHub action to your project
6161
which lints your code. OpenHands may take a peek at your codebase to see what language
62-
it should use, but then it can just drop a new file into `./github/workflows/lint.yml`
62+
it should use and then drop a new file into `./github/workflows/lint.yml`.
6363

64-
> Please add a GitHub action that lints the code in this repository
64+
> Please add a GitHub action that lints the code in this repository.
6565
6666
Some tasks might require a bit more context. While OpenHands can use `ls` and `grep`
6767
to search through your codebase, providing context up front allows it to move faster,
6868
and more accurately. And it'll cost you fewer tokens!
6969

70-
> Please modify ./backend/api/routes.js to add a new route that returns a list of all tasks
70+
> Please modify ./backend/api/routes.js to add a new route that returns a list of all tasks.
7171
7272
> Please add a new React component that displays a list of Widgets to the ./frontend/components
7373
> directory. It should use the existing Widget component.
@@ -78,34 +78,34 @@ OpenHands does great at refactoring existing code, especially in small chunks.
7878
You probably don't want to try rearchitecting your whole codebase, but breaking up
7979
long files and functions, renaming variables, etc. tend to work very well.
8080

81-
> Please rename all the single-letter variables in ./app.go
81+
> Please rename all the single-letter variables in ./app.go.
8282
83-
> Please break the function `build_and_deploy_widgets` into two functions, `build_widgets` and `deploy_widgets` in widget.php
83+
> Please break the function `build_and_deploy_widgets` into two functions, `build_widgets` and `deploy_widgets` in widget.php.
8484
85-
> Please break ./api/routes.js into separate files for each route
85+
> Please break ./api/routes.js into separate files for each route.
8686
8787
## Bug Fixes
8888

89-
OpenHands can also help you track down and fix bugs in your code. But, as any
89+
OpenHands can also help you track down and fix bugs in your code. But as any
9090
developer knows, bug fixing can be extremely tricky, and often OpenHands will need more context.
9191
It helps if you've diagnosed the bug, but want OpenHands to figure out the logic.
9292

9393
> Currently the email field in the `/subscribe` endpoint is rejecting .io domains. Please fix this.
9494
9595
> The `search_widgets` function in ./app.py is doing a case-sensitive search. Please make it case-insensitive.
9696
97-
It often helps to do test-driven development when bugfixing with an agent.
97+
It often helps to do test-driven development when bug fixing with an agent.
9898
You can ask the agent to write a new test, and then iterate until it fixes the bug:
9999

100100
> The `hello` function crashes on the empty string. Please write a test that reproduces this bug, then fix the code so it passes.
101101
102102
## More
103103

104-
OpenHands is capable of helping out on just about any coding task. But it takes some practice
104+
OpenHands is capable of helping out on just about any coding task but it takes some practice
105105
to get the most out of it. Remember to:
106-
* Keep your tasks small
107-
* Be as specific as possible
108-
* Provide as much context as possible
109-
* Commit and push frequently
106+
* Keep your tasks small.
107+
* Be as specific as possible.
108+
* Provide as much context as possible.
109+
* Commit and push frequently.
110110

111111
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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,9 @@ To run OpenHands in CLI mode with Docker:
2626

2727
1. Set the following environmental variables in your terminal:
2828

29-
* `WORKSPACE_BASE` to the directory you want OpenHands to edit (Ex: `export WORKSPACE_BASE=$(pwd)/workspace`).
30-
* `LLM_MODEL` to the model to use (Ex: `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`).
31-
* `LLM_API_KEY` to the API key (Ex: `export LLM_API_KEY="sk_test_12345"`).
29+
- `WORKSPACE_BASE` to the directory you want OpenHands to edit (Ex: `export WORKSPACE_BASE=$(pwd)/workspace`).
30+
- `LLM_MODEL` to the model to use (Ex: `export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"`).
31+
- `LLM_API_KEY` to the API key (Ex: `export LLM_API_KEY="sk_test_12345"`).
3232

3333
2. Run the following Docker command:
3434

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

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,8 @@ as python and Node.js but may need other software installed by default.
99

1010
You have two options for customization:
1111

12-
1. Use an existing image with the required software.
13-
2. Create your own custom Docker image.
12+
- Use an existing image with the required software.
13+
- Create your own custom Docker image.
1414

1515
If you choose the first option, you can skip the `Create Your Docker Image` section.
1616

@@ -58,7 +58,3 @@ sandbox_base_container_image="custom-image"
5858
### Run
5959

6060
Run OpenHands by running ```make run``` in the top level directory.
61-
62-
## Technical Explanation
63-
64-
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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,10 @@ the [README for the OpenHands Resolver](https://github.com/All-Hands-AI/OpenHand
2121
### Iterative resolution
2222

2323
1. Create an issue in the repository.
24-
2. Add the `fix-me` label to the issue, or leave a comment starting with `@openhands-agent`
25-
3. Review the attempt to resolve the issue by checking the pull request
26-
4. Follow up with feedback through general comments, review comments, or inline thread comments
27-
5. Add the `fix-me` label to the pull request, or address a specific comment by starting with `@openhands-agent`
24+
2. Add the `fix-me` label to the issue, or leave a comment starting with `@openhands-agent`.
25+
3. Review the attempt to resolve the issue by checking the pull request.
26+
4. Follow up with feedback through general comments, review comments, or inline thread comments.
27+
5. Add the `fix-me` label to the pull request, or address a specific comment by starting with `@openhands-agent`.
2828

2929
### Label versus Macro
3030

0 commit comments

Comments
 (0)