Read the Docs

What does Read the Docs do?

  • a service that hosts sphinx documentation

  • all public repositories are free

  • a framework for starting your own documentation server

So here you can find step by step instructions how to publish your documentation using Read the Docs.

Setup Read the Docs

  1. Go to https://readthedocs.org/ and create an account.

  2. Log in and click on your user-name in the upper right corner.

  3. Click on Import a Project

  4. Something Manual

  5. Then fill the following form

../_images/import_project.png

  1. Click on next.

Now you successfully introduced Read the Docs to your repository. On the next page you see two important things.

On the one hand you can try to build your documentation and on the other hand we did not establish a webhook so far. Let us start with the build.

Build Documentation

For the build your repository needs to be public. In case it is already public please continue here.

  1. Open your repository https://git.tu-berlin.de/your/repo/url in the browser

  2. In the bottom left corner click on settings

  3. Scroll down to the section Visibility, project features, permissions

  4. Click on the Expand button

  5. Underneath the heading Project Visibility use the drop down menue to choose Public

  6. Scroll down and click save changes

Now your repository can be seen by everybody in the internet, in particular by the Read the Docs service, so we can start building the documentation.

  1. Open https://readthedocs.org/ in your browser and log in

  2. Click on your user-name in the upper right corner.

  3. Click on your project name

  4. Click on the Build Version button

  5. Wait for the build to succeed. It should look like this

../_images/build_completed.png

  1. On the right hand side please click on the button View docs.

Add Webhook

Now we want our documentation to be updated automatically, once a Merge Request is merged. Therefore we will add a webhook to the repository.

  1. Open https://readthedocs.org/ in your browser and log in

  2. Click on your user-name in the upper right corner.

  3. Click on your project name

  4. Click on the Admin button

  5. In the navigation on the left hand side click on Integrations

  6. Click on the button Add integration

  7. In the pull down menue select GitLab incoming webhook and click on the Add integration button

  8. Now right click on the link that you see and that starts with readthedocs.org/api/v2/webhook/... to copy it

  9. Go back to your repository https://git.tu-berlin.de/your/repo/url

  10. Click on Settings>Webhooks

  11. Copy the webhook URL to the URL field

  12. Scroll down and click on Add webhook.