Migration of a Restructured Text and Sphinx based Wiki to ReadTheDocs

If you have a Restructured Text (RST) and Sphinx based Wiki you can migrate it to ReadTheDocs For MoinMoin based Wikis see also the Moin2Sphinx page.

Please read the Example_projects page which describes requirements for your documentation project. You may choose the example-sphinx-basic setup.

ReadTheDocs is a Continuous Documentation Deployment platform for your software project. Every time you change something in your documentation, ReadTheDocs will detect your change and build your documentation.

Prerequisites

We assume that you already have your Wiki documentation files in a Git repository, and that these files are RST files set up to be formatted with Sphinx. For an example see the Moin2Sphinx page.

You should have (or create) a Sphinx Configuration file conf.py in the same folder as the RST files.

ReadTheDocs assumes that your documentation files all reside in your Git project sub-folder named docs. You can move your Sphinx files (including conf.py) into a docs folder with these commands:

mkdir docs
git mv conf.py docs/
git mv <your-files>.rst docs/
git commit
git push

For our desired Manual import of a Git repository to ReadTheDocs, a .readthedocs.yaml file must be added to your Git docs folder. Download the readthedocs.yaml file from the example-sphinx-basic page, for example:

cd docs/
wget https://raw.githubusercontent.com/readthedocs-examples/example-sphinx-basic/main/.readthedocs.yaml
git add .readthedocs.yaml
git commit .readthedocs.yaml
git push

This file may be good as-is without any modifications.

Login to ReadTheDocs

Go to the ReadTheDocs page and login, or sign up if you are a new user.

WARNING: Do not login with your GitHub, GitLab or Bitbucket login! If you do so, ReadTheDocs will be granted full access to your entire Git repository! For security reasons you probably do not want to allow this access! In stead, create your own personal login account.

Import a repository

When you have logged in, you can click on Import a Project (your Git project documentation) from the Dashboard page.

Now click the Import Manually button so that you do not divulge your Git login information!

In the Project Details page select carefully a suitable name for your project. Note: This name will become the DNS domain name of your documentation pages, for example, the name My nice documentation will become https://my-nice-documentation.readthedocs.io.

In the Repository URL field enter the URL of your Git project. It is the same URL which you use to make a git clone command of your code, for example:

https://github.com/OleHolmNielsen/Niflheim_system.git

If you wish to use a Git branch other than the default main branch, enter the branch name in the Default branch box.

Click Next which will take yo to the Add a project configuration file page. Note the instruction:

Make sure your project has a .readthedocs.yaml configuration file at the root directory of your repository.

Since we have already created a readthedocs.yaml file, we can click the Finish button.

Project overview

On your project’s overview page you can click the Build version button to generate the web pages. They will be published, for example, on the page https://my-nice-documentation.readthedocs.io.

When you get (hopefully) the Build completed message, click on the View docs link to go the documentation.

Add Git integration

You should integrate ReadTheDocs with your Git project by defining as Webhook where your Git project pushes a message to ReadTheDocs telling that updates exist. This causes ReadTheDocs to rebuild your documentation from the latest Git files.

First create an Integration on ReadTheDocs in your project page by clicking Admin->Integrations. Now click on Add Integration. Select the appropriate Integration type, for example, GitHub incoming webhook and click Add Integration. Since we have chosen to Import Manually, use the address given to manually configure this webhook, for example:

readthedocs.org/api/v2/webhook/xxxxxxx

Copy the Webhook address.

Next create a Webhook in your Git page. In GitHub this is in the project’s Settings->Webhooks page. Click on Add Webhook (this may require your MFA authentication). In the Payload URL box paste the above Webhook address and click the green button Add webhook.

E-mail notifications

Configure E-mail notifications to be sent on build failures in the page Admin->Email notifications.