448fd740df
This adds a Documentation for connecting Codeberg to [Read the Docs](https://readthedocs.org/). English is not my native Language, so there may be a few things that could be written better. Co-authored-by: René Wagner <rwa@clttr.info> Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/289 Co-authored-by: JakobDev <jakobdev@gmx.de> Co-committed-by: JakobDev <jakobdev@gmx.de>
83 lines
4.8 KiB
Markdown
83 lines
4.8 KiB
Markdown
---
|
|
eleventyNavigation:
|
|
key: Read the Docs Integration
|
|
title: Integrating with Read the Docs
|
|
parent: Integrations
|
|
---
|
|
|
|
This article will guide you through integrating Codeberg with [Read the Docs](https://readthedocs.org/) to allow automatic build of your documentation. It will show you how to connect Read the Docs to a Git repository hosted on Codeberg. To learn how Read the Docs works, take a look at the [official Documentation](https://docs.readthedocs.io).
|
|
|
|
> Gitea/Forgejo is currenly not official supported by Read the Docs, so this may break in the future.
|
|
|
|
## Registration
|
|
|
|
If you do not have an account yet, you must sign up with [readthedocs first](https://readthedocs.org/accounts/signup/).
|
|
|
|
After sign-up you need to login with your user to access your [dashboard](https://readthedocs.org/dashboard/).
|
|
|
|
## Create new Project
|
|
This steps shows how to create a new project on Read the Docs
|
|
|
|
1. On the [Read the Docs dashboard](https://readthedocs.org/dashboard/) click "Import a Project"
|
|
2. If you have connected Read the Docs with some provider e.g. GitHub, you see a list of your repos at that provider. Ignore it and click "Import Manually". You should see this screen:
|
|
|
|
<picture>
|
|
<source srcset="/assets/images/integrations/read-the-docs/import-manual.webp" type="image/webp">
|
|
<img src="/assets/images/integrations/read-the-docs/import-manual.png" alt="Image of the Import Manual page">
|
|
</picture>
|
|
|
|
1. Under "Name" enter the name of your project. Under "Repository URL" enter the Git URL of your repo. It has the form `https://codeberg.org/<owner>/<repo>.git`. Leave the rest as it is and click "Next"
|
|
2. You should now be on your Project page and see a warning that the project doesn't have a valid Webhook. Ignore that. Go to Admin->Integrations. You should see this screen:
|
|
|
|
<picture>
|
|
<source srcset="/assets/images/integrations/read-the-docs/admin-integrations.webp" type="image/webp">
|
|
<img src="/assets/images/integrations/read-the-docs/admin-integrations.png" alt="Image of an admin website of a Read the docs project.
|
|
The integrations section of the admin page is selected.
|
|
The content of the Integrations sections states, that 'No integrations are currently configured.'.
|
|
An error message is shown in red saying that the project does not have a valid webhook set up.">
|
|
</picture>
|
|
|
|
5. Now click on "Add Integration" and select "GitHub incoming webhook" as type. You should see this screen:
|
|
|
|
<picture>
|
|
<source srcset="/assets/images/integrations/read-the-docs/github-integration.webp" type="image/webp">
|
|
<img src="/assets/images/integrations/read-the-docs/github-integration.png" alt="Image of an admin website of a Read the docs project.
|
|
The integrations section of the admin page is selected.
|
|
The page content start with a header saying 'Integration - GitHub incoming webhook'.
|
|
After some explaining text an url specific to the Read the docs project is shown which can be used to manually configure this webhook.
|
|
The url shown is marked with a red border.">
|
|
</picture>
|
|
|
|
6. Copy the URL that is marked Red in the Image. You should keep it secret, as it allows pushing to your Documentation
|
|
7. Now go to the "Webhooks" Section of the settings of your Codeberg Repo. Create a new "Forgejo" Webhook
|
|
|
|
<picture>
|
|
<source srcset="/assets/images/integrations/read-the-docs/forgejo-webhook.webp" type="image/webp">
|
|
<img src="/assets/images/integrations/read-the-docs/forgejo-webhook.png" alt="Image of a Forgejo repository configuration.
|
|
The tab 'Webhooks' is selected.
|
|
The button 'Add Webhook' has been clicked and presents a list of possible Webhooks integrations.
|
|
The 'Forgejo' entry in the list has been marked with a red border.">
|
|
</picture>
|
|
|
|
8. Under "Target URL" enter the URL you copied from the Read the Docs webhook
|
|
9. Under "Trigger On:" select "All Events"
|
|
|
|
<picture>
|
|
<source srcset="/assets/images/integrations/read-the-docs/add-webhook.webp" type="image/webp">
|
|
<img src="/assets/images/integrations/read-the-docs/add-webhook.png" alt="Image of the Forgejo 'Add Webhook' dialog.
|
|
The input field for 'Target URL' is marked with a red border.
|
|
Also the 'All Events' checkout below the 'Trigger On' section is marked with a red border.">
|
|
</picture>
|
|
|
|
Congratulation! Your done! To test it, push a commit in your Codeberg Repo and see if the documentation rebuilds. This may take a few minutes.
|
|
|
|
## Migrate Project
|
|
You may migrate a repo that is connected to Read the Docs from another git forge to Codeberg. In this case, follow these steps:
|
|
|
|
1. Go to Admin->Settings of your Project on Read the Docs
|
|
2. Under "Repository URL" enter the Git URL of your Codeberg Repo
|
|
3. Now go to "Integrations". You will see a existing Integration
|
|
4. Click on it to open the Settings of the Integration
|
|
5. Now click on "Delete Webhook"
|
|
6. Jump to Step 5 of the "Create new project" section and follow the steps there
|