ReadTheDocs

Read the docs is a simple yet powerful tool for creating effective online technical documentation. It's used by many large projects, for example the MITgcm documentation is moving to RTD. Getting started with documentation on RTD is straightforward, and it integrates seamlessly with git. This means your documentation can be version controlled alongside your code base. No more excuses for out of date documentation!

This page will not go through setting up Markdown or Sphinx documentation with ReadTheDocs. The Getting started guide is a great resource. For an example of Markdown documentation, see the gcmpy docs and code repo. This page will provide some tips about integrating RTD with the UW fluids gitlab group (see Git page for more detail on this group).

Caution: the instructions here rely on making your repository public. Only proceed if this is okay for your project!

Integrating with gitlab

It is relatively easy to integrate RTD with your code base on the gitlab group. Navigate to your repository home, click into the settings menu (gear icon in top left), and go to Edit Project. Change the Visibility Level to Public and change Feature Visibility --> Repository to "Everyone with access".

If you are creating a new project on RTD, specify the gitlab project URL when it asks for a URL to import from. If you are modifying an existing RTD project (for instance, moving from a GitHub repo to the group GitLab), navigate to Admin --> Settings --> Repository URL and put in your gitlab project URL.

Adding a webhook

You might have to add your own webhook. This triggers your online docs to update when you push to the git repository.

On RTD, navigate to Admin --> Integrations and select "Add integration". Choose "GitLab incoming webhook" from the drop-down menu. Follow the link it gives you, and copy the URL when the page loads.

Go to your GitLab repo, and from the drop-down settings menu choose Webhooks. Paste the URL into the URL box, and leave the other settings as they are. Select "Add webhook". That should be it!

Now commit some changes to your docs, and go to your RTD project page. You should see it rebuilding your documentation like magic. If everything builds, you're done! Now any time you update your repo, your online docs will update.

If this doesn't work, RTD has some helpful troubleshooting tips. Navigate to the webhook you added on RTD, and you should see a link to help documentation. Good luck!