Your tasks: Creating a 'Read the Docs' Page

How to Create a ReadTheDocs Page

Description

Documentation is an essential part of software projects. Typically, this documentation is composed of static pages generated by tools such as Sphinx or MKDocs. Platforms like GitHub or GitLab offer features to host static documentation, but a popular alternative is Read the Docs, which simplifies publishing and managing documentation. ReadTheDocs can be used independently or integrated with platforms like GitHub or GitLab, utilizing Continuous Integration (CI) to automate the build and publish process.

Considerations

• In a ReadTheDocs project you need to use a configuration file .readthedocs.yaml.
• A Git repository can be used to version control the project and a remote repository can be hosted on GitHub or GitLab.
• Tools such as Sphinx or MkDocs can be used write the static documentation pages.
• CI that is offered by GitHub and GitLab helps automating the import task. Changes can be imported on different occasions, e.g. on each push to the repository or merge to the default branch.

Solutions

Follow steps below to create a ReadTheDocs page.

1. Create a Documentation Source

To begin, you need to generate the source files for your documentation:

• Sphinx: Run sphinx-quickstart to initialize the project. This will create configuration files and folder structure for your documentation.
• MkDocs: Install MkDocs and run mkdocs new my-project to create a basic structure with Markdown files.

2. Host the Project on GitHub or GitLab

• Push the generated documentation to a remote Git repository (e.g., GitHub or GitLab). The repository will hold both your project’s code and its documentation.

Example GitHub steps:

• Create a repository on GitHub.
• Add your documentation files to the repository.
• Commit and push your changes using Git commands (git add, git commit, and git push).

3. Import Project on ReadTheDocs

• Link your GitHub or GitLab account to ReadTheDocs.
• After linking your account, return to the ReadTheDocs dashboard.
  • Click on the Import a Project button, you will see a list of repositories from your linked account. Select the repository that contains your documentation.
• Once you’ve selected your repository, you will be prompted to configure the build settings.
  • Here you can specify:
    • Project Name: This will be the name of your project on ReadTheDocs.
    • Documentation Type: Choose whether you are using Sphinx, MkDocs, or another tool.
    • Branch: Specify the branch you want to build from (commonly the main branch).
    • Environment Settings: If your project requires specific Python packages or configurations, make sure to set them up.

4. Configure ReadTheDocs with .readthedocs.yaml

After importing your project into ReadTheDocs, to manage project settings and dependencies, create a .readthedocs.yaml file in the root of your repository. This configuration file tells ReadTheDocs how to build your documentation.

4.1. Create the .readthedocs.yaml File
In the root directory of your project, create a new file named .readthedocs.yaml.

4.2. Define the Version
Start by specifying the version of the configuration file, ReadTheDocs currently uses version 2.

4.3. Specify the Python Environment (optional) If your documentation requires specific Python packages, you can define the required Python version and any dependencies.

python:
  version: 3.8  # Specify the Python version
  install:
    - requirements: requirements.txt  # Install dependencies from a requirements file

4.4 Choose a documentation builder: You need to specify which documentation tool you are using, such as Sphinx or MkDocs.

Sphinx

sphinx:
  configuration: docs/conf.py  # If using Sphinx, specify the configuration file path

Or

MKDocs

mkdocs:
  config: mkdocs.yml  # If using MkDocs, specify the config file

5. Set Up Webhooks for Automatic Builds

Integrate your project with Continuous Integration (CI) to automatically rebuild your documentation whenever changes are made:

• GitHub Actions: Set up a workflow that triggers on every push or pull request. This helps automate the process of updating the documentation whenever you make changes to the source files.

• GitLab CI/CD: Similar to GitHub, you can configure GitLab CI pipelines to handle automatic updates.

6. Customize and Build Documentation

Once imported, ReadTheDocs will automatically start building the documentation. You can further customize your documentation:

• Add custom themes, like the popular ReadTheDocs theme for Sphinx.
• Add additional build formats like PDF and ePub, if needed.

Review the build logs to ensure the documentation is generated correctly.

7. Publish and View Documentation

After a successful build, the documentation will be published and publicly accessible via ReadTheDocs at a URL similar to: https://<your-project>.readthedocs.io/.

• You can always trigger new builds from the ReadTheDocs dashboard or via new commits to your repository.

For further information, please refer to the Read the Docs tutorial. Additionally, check out our page on software documentation for more insights.

How to cite this page

TO DO.

References

• Read the Docs tutorial

Related pages

Tools and resources on this page

National resources

Tools and resources tailored to users in different countries.

Azza Gamgami

Christian Hüser

HZDR