How to Create a ReadTheDocs Page
Description
Documentation is often 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 ReadTheDocs, 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
, andgit 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.
- Click on the
- 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.
- Here you can specify:
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
orpull 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 be added.
Tools and resources
- ReadTheDocs: Automatically hosts and rebuilds documentation.
- Sphinx: For generating documentation from reStructuredText files.
- MkDocs: A lightweight static site generator that uses Markdown.
- GitHub: Hosts repositories with built-in CI for documentation updates.
- GitLab: Offers CI/CD pipelines for automated builds.
References
Related pages
Tools and resources on this page
Skip national tools tableNational resources
Tools and resources tailored to users in different countries.
Contributors