Skip to content

Commit 822941d

Browse files
hasithasit
authored
Improve Documentation Structure and Accessibility in Markdown Files (#69)
* Major refactor - Move configure and tools to top level - Update category positions - Move images to static dir - Update links * Update image file name in introduction.md * Update sidebar positions for integrations documentation * Update category positions for documentation * Update knowledge base integration description * Update FAQ with CodeRabbit comparison and CodeRabbit's uniqueness * Update redirects in docusaurus.config.ts * Update Jira and Linear integration configuration in knowledge base * Update GitLab integration documentation
1 parent 4b20874 commit 822941d

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

65 files changed

+105
-66
lines changed

‎docs/about/features.md

+6-6
Original file line numberDiff line numberDiff line change
@@ -13,28 +13,28 @@ High-Level Summary: This offers a concise overview of the changes in the pull
1313
request. It helps the team, including those without technical expertise, to
1414
quickly understand the changes and the impact on the product.
1515

16-
![Summary Overview](./images/Summary-Overview.png)
16+
![Summary Overview](/img/about/Summary-Overview.png)
1717

1818
Walkthrough: A detailed code walkthrough to understand the changes in each file
1919
that is part of the pull request, followed by a celebratory poem about the
2020
changes.
2121

22-
![Summary Walkthrough](./images/Summary-Walkthrough.png)
22+
![Summary Walkthrough](/img/about/Summary-Walkthrough.png)
2323

2424
### 2. Code Review feedback {#code-review-feedback}
2525

2626
Review feedback is posted as review comments on the lines of the code that
2727
changed for each file. Code suggestions are given in a Diff format, which either
2828
be copied or committed within the pull request with a single click.
2929

30-
![Review Feedback](./images/ReviewFeedback.png)
30+
![Review Feedback](/img/about/ReviewFeedback.png)
3131

3232
A review status is generated for each commit that is reviewed. It displays the
3333
commit IDs that were reviewed, the files examined and ignored, as well as the
3434
additional comments generated for each review, and so on. Review status is
3535
useful for understanding the auxiliary context of the review.
3636

37-
![Review Status](./images/ReviewStatus.png)
37+
![Review Status](/img/about/ReviewStatus.png)
3838

3939
### 3. Chat with CodeRabbit {#chat-with-coderabbit}
4040

@@ -44,11 +44,11 @@ changes. Just comment on the CodeRabbit review to start the conversation.
4444
CodeRabbit learns from your interactions and gets smarter over time. The more
4545
you chat, the better it gets.
4646

47-
![Chat](./images/chat.png)
47+
![Chat](/img/about/chat.png)
4848

4949
### 4. Issue Validation {#issue-validation}
5050

5151
Pull request changes are validated against the linked GitHub or GitLab issue and
5252
identifies all other issues which might be affected by this change.
5353

54-
![Issue Validation](./images/issue-validation.png)
54+
![Issue Validation](/img/about/issue-validation.png)

‎docs/about/images/CodeRabbitFlow.png

-222 KB
Binary file not shown.

‎docs/about/pricing.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -74,15 +74,15 @@ These are the hourly usage limits for each developer per repository:
7474
- During the trial period, seat assignment is automatic, but the number of seats
7575
can be adjusted when purchasing the subscription.
7676

77-
![Seat Management](./images/cr_seat_manage_dark.png#gh-dark-mode-only)
78-
![Seat Management](./images/cr_seat_manage_light.png#gh-light-mode-only)
77+
![Seat Management](/img/about/cr_seat_manage_dark.png#gh-dark-mode-only)
78+
![Seat Management](/img/about/cr_seat_manage_light.png#gh-light-mode-only)
7979

8080
### Free Plan
8181

8282
- Seats are assigned to new developers immediately
8383

84-
![Free Seat Assignment](./images/cr_seat_free_dark.png#gh-dark-mode-only)
85-
![Free Seat Assignment](./images/cr_seat_free_light.png#gh-light-mode-only)
84+
![Free Seat Assignment](/img/about/cr_seat_free_dark.png#gh-dark-mode-only)
85+
![Free Seat Assignment](/img/about/cr_seat_free_light.png#gh-light-mode-only)
8686

8787
**Note:** The subscription is limited to human users; bot users are not
8888
supported. Thus, pull requests or merge requests created by bots will not be

‎docs/about/support.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@ Complete the support ticket by providing your name, email, a description of your
2222
issue, and attaching any necessary files. If you are reporting a bug, please
2323
provide the GitHub or GitLab organization name.
2424

25-
![Open a Ticket](./images/cr_support_help_light.png#gh-light-mode-only)
26-
![Open a Ticket](./images/cr_support_help_dark.png#gh-dark-mode-only)
25+
![Open a Ticket](/img/about/cr_support_help_light.png#gh-light-mode-only)
26+
![Open a Ticket](/img/about/cr_support_help_dark.png#gh-dark-mode-only)
2727

2828
## Email Support
2929

@@ -33,7 +33,7 @@ You can also reach out to us at
3333
:::tip
3434

3535
To see more common issues faced by CodeRabbit users, visit our
36-
[FAQ section](../faq/faq.md) for detailed answers and solutions to frequently
36+
[FAQ section](../faq.md) for detailed answers and solutions to frequently
3737
encountered problems.
3838

3939
:::

‎docs/guides/configure-coderabbit.md renamed to ‎docs/configure-coderabbit.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ description:
55
CodeRabbit offers various configuration options to tailor the reviews to your
66
specific requirements. Configuration can be made using one of the below
77
options.
8-
sidebar_position: 1
8+
sidebar_position: 3
99
---
1010

1111
```mdx-code-block

‎docs/faq/faq.md renamed to ‎docs/faq.md

+24-5
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
title: FAQs
33
sidebar_label: FAQs
44
description: Frequently asked questions about CodeRabbit.
5+
sidebar_position: 7
56
---
67

78
### General
@@ -37,15 +38,33 @@ uses proprietary code from private repositories for training purposes.
3738
Yes, you can switch between different organizations on CodeRabbit. To do so,
3839
click on the organization name in the top-left corner of the CodeRabbit UI.
3940

40-
![Switch Organizations](./images/cr_support_orgs_light.png#gh-light-mode-only)
41-
![Switch Organizations](./images/cr_support_orgs_dark.png#gh-dark-mode-only)
41+
![Switch Organizations](/img/faq/cr_support_orgs_light.png#gh-light-mode-only)
42+
![Switch Organizations](/img/faq/cr_support_orgs_dark.png#gh-dark-mode-only)
4243

4344
#### What Large Language Models does CodeRabbit use?
4445

4546
CodeRabbit currently utilizes OpenAI's `gpt-4-turbo` and `gpt-3.5-turbo`. We're
4647
researching and testing upcoming LLMs to ensure we're offering the most precise
4748
reviews possible.
4849

50+
#### How does CodeRabbit compare to other AI code generators?
51+
52+
Code reviews remain essential, whether the code is written by a human or a bot.
53+
This is mainly because the perspective of the reviewer differs from that of the
54+
code generator, whether human or machine. This distinction is precisely why
55+
human peer reviews have been effective for so long. While AI-powered
56+
code-generation tools like GitHub Copilot hold immense potential, it's important to recognize that
57+
these generators are still in their early stages and may not be equipped to
58+
auto-generate meaningful code for moderately complex applications.
59+
60+
#### How is CodeRabbit different from other code review tools?
61+
62+
Traditional code review tools excel in linting and static analysis, but they
63+
fall short in providing context-aware, conversational feedback with actionable
64+
suggestions for changes that can be directly committed. On the other hand,
65+
**CodeRabbit** leverages AI to understand the intent behind the code changes and
66+
provide human-like feedback for applying the best practices.
67+
4968
### Subscription
5069

5170
#### Can a CodeRabbit subscription be used across multiple organizations?
@@ -74,7 +93,7 @@ commit after the app is installed. You can, however, use the
7493
#### Can I customize CodeRabbit?
7594

7695
Reviews are customizable. For information, check out our
77-
[Customization](../guides/review-instructions.md) guide.
96+
[Customization](./guides/review-instructions.md) guide.
7897

7998
#### Can I choose a language other than English for the reviews?
8099

@@ -123,7 +142,7 @@ cases, we re-allow further reviews/conversations after a brief timeout.
123142

124143
#### Who can install CodeRabbit on the repositories?
125144

126-
You need to be an admin of the orgnizaation to add the repositories.
145+
You need to be an admin of the organization to add the repositories.
127146

128147
#### I can't add CodeRabbit to my GitLab Repositories. What should I do?
129148

@@ -133,6 +152,6 @@ If there are any access restrictions by domain, then you will need to add
133152
:::tip
134153

135154
If you have further questions or need additional information, please check out
136-
our [Support](../about/support.md) page for more details.
155+
our [Support](./about/support.md) page for more details.
137156

138157
:::

‎docs/guides/_category_.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
label: Guides
2-
position: 3
2+
position: 5
33
collapsible: true
44
collapsed: true

‎docs/guides/delete-account.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -43,8 +43,8 @@ upon selecting **Delete Account**. You can open the dropdowns for more
4343
information.
4444

4545
<div align="center">
46-
![Delete Account](./images/delete_account_light.png#gh-light-mode-only)
47-
![Delete Account](./images/delete_account_dark.png#gh-dark-mode-only)
46+
![Delete Account](/img/guides/delete_account_light.png#gh-light-mode-only)
47+
![Delete Account](/img/guides/delete_account_dark.png#gh-dark-mode-only)
4848
</div>
4949

5050
Deletion will only occur once the admin specifically types in "delete" in the

‎docs/guides/ondemand-reports.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Sign in to your CodeRabbit account and navigate to the [**API Keys**](https://ap
2525
Click on the **Create API Key** button and enter a name for the API Key.
2626
Copy the API key, and keep it safe as it won't be visible again.
2727

28-
![API Keys](./images/api_keys.png)
28+
![API Keys](/img/guides/api_keys.png)
2929

3030
## Generate an On-demand report
3131

‎docs/guides/review-instructions.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ sidebar_position: 3
99
---
1010

1111
The guide explains how to add custom review instructions for the entire project.
12-
Also, see the guide on how to [configure CodeRabbit](./configure-coderabbit.md).
12+
Also, see the guide on how to [configure CodeRabbit](../configure-coderabbit.md).
1313

1414
### Path-based instructions {#path-based}
1515

‎docs/guides/tools/_category_.yml

-4
This file was deleted.

‎docs/integrations/_category_.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
label: Integrations
2-
position: 4
2+
position: 6
33
collapsible: true
44
collapsed: true

‎docs/integrations/knowledge-base.md

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: External Knowledge Base
3+
description: Integrate CodeRabbit with an external knowledge base for issue tracking.
4+
sidebar_label: Knowledge Base
5+
sidebar_position: 3
6+
---
7+
8+
CodeRabbit integrates with external knowledge bases to provide a seamless experience for issue tracking. This will allow CodeRabbit to use the context from the linked issues while reviewing the code.
9+
10+
## Jira {#jira}
11+
12+
### CodeRabbit App
13+
14+
1. Navigate to [integrations][integrations] in the CodeRabbit app.
15+
2. Toggle the Jira switch to enable the integration.
16+
17+
Upon enabling the Jira integration, CodeRabbit will redirect you to the Jira login page. Enter your Jira credentials to authenticate the integration.
18+
19+
### CodeRabbit Configuration
20+
21+
1. Add Jira's Project Keys to the `knowledge_base.jira.project_keys` field in your project's CodeRabbit configuration file at `.coderabbit.yaml`.
22+
23+
## Linear {#Linear}
24+
25+
### CodeRabbit App
26+
27+
1. Navigate to [integrations][integrations] in the CodeRabbit app.
28+
2. Toggle the Linear switch to enable the integration.
29+
30+
Upon enabling the Linear integration, CodeRabbit will redirect you to the Linear login page. Enter your Linear credentials to authenticate the integration.
31+
32+
### CodeRabbit Configuration
33+
34+
1. Add Linear's Team Keys to the `knowledge_base.linear.team_keys` field in your project's CodeRabbit configuration file at `.coderabbit.yaml`.
35+
36+
[integrations]: https://app.coderabbit.ai/integrations

‎docs/integrations/saas-gitlab.md

+6-5
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
title: Integrating CodeRabbit with SaaS GitLab
33
description: Integrate CodeRabbit with SaaS GitLab.
44
sidebar_label: SaaS GitLab
5+
sidebar_position: 1
56
---
67

78
This guide will assist you in effectively integrating CodeRabbit with SaaS GitLab.
@@ -26,22 +27,22 @@ To interact with the GitLab API, a **Personal Access Token** is required. This t
2627

2728
Upon first login to the application (immediately after the onboarding screen), you will need to choose based on your organization's requirements.
2829

29-
![gitlab user modal choice](./images/gitlab_user_choice.png)
30+
![gitlab user modal choice](/img/integrations/gitlab_user_choice.png)
3031

31-
**We recommend using the default CodeRabbit user** for most organizations as it is pre-configured. However, we understand that some organizations may prefer more control over the user or have restrictions regarding user inclusion within their organization.
32+
**We recommend using the default CodeRabbit user** for most organizations, as it is pre-configured. However, we understand that some organizations may prefer more control over the user or have restrictions regarding user inclusion within their organization.
3233

3334
### Personal Access Tokens
3435

3536
If your organization opts to use another user within the organization, you can do so by [generating a personal access token](#generating-a-personal-access-token).
3637

37-
![gitlab organization user modal choice](./images/gitlab_organization_user.png)
38+
![gitlab organization user modal choice](/img/integrations/gitlab_organization_user.png)
3839

3940
#### Recommendations
4041

4142
* **Create a dedicated user for CodeRabbit** - This ensures the user is exclusively for CodeRabbit, allowing better access control.
4243
* **Use "CodeRabbit" as the username** - This makes the user easily recognizable for future reference.
4344
* **Use a dedicated email address** - This helps in easy identification and management.
44-
* **Use the CodeRabbit logo as the profile picture** - This further ensures easy recognition. You can download our logo from [here](./images/logo.svg "download").
45+
* **Use the CodeRabbit logo as the profile picture** - This further ensures easy recognition. You can download our logo from [here](/img/integrations/logo.svg "download").
4546

4647
#### Key Points to Remember
4748

@@ -66,4 +67,4 @@ GitLab provides an option to generate a personal access token for a new user. Fo
6667
9. Click "Create Personal Access Token."
6768
10. Note down the token as it will only be displayed once.
6869

69-
![Untitled](./images/admin-access-token.png)
70+
![Untitled](/img/integrations/admin-access-token.png)

‎docs/integrations/self-hosted-gitlab.md

+7-6
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
title: CodeRabbit for Self-Managed GitLab
33
description: Integrate CodeRabbit with your Self-Managed GitLab instance.
44
sidebar_label: Self-Managed GitLab
5+
sidebar_position: 2
56
---
67

78
This page guides you through the process of integrating your Self-Managed GitLab
@@ -16,23 +17,23 @@ complete, you can log in directly using the OAuth2 flow.
1617
**Visit CodeRabbit:** Visit our [Login](https://coderabbit.ai/login) page and
1718
select Self-Hosted GitLab
1819

19-
![login-page](./images/login-page.png)
20+
![login-page](/img/integrations/login-page.png)
2021

2122
### Step 2: Enter your Self-Managed GitLab URL
2223

2324
On this page, enter the URL of your self-managed GitLab instance and click
2425
submit. Once, you submit, we check our database for a record of your
2526
organization and if we find an existing one, we are starting the login process.
2627

27-
![Untitled](./images/self-hosted-gitlab-host-url.png)
28+
![Untitled](/img/integrations/self-hosted-gitlab-host-url.png)
2829

2930
If the self-managed GitLab instance is not found, we initiate the onboarding process, which can be either manual or automated.
3031

3132
### **Step 3: Onboarding Manual or Automated**
3233

3334
#### 1. Automated onboarding
3435

35-
![Untitled](./images/automated-onboarding.png)
36+
![Untitled](/img/integrations/automated-onboarding.png)
3637

3738
#### **Why do we need the Admin Access Token?**
3839

@@ -47,7 +48,7 @@ wish, as the next step.
4748
#### 2. Manual onboarding
4849

4950
For the manual onboarding process we need to create the [CodeRabbit user](#creating-coderabbit-user) and the [OAuth2 GitLab application](#creating-oauth2-application).
50-
![Untitled](./images/manual-onboarding.png)
51+
![Untitled](/img/integrations/manual-onboarding.png)
5152

5253
#### **Creating CodeRabbit user**
5354

@@ -89,14 +90,14 @@ the token, please follow the process outlined below:
8990
9. Select Create personal access token.
9091
10. Please note down this token as this will be visible one time only
9192

92-
![Untitled](./images/admin-access-token.png)
93+
![Untitled](/img/integrations/admin-access-token.png)
9394

9495
### **Step 4: Paste the details and click submit**
9596

9697
- Submit the form.
9798
- We will handle the setup process for you.
9899
- On subsequent visits, your setup will be automatically detected, allowing for
99-
direct login. ![Untitled](./images/self-hosted-page.png)
100+
direct login. ![Untitled](/img/integrations/self-hosted-page.png)
100101

101102
### **Step 5: Whitelist CodeRabbit IP address**
102103

0 commit comments

Comments
 (0)