Read the Docs: documentation simplified

Read the Docs tutorial

In this tutorial you will learn how to host a public documentation project on Read the Docs Community.

Note

Find out the differences between Read the Docs Community and Read the Docs for Business.

In the tutorial we will:

Import a Sphinx project from a GitHub repository (no prior experience with Sphinx is required).
Tailor the project’s configuration.
Explore other useful Read the Docs features.

If you don’t have a GitHub account, you’ll need to register for a free account before you start.

Preparing your repository on GitHub

Sign in to GitHub and navigate to the tutorial GitHub template.
Click the green Use this template button, then click Create a new Repository. On the new page:

Owner
Leave the default, or change it to something suitable for a tutorial project.

Repository name
Something memorable and appropriate, for example rtd-tutorial.

Visibility
Make sure the project is “Public”, rather than “Private”.
Click the green Create repository button to create a public repository that you will use in this Read the Docs tutorial, containing following files:

.readthedocs.yaml
Read the Docs configuration file. Required.

README.rst
Description of the repository.

pyproject.toml
Python project metadata that makes it installable. Useful for automatic documentation generation from sources.

lumache.py
Source code of the fictional Python library.

docs/
Directory holding all the fictional Python library documentation in reStructuredText, the Sphinx configuration docs/source/conf.py and the root document docs/source/index.rst.

Creating a Read the Docs account

To create a Read the Docs account: navigate to the Sign Up page and choose the option Sign up with GitHub. On the authorization page, click the green Authorize readthedocs button.

Note

Read the Docs needs elevated permissions to perform certain operations that ensure that the workflow is as smooth as possible, like installing webhooks. If you want to learn more, check out Permissions for connected accounts.

After that, you will be redirected to Read the Docs to confirm your e-mail and username. Click the Sign Up » button to create your account and open your dashboard.

When you have clicked the link in your email from Read the Docs to “verify your email address” and finalize the process, your Read the Docs account will be ready to create your first project.

Read the Docs empty dashboard — Welcome to your Read the Docs dashboard!

Importing the project to Read the Docs

To import your GitHub project to Read the Docs:

Click the Import a Project button on your dashboard.
Click the ➕ button to the right of your rtd-tutorial project. If the list of repositories is empty, click the 🔄 button.

Import projects workflow
Enter some details about your Read the Docs project:

Name
The name of the project, used to create a unique subdomain for each project. so it is better if you prepend your username, for example {username}-rtd-tutorial.

Repository URL
The URL that contains the documentation source. Leave the automatically filled value.

Default branch
Name of the default branch of the project, leave it as main.

Then click the Next button to create the project and open the project home.

You just created your first project on Read the Docs! 🎉

Checking the first build

Read the Docs will build your project documentation right after you create it.

To see the build logs:

Click the Your documentation is building link on the project home.
- If the build has not finished by the time you open it, you will see a spinner next to a “Installing” or “Building” indicator, meaning that it is still in progress.
- If the build has finished, you’ll see a green “Build completed” indicator, the completion date, the elapsed time, and a link to the generated documentation.
First successful documentation build
Click on View docs to see your documentation live!

HTML documentation live on Read the Docs

Note

Advertisement is one of our main sources of revenue. If you want to learn more about how do we fund our operations and explore options to go ad-free, check out our Sustainability page.

If you don’t see the ad, you might be using an ad blocker. Our EthicalAds network respects your privacy, doesn’t target you, and tries to be as unobtrusive as possible, so we would like to kindly ask you to not block us ❤️

Configuring the project

To update the project description and configure the notification settings:

Navigate back to the project page and click the ⚙ Admin button,to open the Settings page.
Update the project description by adding the following text:

Lumache (/lu’make/) is a Python library for cooks and food lovers that creates recipes mixing random ingredients.
Set the project homepage to https://world.openfoodfacts.org/, and add food, python to the list of public project tags.
To get a notification if the build fails, click the Email Notifications link on the left, add your email address, and click the Add button.

Triggering builds from pull requests

Read the Docs can trigger builds from GitHub pull requests and show you a preview of the documentation with those changes.

To trigger builds from pull requests:

Click the Settings link on the left under the ⚙ Admin menu, check the “Build pull requests for this project” checkbox, and click the Save button at the bottom of the page.
Make some changes to your documentation:
1. Navigate to your GitHub repository, locating the file docs/source/index.rst, and clicking on the ✏️ icon on the top-right with the tooltip “Edit this file” to open a web editor (more information on their documentation).
  
  File view on GitHub before launching the editor
2. In the editor, add the following sentence to the file:
  docs/source/index.rst
  Lumache hosts its documentation on Read the Docs.
3. Write an appropriate commit message, choose the “Create a new branch for this commit and start a pull request” option.
4. Click the green Propose changes button to open the new pull request page, then click the Create pull request button below the description.
Read the Docs building the pull request from GitHub

After opening the pull request, a Read the Docs check will appear indicating that it is building the documentation for that pull request. If you click the Details link while your project is building the build log will be opened. After building this link opens the documentation directly.

Adding a configuration file

The Admin tab of the project home has some global configuration settings for your project.

Build process configuration settings are in .readthedocs.yaml configuration file, in your Git repository, which means it can be different for every version or branch of your project (more on versioning).

Using different Python versions

To build your project with Python 3.8 instead of the latest Python version, edit the .readthedocs.yaml file and change the Python version to 3.8 like this:

.readthedocs.yaml

version: 2

build:
  os: "ubuntu-22.04"
  tools:
    python: "3.8"

python:
  install:
    - requirements: docs/requirements.txt

sphinx:
  configuration: docs/source/conf.py

The purpose of each key in the .readthedocs.yaml configuration file is:

version: Required, specifies version 2 of the configuration file.
build.os: Required, specifies the Docker image used to build the documentation. states the name of the base image.
build.tools.python: Specifies the Python version.
python.install.requirements: Specifies what Python dependencies to install.

After you commit these changes, go back to your project home, navigate to the “Builds” page, and open the new build that just started. You will notice that one of the lines contains python -mvirtualenv: if you click on it, you will see the full output of the corresponding command, stating that it used Python 3.8.6, the latest version of Python 3.8, to create the virtual environment.

Making build warnings more visible

If you navigate to your HTML documentation, you will notice that the index page looks correct but the API section is empty. This is a common issue with Sphinx, and the reason is stated in the build logs. On the build page you opened before, click on the View raw link on the top right, which opens the build logs in plain text, and you will see several warnings:

WARNING: [autosummary] failed to import 'lumache': no module named lumache
...
WARNING: autodoc: failed to import function 'get_random_ingredients' from module 'lumache'; the following exception was raised:
No module named 'lumache'
WARNING: autodoc: failed to import exception 'InvalidKindError' from module 'lumache'; the following exception was raised:
No module named 'lumache'

To spot these warnings more easily and help you to address them, add the sphinx.fail_on_warning option to your Read the Docs configuration file.

To fail on warnings to your Read the Docs project, edit the .readthedocs.yaml file in your project, add the three lines of sphinx configuration below, and commit the file:

.readthedocs.yaml

version: 2

build:
  os: "ubuntu-22.04"
  tools:
    python: "3.8"

python:
  install:
    - requirements: docs/requirements.txt

sphinx:
  configuration: docs/source/conf.py
  fail_on_warning: true

If you navigate to your “Builds” page, you will see a Failed build, which is expected because we’ve configured Sphinx to fail on warnings and several warnings were encountered during the build.

To learn how to fix these warnings, see the next section.

Installing Python dependencies

The reason sphinx.ext.autosummary and sphinx.ext.autodoc fail to import the Making build warnings more visible, is because the lumache module is not installed.

You will need to specify those installation requirements in .readthedocs.yaml.

To install your project dependencies and make your code available to Sphinx, edit .readthedocs.yaml, add the python.install section and commit it:

.readthedocs.yaml

python:
  install:
    - requirements: docs/requirements.txt
    # Install our python package before building the docs
    - method: pip
      path: .

Now, Read the Docs installs the Python code before starting the Sphinx build, which will finish seamlessly. If you go now to the API page of your HTML documentation, you will see the lumache summary! :tada:

Enabling PDF and EPUB builds

Sphinx can build several other formats in addition to HTML, such as PDF and EPUB. You might want to enable these formats for your project so your users can read the documentation offline.

To do so, add the following formats to your .readthedocs.yaml:

.readthedocs.yaml

sphinx:
  configuration: docs/source/conf.py
  fail_on_warning: true

formats:
  - pdf
  - epub

After this change, PDF and EPUB downloads will be available both from the “Downloads” section of the project home, as well as the flyout menu.

Downloads available from the flyout menu

Versioning documentation

Read the Docs supports having several versions of your documentation, in the same way that you have several versions of your code. By default, it creates a latest version that points to the default branch of your version control system (main in the case of this tutorial), and that’s why the URLs of your HTML documentation contain the string /latest/.

Creating a new version of your documentation

Read the Docs automatically creates documentation versions from GitHub branches and tags that follows some rules about looking like version numbers, such as 1.0, 2.0.3 or 4.x.

To create version 1.0 of your code, and consequently of your documentation:

Navigate to your GitHub repository, click the branch selector, type 1.0.x, and click “Create branch: 1.0.x from ‘main’” (more information in the GitHub documentation).
Check that you now have version 1.0.x in your project home, click on the Versions button, and under “Active Versions” you will see two entries:

The latest version, pointing to the main branch.

A new stable version, pointing to the origin/1.0.x branch.

When you created your branch, Read the Docs created a new special version called stable pointing to it. When it’s built it will be listed in the flyout menu.

Setting stable as the default

To set stable as the default version, rather than latest, so that users see the stable documentation when they visit the root URL of your documentation:

In the ⚙ Admin menu of your project home, go to the Settings link, choose stable in the “Default version*” dropdown, and hit Save at the bottom.

Modifying versions

Both latest and stable are now active, which means that they are visible for users, and new builds can be triggered for them. In addition to these, Read the Docs also created an inactive 1.0.x version, which will always point to the 1.0.x branch of your repository.

List of inactive versions of the project

To activate the 1.0.x version:

On your project home, go to the “Versions”, locate 1.0.x under “Activate a version”, and click the Activate button.
On the “Activate” page with “Active” and “Hidden” checkboxes, check only “Active” and click Save.

Note

Read more about hidden versions in our documentation.

Getting project insights

Once your project is up and running, you will probably want to understand how readers are using your documentation, addressing some common questions like:

what are the most visited pages?
what are the most frequently used search terms?
are readers finding what they are looking for?

Read the Docs has traffic and search analytics tools to help you find answers to these questions.

Understanding traffic analytics

The Traffic Analytics view gives you a simple overview of how your readers browse your documentation. It respects visitors’ privacy by not storing identifying information about them.

This page shows the most viewed documentation pages of the past 30 days, plus a visualization of the daily views during that period.

To see the Traffic Analytics view, go back the project page again, click the ⚙ Admin button, and then click the Traffic Analytics section. You will see the list of pages in descending order of visits, and a similar visualization to this one:

You can also download this data in CSV format for closer inspection. To do that, scroll to the bottom of the page and click the Download all data button.

Understanding search analytics

As well as traffic analytics, Read the Docs shows what terms your readers are searching for. This can inform decisions on what areas to focus on, or what parts of your project are less understood or more difficult to find.

To generate some artificial search statistics on the project, go to the HTML documentation, locate the Sphinx search box on the left, type ingredients, and press the Enter key. You will be redirected to the search results page, which will show two entries.

Next, go back to the ⚙ Admin section of your project page, and then click the Search Analytics section. You will see a table with the most searched queries (including the ingredients one you just typed), how many results did each query return, and how many times it was searched. Below the queries table, you will also see a visualization of the daily number of search queries during the past 30 days.

Like the Traffic Analytics, you can also download the whole dataset in CSV format by clicking on the Download all data button.

Where to go from here

This is the end of the tutorial. You have accomplished a lot:

Forked a GitHub repository.
Connected it to Read the Docs.
Built its HTML documentation.
Customized the build process.
Added new documentation versions.
Browsed the project analytics.

Nice work!

Here are some resources to help you continue learning about documentation and Read the Docs:

Learn more about the platform features.
Learn about other supported documentation generators in the Sphinx tutorial or the MkDocs User Guide.
See a list of Read the Docs Example projects.
Learn how to do specific tasks in the How-to guides A-Z.
Learn about private project support and other enterprise features in our commercial service guide.
Join a global community of fellow documentarians in Write the Docs and its Slack workspace.
Contribute to Read the Docs in Contributing to Read the Docs, we appreciate it!

Happy documenting!

Adding a documentation project

This page takes you through the process of adding a documentation project to Read the Docs. If you have connected your Read the Docs account to GitHub, Bitbucket, or GitLab, and you have admin access to the repository you want to add, you will be able to add your project automatically. Otherwise, you will need to add it manually and perform some extra steps.

Automatically add your project

Go to your dashboard.
Click on Add project.
Type the name of the repository you want to add and click on it. If you are using our GitHub App, make sure you have installed the Read the Docs GitHub App in your repository.
Click on Continue.
Edit any of the pre-filled fields with information of the repository.
Click on Next.
Add a configuration file to your repository if it doesn’t exist yet.
Click on This file exists.

See also

Git integration (GitHub, GitLab, Bitbucket): Your project will be automatically configured with a Git integration. Learn more about all the features enabled by that integration on this page.

Manually add your project

Go to your dashboard.
Click on Add project.
Click on Configure manually.
Click on Continue.
Fill all the fields of the form.
Click on Next.
Add a configuration file to your repository if it doesn’t exist yet.
Click on This file exists.

Once your project is created, you’ll need to manually configure the repository webhook if you would like to have new changes trigger builds for your project on Read the Docs.

See also

How to manually configure a Git repository integration: Additional setup steps required for manually created projects. This guide covers setting up SSH keys and webhook integrations.

What’s next

Once your documentation project is created, a build will be triggered. It will automatically fetch the code from your repository and build the documentation. You can see the logs for the build process from your dashboard.

See also

Build process overview: Explanation about the build process.
Configuration file overview: Practical steps to add a configuration file to your documentation project.
Versions: Manage multiple versions of your documentation project.

If you have any trouble, don’t hesitate to reach out to us. The support page has more information on getting in touch.

Markup language: MyST
Rendered version: https://example-jupyter-book.readthedocs.io/
Repository: https://github.com/readthedocs-examples/example-jupyter-book/

Antora

Antora with asciidoctor-kroki extension configured for AsciiDoc and Diagram as Code.

Markup language: AsciiDoc
Rendered version: https://example-antora-basic.readthedocs.io/
Repository: https://github.com/man-chi/example-antora-basic/

Contributing an example project

We would love to add more examples that showcase features of Read the Docs or great tools or methods to build documentation projects.

We require that an example project:

is hosted and maintained by you in its own Git repository, example-<topic>.
contains a README.
uses a .readthedocs.yaml configuration.
is added to the above list by opening a PR targeting examples.rst file from our documentation.

We recommend that your project:

has continuous integration and PR builds.
is versioned as a real software project, i.e. using git tags.
covers your most important scenarios, but references external real-life projects whenever possible.
has a minimal tech stack – or whatever you feel comfortable about maintaining.
copies from an existing example project as a template to get started.

We’re excited to see what you come up with!

Configuration file overview

As part of the initial set up of a Read the Docs project, you need to create a configuration file called .readthedocs.yaml. The configuration file tells Read the Docs what specific settings to use for your project.

This tutorial covers:

Where to put your configuration file 

The .readthedocs.yaml file should be placed in the top-most directory of your project’s repository. When you have changed the configuration file, you need to commit and push the changes to your Git repository. Read the Docs will then automatically find and use the configuration to build your project.

Note

The Read the Docs configuration file is a YAML file. YAML is a human-friendly data serialization language for all programming languages. To learn more about the structure of these files, see the YAML language overview.

Getting started with a template 

Here are some configuration file examples to help you get started. Pick an example based on the tool that your project is using, copy its contents to .readthedocs.yaml, and add the file to your Git repository.

If your project uses Sphinx, we offer a special builder optimized for Sphinx projects.

.readthedocs.yaml

# Read the Docs configuration file for Sphinx projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-24.04
  tools:
    python: "3.12"
    # You can also specify other tool versions:
    # nodejs: "20"
    # rust: "1.70"
    # golang: "1.20"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
  configuration: docs/conf.py
  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
  # builder: "dirhtml"
  # Fail on all warnings to avoid broken references
  # fail_on_warning: true

# Optionally build your docs in additional formats such as PDF and ePub
# formats:
#   - pdf
#   - epub

# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
# python:
#   install:
#     - requirements: docs/requirements.txt

If your project uses MkDocs, we offer a special builder optimized for MkDocs projects.

.readthedocs.yaml

# Read the Docs configuration file for MkDocs projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

mkdocs:
  configuration: mkdocs.yml

# Optionally declare the Python requirements required to build your docs
python:
  install:
  - requirements: docs/requirements.txt

You can find more information about these tools in our Popular documentation tools.

Editing the template 

Now that you have a .readthedocs.yaml file added to your Git repository, you should see Read the Docs trying to build your project with the configuration file. The configuration file probably needs some adjustments to accommodate exactly your project setup.

Note

If you added the configuration file in a separate branch, you may have to activate a version for that branch.

If you have added the file in a pull request, you should enable pull request builds.

Skip: file header and comments

There are some parts of the templates that you can leave in place:

version key: The version key tells the system how to read the rest of the configuration file. The current and only supported version is version 2.
Comments: We added comments that explain the configuration options and optional features. These lines begin with a #.
Commented out features: We use the # in front of some popular configuration options. They are there as examples, which you can choose to enable, delete or save for later.

Adjust: `build.os`

In our examples, we are using Read the Docs’ custom image based on the latest Ubuntu release. Package versions in these images will not change drastically, though will receive periodic security updates.

You should pay attention to this field if your project needs to build on an older version of Ubuntu, or in the future when you need features from a newer Ubuntu.

See also

build.os: Configuration file reference with all values possible for build.os.

Adjust: Python configuration

If you are using Python in your builds, you should define the Python version in build.tools.python.

The python key contains a list of sub-keys, specifying the requirements to install.

Use python.install.path to install the project itself as a Python package using pip
Use python.install.requirements to install packages from a requirements file
Use python.install.method: uv to install packages with uv sync or uv pip
Use build.jobs for Poetry, PDM, or advanced custom install workflows

See also

build.tools.python: Configuration file reference with all Python versions available for build.tools.python.
python: Configuration file reference for configuring the Python environment activated by build.tools.python.

Adjust: Sphinx and MkDocs version

If you are using either the sphinx or mkdocs builder, then Sphinx or MkDocs will be installed automatically in its latest version.

But we recommend that you specify the version that your documentation project uses. The requirements key is a file path that points to a text (.txt) file that lists the Python packages you want Read the Docs to install.

See also

Use a requirements file for Python dependencies: This guide explains how to specify Python requirements, such as the version of Sphinx or MkDocs.
sphinx: Configuration file reference for configuring the Sphinx builder.
mkdocs: Configuration file reference for configuring the MkDocs builder.

Next steps 

There are more configuration options that the ones mentioned in this guide.

After you add a configuration file your Git repository, and you can see that Read the Docs is building your documentation using the file, you should have a look at the complete configuration file reference for options that might apply to your project.

See also

Configuration file reference.: The complete list of all possible .readthedocs.yaml settings, including the optional settings not covered in on this page.
Build process customization: Are familiar with running a command line? Perhaps there are special commands that you know you want Read the Docs to run. Read this guide and learn more about how you add your own commands to .readthedocs.yaml.

Configuration file reference

Read the Docs supports configuring your documentation builds with a configuration file. This file is named .readthedocs.yaml and should be placed in the top level of your Git repository.

The .readthedocs.yaml file can contain a number of settings that are not accessible through the Read the Docs website.

Note

When using a monorepo, it is possible to place the .readthedocs.yaml file in a subdirectory and configure a custom path from the project settings dashboard. See the How to use a .readthedocs.yaml file in a sub-folder documentation for more details.

Because the file is stored in Git, the configuration will apply to the exact version that is being built. This allows you to store different configurations for different versions of your documentation.

Below is an example YAML file which shows the most common configuration options:

.readthedocs.yaml

# Read the Docs configuration file for Sphinx projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-24.04
  tools:
    python: "3.12"
    # You can also specify other tool versions:
    # nodejs: "20"
    # rust: "1.70"
    # golang: "1.20"

# Build documentation in the "docs/" directory with Sphinx
sphinx:
  configuration: docs/conf.py
  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
  # builder: "dirhtml"
  # Fail on all warnings to avoid broken references
  # fail_on_warning: true

# Optionally build your docs in additional formats such as PDF and ePub
# formats:
#   - pdf
#   - epub

# Optional but recommended, declare the Python requirements required
# to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
# python:
#   install:
#     - requirements: docs/requirements.txt

.readthedocs.yaml

# Read the Docs configuration file for MkDocs projects
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the version of Python and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.12"

mkdocs:
  configuration: mkdocs.yml

# Optionally declare the Python requirements required to build your docs
python:
  install:
  - requirements: docs/requirements.txt

See also

Configuration file overview: Practical steps to add a configuration file to your documentation project.

Supported settings

Read the Docs validates every configuration file. Any configuration option that isn’t supported will make the build fail. This is to avoid typos and provide feedback on invalid configurations.

Warning

When using a v2 configuration file, the local settings from the web interface are ignored.

version 

Required:: true

Example:

version: 2

formats 

Additional formats of the documentation to be built, apart from the default HTML.

Type:: list
Options:: htmlzip, pdf, epub, all
Default:: []

Example:

version: 2

# Default
formats: []

version: 2

# Build PDF & ePub
formats:
  - epub
  - pdf

Note

You can use the all keyword to indicate all formats.

version: 2

# Build all formats
formats: all

Warning

At the moment, only Sphinx supports additional formats. pdf, epub, and htmlzip output is not yet supported when using MkDocs. However, you can use Where to put files with custom build commands to generate offline formats for any documentation framework.

With builds from pull requests, only HTML formats are generated. Other formats are resource intensive and will be built after merging.

python 

Configuration of the Python environment to be used.

version: 2

python:
  install:
    - requirements: docs/requirements.txt
    - method: pip
      path: .
      extra_requirements:
        - docs
    - method: pip
      path: another/package

python.install 

Read the Docs uses pip by default to install your Python packages. It also supports uv through python.install. If you are using a Conda environment to manage your build, you’ll need to use the Conda environment file instead. If you have a commercial plan you can also install private dependencies.

List of installation methods of packages and requirements. You can have several of the following methods.

Note

When using method: uv, currently only one entry is allowed under python.install.

Type:: list
Default:: []

Requirements file 

Install packages from a requirements file.

The path to the requirements file, relative to the root of the project.

Key:: requirements
Type:: path
Required:: false

Example:

version: 2

python:
  install:
    - requirements: docs/requirements.txt
    - requirements: requirements.txt

Packages 

Install the project using pip install. The use of python setup.py install is deprecated.

The path to the package, relative to the root of the project.

Key:: path
Type:: path
Required:: false

The installation method.

Key:: method
Options:: pip, setuptools (deprecated), uv
Default:: pip

Extra requirements section to install in addition to the package dependencies.

Key:: extra_requirements
Type:: list
Default:: []

For example, to run pip install .[docs]:

version: 2

python:
  install:
    - method: pip
      path: .
      extra_requirements:
        - docs

uv 

Install dependencies using uv.

Set method: uv and choose one of the following commands:

command: sync to run uv sync using your pyproject.toml and, if present, uv.lock
command: pip to run uv pip install from a requirements file or a local path

Key:: command
Options:: sync, pip
Required:: true

Use path to point uv at a project that is not located at the repository root.

Key:: path
Type:: path
Required:: false

With command: sync, you can select dependency groups from pyproject.toml. Use either a list of group names or all.

Key:: groups
Type:: list or all
Required:: false

With either uv command, you can install optional dependencies. Use either a list of extras or all.

Key:: extras
Type:: list or all
Required:: false

With command: pip, you can install from a requirements file.

Key:: requirements
Type:: path
Required:: false

Note

command: sync doesn’t allow requirements. command: pip requires either requirements or path. groups is only supported with command: sync.

For example, to run uv sync --group docs:

version: 2

python:
   install:
      - method: uv
         command: sync
         groups:
            - docs

For example, to run uv pip install -r docs/requirements.txt:

version: 2

python:
   install:
      - method: uv
         command: pip
         requirements: docs/requirements.txt

For example, to run uv pip install .[docs]:

version: 2

python:
   install:
      - method: uv
         command: pip
         path: .
         extras:
            - docs

conda 

Configuration for Conda support.

version: 2

build:
  os: "ubuntu-24.04"
  tools:
    python: "mambaforge-22.9"

conda:
  environment: environment.yml

conda.environment 

The path to the Conda environment file, relative to the root of the project.

Type:: path
Required:: false

Note

When using Conda, it’s required to specify build.tools.python to tell Read the Docs to use whether Conda or Mamba to create the environment.

build 

Configuration for the documentation build process. This allows you to specify the base Read the Docs image used to build the documentation, and control the versions of several tools: Python, Node.js, Rust, and Go.

version: 2

build:
  os: ubuntu-24.04
  tools:
    python: "3.13"
    nodejs: "22"
    rust: "1.82"
    golang: "1.23"

build.os 

The Docker image used for building the docs. Image names refer to the operating system Read the Docs uses to build them.

Note

Arbitrary Docker images are not supported.

Type:: string
Options:: ubuntu-20.04 (deprecated), ubuntu-22.04, ubuntu-24.04, ubuntu-26.04, ubuntu-lts-latest
Required:: true

Note

The ubuntu-lts-latest option refers to the latest Ubuntu LTS version of Ubuntu available on Read the Docs, which may not match the latest Ubuntu LTS officially released.

Warning

Using ubuntu-lts-latest may break your builds unexpectedly if your project isn’t compatible with the newest Ubuntu LTS version when it’s updated by Read the Docs.

build.tools 

Version specifiers for each tool. It must contain at least one tool.

Type:: dict
Options:: python, nodejs, ruby, rust, golang
Required:: true

Note

Each tool has a latest option available, which refers to the latest version available on Read the Docs, which may not match the latest version officially released. Versions and the latest option are updated at least once every six months to keep up with the latest releases.

Warning

Using latest may break your builds unexpectedly if your project isn’t compatible with the newest version of the tool when it’s updated by Read the Docs.

build.tools.python 

Python version to use. You can use several interpreters and versions, from CPython, Miniconda, and Mamba.

Note

If you use Miniconda3 or Mambaforge, you can select the Python version using the environment.yml file. See our How to use Conda as your Python environment guide for more information.

Type:

string

Options:

2.7
3 (alias for the latest 3.x version available on Read the Docs)
3.6
3.7
3.8
3.9
3.10
3.11
3.12
3.13
3.14
latest (alias for the latest version available on Read the Docs)
miniconda3-4.7
miniconda3-3.12-24.1
miniconda3-3.12-24.9
miniconda-latest (alias for the latest version available on Read the Docs)
mambaforge-4.10 (deprecated)
mambaforge-22.9 (deprecated)
mambaforge-23.11 (deprecated)
mambaforge-latest (deprecated - alias for the latest version available on Read the Docs)
miniforge3-25.11
miniforge3-latest (alias for the latest version available on Read the Docs)

build.tools.nodejs 

Node.js version to use.

Type:

string

Options:

14
16
18
19
20
22
23
24
latest (alias for the latest version available on Read the Docs)

build.tools.ruby 

Ruby version to use.

Type:

string

Options:

3.3
3.4
latest (alias for the latest version available on Read the Docs)

build.tools.rust 

Rust version to use.

Type:

string

Options:

1.55
1.61
1.64
1.70
1.75
1.78
1.82
1.86
1.91
latest (alias for the latest version available on Read the Docs)

build.tools.golang 

Go version to use.

Type:

string

Options:

1.17
1.18
1.19
1.20
1.21
1.22
1.23
1.24
1.25
latest (alias for the latest version available on Read the Docs)

build.apt_packages 

List of APT packages to install. Our build servers run various Ubuntu LTS versions with the default set of package repositories installed. We don’t currently support PPA’s or other custom repositories.

Type:: list
Default:: []

version: 2

build:
  apt_packages:
    - libclang
    - cmake

Note

When possible avoid installing Python packages using apt (python3-numpy for example), use pip or conda instead.

Warning

Currently, it’s not possible to use this option when using build.commands.

build.jobs 

Commands to be run before or after a Read the Docs pre-defined build jobs, or to override a specific job. This allows you to run custom commands at a particular moment in the build process. See Build process customization for more details.

version: 2

build:
  os: ubuntu-24.04
  tools:
    python: "3.13"
  jobs:
    pre_create_environment:
      - echo "Command run at 'pre_create_environment' step"
    post_build:
      - echo "Command run at 'post_build' step"
      - echo `date`

Note

Each build step consists of a list of commands to be executed. build.os and build.tools are also required to use build.jobs.

Note

If the sphinx or mkdocs keys are present in the configuration file, the default steps for each tool will be executed for the create_environment, install, and build steps. You can override any of these steps, but be aware that some steps may depend on others, for example, the default install and build steps depend on the create_environment step creating the Python virtual environment in a specific directory.

If neither of the sphinx or mkdocs keys are present in the configuration file, only the specified build.tools and build.apt_packages will be installed, you will in charge of generating the documentation in the $READTHEDOCS_OUTPUT directory.

Type:: dict
Allowed keys:: post_checkout, pre_system_dependencies, post_system_dependencies, pre_create_environment, create_environment, post_create_environment, pre_install, post_install, pre_build, build, post_build
Required:: false
Default:: {}

build.jobs.build 

Commands to override the default build process. When running builds from pull requests, only the html step will be executed.

version: 2

formats: [pdf, epub]
build:
  os: ubuntu-24.04
  tools:
    python: "3.13"
  jobs:
    create_environment:
      - echo "Preparing environment"
    install:
      - echo "Installing dependencies"
    build:
      html:
        - echo "Building HTML"
        - mkdir -p $READTHEDOCS_OUTPUT/html/
        - echo "Hello world!" > $READTHEDOCS_OUTPUT/html/index.html
      pdf:
        - echo "Building PDF"
        - mkdir -p $READTHEDOCS_OUTPUT/pdf/
        - echo "Hello world!" > $READTHEDOCS_OUTPUT/pdf/index.pdf
      epub:
        - echo "Building ePub"
        - mkdir -p $READTHEDOCS_OUTPUT/epub/
        - echo "Hello world!" > $READTHEDOCS_OUTPUT/epub/index.epub

Type:: dict
Allowed keys:: html, pdf, epub, htmlzip
Required:: false
Default:: {}

Note

If any of the pdf, epub, or htmlzip steps are overridden, they should be included in the formats list.

Note

For each format, you need to generate their output in the $READTHEDOCS_OUTPUT directory.

build.commands 

Specify a list of commands that Read the Docs will run on the build process. When build.commands is used, none of the pre-defined build jobs will be executed.

version: 2

build:
  os: ubuntu-24.04
  tools:
    python: "3.13"
  commands:
    - pip install pelican
    - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/

But we recommend using build.jobs instead:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  jobs:
    install:
      - pip install pelican
    build:
      html:
        - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/

build.jobs offers the same functionality as build.commands, but in a more structured way that allows you to define different commands for each format, while also supporting installing system dependencies via build.apt_packages. See Build process customization for more details.

Note

build.os and build.tools are also required when using build.commands.

Note

All items in the build.commands array are executed in a clean shell environment, i.e. environment changes do not persist and the working directory always start from the git repo.

Type:: list
Required:: false
Default:: []

sphinx 

Configuration for Sphinx documentation.

version: 2

sphinx:
  builder: html
  configuration: conf.py
  fail_on_warning: true

Note

If you want to pin Sphinx to a specific version, use a requirements.txt or environment.yml file (see Requirements file and conda.environment). If you are using a metadata file to describe code dependencies like setup.py, pyproject.toml, or similar, you can use the extra_requirements option (see Packages). This also allows you to override the default pinning done by Read the Docs if your project was created before October 2020.

sphinx.builder 

The builder type for the Sphinx documentation.

Type:: string
Options:: html, dirhtml, singlehtml
Default:: html

Note

The htmldir builder option was renamed to dirhtml to use the same name as sphinx. Configurations using the old name will continue working.

sphinx.configuration 

The path to the conf.py file, relative to the root of the project.

Type:: path
Required:: true

sphinx.fail_on_warning 

Turn warnings into errors (-W and --keep-going options). This means the build fails if there is a warning and exits with exit status 1.

Type:: bool
Default:: false

mkdocs 

Configuration for MkDocs documentation.

version: 2

mkdocs:
  configuration: mkdocs.yml
  fail_on_warning: false

Note

If you want to pin MkDocs to a specific version, use a requirements.txt or environment.yml file (see Requirements file and conda.environment). If you are using a metadata file to describe code dependencies like setup.py, pyproject.toml, or similar, you can use the extra_requirements option (see Packages). This also allows you to override the default pinning done by Read the Docs if your project was created before March 2021.

mkdocs.configuration 

The path to the mkdocs.yml file, relative to the root of the project.

Type:: path
Required:: true

mkdocs.fail_on_warning 

Turn warnings into errors. This means that the build stops at the first warning and exits with exit status 1.

Type:: bool
Default:: false

submodules 

VCS submodules configuration.

Note

Only Git is supported at the moment.

Warning

You can’t use include and exclude settings for submodules at the same time.

version: 2

submodules:
  include:
    - one
    - two
  recursive: true

submodules.include 

List of submodules to be included.

Type:: list
Default:: []

Note

You can use the all keyword to include all submodules.

version: 2

submodules:
  include: all

submodules.exclude 

List of submodules to be excluded.

Type:: list
Default:: []

Note

You can use the all keyword to exclude all submodules. This is the same as include: [].

version: 2

submodules:
  exclude: all

submodules.recursive 

Do a recursive clone of the submodules.

Type:: bool
Default:: false

Note

This is ignored if there aren’t submodules to clone.

search 

Settings for more control over Server side search.

version: 2

search:
  ranking:
    api/v1/*: -1
    api/v2/*: 4
  ignore:
    - 404.html

search.ranking 

Set a custom search rank over pages matching a pattern.

Type:: map of patterns to ranks
Default:: {}

Patterns are matched against the relative paths of the HTML files produced by the build, you should try to match index.html, not docs/index.rst, nor /en/latest/index.html. Patterns can include one or more of the following special characters:

* matches everything, including slashes.
? matches any single character.
[seq] matches any character in seq.

The rank can be an integer number between -10 and 10 (inclusive). Pages with a rank closer to -10 will appear further down the list of results, and pages with a rank closer to 10 will appear higher in the list of results. Note that 0 means normal rank, not no rank.

If you are looking to completely ignore a page, check search.ignore.

version: 2

search:
  ranking:
    # Match a single file
    tutorial.html: 2

    # Match all files under the api/v1 directory
    api/v1/*: -5

    # Match all files named guides.html,
    # two patterns are needed to match both the root and nested files.
    'guides.html': 3
    '*/guides.html': 3

Note

The final rank will be the last pattern to match the page.

Tip

Is better to decrease the rank of pages you want to deprecate, rather than increasing the rank of the other pages.

search.ignore 

List of paths to ignore and exclude from the search index. Paths matched will not be included in search results.

Type:: list of patterns
Default:: ['search.html', 'search/index.html', '404.html', '404/index.html']

Patterns are matched against the relative paths of the HTML files produced by the build, you should try to match index.html, not docs/index.rst, nor /en/latest/index.html. Patterns can include one or more of the following special characters:

* matches everything (including slashes).
? matches any single character.
[seq] matches any character in seq.

version: 2

search:
   ignore:
     # Ignore a single file in the root of the output directory
     - 404.html

     # Ignore all files under the search/ directory
     - search/*

     # Ignore all files named ref.html,
     # two patterns are needed to match both the root and nested files.
     - 'ref.html'
     - '*/ref.html'

version: 2

search:
   ignore:
     # Custom files to ignore
     - file.html
     - api/v1/*

     # Defaults
     - search.html
     - search/index.html
     - 404.html
     - 404/index.html

Note

Since Read the Docs fallbacks to the original search engine when no results are found, you may still see search results from ignored pages.

Schema

You can see the complete schema here. This schema is available at Schema Store, use it with your favorite editor for validation and autocompletion.

Read the Docs Addons

Read the Docs Addons is a group of features for documentation readers and maintainers that you can add to any documentation set hosted on Read the Docs. They are used in the rendered documentation, and can be accessed via hotkeys or on screen UI elements.

Visual diff: Highlight changed output from pull requests
Link previews: See the content the link points to before clicking on it
Documentation notification: Alert users to various documentation states
Flyout: Easily switch between versions and translations
Non-stable notification: Notify readers that they are reading docs from a non stable release
Latest version notification: Notify readers that they are reading docs from a development version
Search as you type: Get search results faster
Traffic analytics: See what pages your users are reading
Search analytics: Understand what your users are searching for
Custom script: Inject custom JavaScript into your documentation

Configuring Read the Docs Addons

Individual configuration options for each addon are available in Settings.

Go to the new dashboard.
Click on a project name.
Go to Settings.
In the left bar, go to Addons.
Configure each Addon individually.

Integrating with Addons

Integrate with Search as you type

To configure your site to use Read the Docs search instead of the default search, adapt the following block of JavaScript to your own site:

javascript/readthedocs.js

// TODO: Change me if needed
const selector = "input[type='search']";

document.addEventListener("DOMContentLoaded", function(event) {
    // Trigger Read the Docs' search addon instead of the default search
    document.querySelector(selector).addEventListener("click", (e) => {
        const event = new CustomEvent("readthedocs-search-show");
        document.dispatchEvent(event);
    });
});

Note

Depending on the tool you are using, you may need to change the selector to match the search input field. You will also need to ensure that the JavaScript file is included in your documentation build.

Addons data and customization

Addons can be customized using CSS variables and the data used by Addons can be accessed using a custom event.

CSS variable customization

Addons use CSS custom properties (CSS variables) to allow for easy customization. To customize addons, add CSS variable definitions to your theme’s CSS:

:root {
    /* Reduce Read the Docs' flyout font a little bit */
    --readthedocs-flyout-font-size: 0.7rem;

    /* Reduce Read the Docs' notification font a little bit */
    --readthedocs-notification-font-size: 0.8rem;

    /* This customization is not yet perfect because we can't change the `line-height` yet. */
    /* See https://github.com/readthedocs/addons/issues/197 */
    --readthedocs-search-font-size: 0.7rem;
}

CSS variables reference

You can find default values and full CSS in our Addons source.

Custom event integration

Read the Docs provides a custom event readthedocs-addons-data-ready that allows you to access the Addons data and integrate it into your theme or documentation. The event provides access to the version data, project information, and other Addons configuration.

To use the custom event:

Add the required meta tag to your HTML template:

<meta name="readthedocs-addons-api-version" content="1" />

Add a JavaScript event listener to handle the data:

document.addEventListener(
  "readthedocs-addons-data-ready",
  function (event) {
    // Access the addons data
    const config = event.detail.data();

    // Example: Create a version selector
    const versions = config.versions.active.map(version => ({
      slug: version.slug,
      url: version.urls.documentation
    }));

    // Use the data to build your UI
    console.log('Available versions:', versions);
  }
);

Event data reference

The event.detail.data() object contains all the Addons configuration, including:

addons - Individual addon configurations
builds.current - Details about the current build
projects.current - Current project details
projects.translations - Available translations
versions.current - Details about the current version
versions.active - List of all active and not hidden versions

Click to see an example of the Addons data

{
"addons": {
    "Most of this config is currently for internal use.": "We are working on making this more public.",
},
"api_version": "1",
"builds": {
    "current": {
        "commit": "6db46a36ed3da98de658b50c66b458bbfa513a4e",
        "created": "2025-01-07T16:02:16.842871Z",
        "duration": 78,
        "error": "",
        "finished": "2025-01-07T16:03:34.842Z",
        "id": 26773762,
        "project": "docs",
        "state": {
            "code": "finished",
            "name": "Finished"
        },
        "success": true,
        "urls": {
            "build": "https://app.readthedocs.org/projects/docs/builds/26773762/",
            "project": "https://app.readthedocs.org/projects/docs/",
            "version": "https://app.readthedocs.org/projects/docs/version/stable/edit/"
        },
        "version": "stable"
    }
},
"domains": {
    "dashboard": "readthedocs.org"
},
"projects": {
    "current": {
        "created": "2016-12-20T06:26:09.098922Z",
        "default_branch": "main",
        "default_version": "stable",
        "external_builds_privacy_level": "public",
        "homepage": null,
        "id": 74581,
        "language": {
            "code": "en",
            "name": "English"
        },
        "modified": "2024-11-13T17:09:09.007795Z",
        "name": "docs",
        "privacy_level": "public",
        "programming_language": {
            "code": "py",
            "name": "Python"
        },
        "repository": {
            "type": "git",
            "url": "https://github.com/readthedocs/readthedocs.org"
        },
        "single_version": false,
        "slug": "docs",
        "subproject_of": null,
        "tags": [
            "docs",
            "python",
            "sphinx-doc"
        ],
        "translation_of": null,
        "urls": {
            "builds": "https://app.readthedocs.org/projects/docs/builds/",
            "documentation": "https://docs.readthedocs.io/en/stable/",
            "downloads": null,
            "home": "https://app.readthedocs.org/projects/docs/",
            "versions": "https://app.readthedocs.org/projects/docs/versions/"
        },
        "users": [
            {
                "username": "eric"
            },
            {
                "username": "davidfischer"
            },
            {
                "username": "humitos"
            },
            {
                "username": "plaindocs"
            },
            {
                "username": "agj"
            },
            {
                "username": "stsewd"
            }
        ],
        "versioning_scheme": "multiple_versions_with_translations"
    },
    "translations": []
},
"readthedocs": {
    "analytics": {
        "code": "UA-17997319-1"
    }
},
"versions": {
    "active": [
        {
            "active": true,
            "aliases": [],
            "built": true,
            "downloads": {
                "epub": "https://docs.readthedocs.io/_/downloads/en/stable/epub/",
                "htmlzip": "https://docs.readthedocs.io/_/downloads/en/stable/htmlzip/"
            },
            "hidden": false,
            "id": 2604018,
            "identifier": "6db46a36ed3da98de658b50c66b458bbfa513a4e",
            "privacy_level": "public",
            "ref": "11.18.0",
            "slug": "stable",
            "type": "tag",
            "urls": {
                "dashboard": {
                    "edit": "https://app.readthedocs.org/projects/docs/version/stable/edit/"
                },
                "documentation": "https://docs.readthedocs.io/en/stable/",
                "vcs": "https://github.com/readthedocs/readthedocs.org/tree/11.18.0/"
            },
            "verbose_name": "stable"
        }
    ],
    "current": {
        "active": true,
        "aliases": [],
        "built": true,
        "downloads": {
            "epub": "https://docs.readthedocs.io/_/downloads/en/stable/epub/",
            "htmlzip": "https://docs.readthedocs.io/_/downloads/en/stable/htmlzip/"
        },
        "hidden": false,
        "id": 2604018,
        "identifier": "6db46a36ed3da98de658b50c66b458bbfa513a4e",
        "privacy_level": "public",
        "ref": "11.18.0",
        "slug": "stable",
        "type": "tag",
        "urls": {
            "dashboard": {
                "edit": "https://app.readthedocs.org/projects/docs/version/stable/edit/"
            },
            "documentation": "https://docs.readthedocs.io/en/stable/",
            "vcs": "https://github.com/readthedocs/readthedocs.org/tree/11.18.0/"
        },
        "verbose_name": "stable"
    }
}

You can see a live example of this in our Addons API response for these docs.

Example: creating a version selector

Here’s a complete example showing how to create a version selector using the Addons data:

document.addEventListener(
  "readthedocs-addons-data-ready",
  function (event) {
    const config = event.detail.data();

    // Create the version selector HTML
    const versionSelector = `
      <div class="version-selector">
        <select onchange="window.location.href=this.value">
          <option value="${config.versions.current.urls.documentation}">
            ${config.versions.current.slug}
          </option>
          ${config.versions.active
            .filter(v => v.slug !== config.versions.current.slug)
            .map(version => `
              <option value="${version.urls.documentation}">
                ${version.slug}
              </option>
            `).join('')}
        </select>
      </div>
    `;

    // Insert the version selector into your page
    document.querySelector('#your-target-element')
      .insertAdjacentHTML('beforeend', versionSelector);
  }
);

Diving deeper

You can read more about all of the Addons functionality by diving into each Addon above. If you are a developer and would like to integrate with our Addons or use our existing data, you can reach out to us and we would love to work with you.

Account authentication methods

Read the Docs supports several authentication methods for creating an account and logging in. The method you choose depends on your preferences and the security requirements of your organization.

These authentication methods are not mutually exclusive; you can use multiple methods to access your account.

Email and password

You can create an account on Read the Docs using your email address and a password. This method works well for individual users and small teams, but it limits the functionality available to you.

VCS provider authentication

You can also create an account on Read the Docs using a VCS authentication provider: GitHub, GitLab, or Bitbucket. This method is more secure and convenient than using an email and password, and provides access to additional features like automatic repository syncing.

VCS provider authentication is required for the following features:

Pull request previews
Automatic repository syncing for easy project creation
Automatic webhook creation on project creation

See also

How to connect your Read the Docs account to your Git provider: Learn how to connect your Read the Docs account with a Git provider.

Google authentication

Note

This feature is only available on Read the Docs for Business.

Read the Docs supports Google authentication for organizations. Google authentication works well for users already using Google services, and easily integrates into your existing workflow.

Google provides authentication, but not authorization. This means that you can log in to Read the Docs with this method, but we aren’t able to determine which projects you have access to automatically.

See also

SSO with Google Workspace: Learn how to configure Google authentication for your organization.

SAML authentication

Note

This feature is only available on Read the Docs for Business.

Read the Docs supports SAML authentication for organizations. SAML authentication is a secure way to authenticate users and manage access to your organization’s projects. This is only available on Enterprise plans, and requires custom integration to be enabled.

SAML provides authentication, but not authorization. This means that users can log in to Read the Docs with this method, but we aren’t able to determine which projects each user has access to automatically.

See also

SSO with SAML: Learn how to configure SAML authentication for your organization.

Two-factor authentication

Read the Docs supports two-factor authentication (2FA) for added security on all authentication methods. If you have 2FA enabled on your account, you will be prompted to enter a code when logging in.

See also

Configuring two-factor authentication: Learn how to enable and disable two-factor authentication on your account.

Automation rules

Automation rules allow project maintainers to automate actions on new branches and tags in Git repositories. If you are familiar with GitOps, this might seem familiar. The goal of automation rules is to be able to control versioning through your Git repository and avoid duplicating these efforts on Read the Docs.

See also

How to manage versions automatically: A practical guide to managing automated versioning of your documentation.
Versions: General explanation of how versioning works on Read the Docs

How automation rules work

When a new tag or branch is pushed to your repository, Read the Docs receives a webhook. We then create a new Read the Docs version that matches your new Git tag or branch.

All automation rules are evaluated for this version, in the order they are listed. If the version matches the version type and the pattern in the rule, the specified action is performed on that version.

Note

Versions can match multiple automation rules, and all matching actions will be performed on the version.

Matching a version in Git

We have a couple predefined ways to match against versions that are created, and you can also define your own.

Predefined matches

Automation rules support two predefined version matches:

Any version: All new versions will match the rule.
SemVer versions: All new versions that follow semantic versioning (with or without a v prefix) will match the rule.

Custom matches

If none of the above predefined matches meet your use case, you can use a Custom match.

The custom match should be a valid Python regular expression. Each new version will be tested against this regular expression.

Actions for versions

When an automation rule matches a new version, the specified action is performed on that version. Currently, the following actions are available:

Activate version: Activates and builds the version.
Hide version: Hides the version. If the version is not active, activates it and builds the version. See Version states.
Make version public: Sets the version’s privacy level to public. See Version states.
Make version private: Sets the version’s privacy level to private. See Version states.
Set version as default: Sets the version as the default version. It also activates and builds the version. See Root URL redirect at /.
Delete version: When a branch or tag is deleted from your repository, Read the Docs will delete it only if isn’t active. This action allows you to delete active versions when a branch or tag is deleted from your repository.

There are a couple caveats to these rules that are useful:

The default version isn’t deleted even if it matches a rule. You can use the Set version as default action to change the default version before deleting the current one.
If your versions follow PEP 440, Read the Docs activates and builds the version if it’s greater than the current stable version. The stable version is also automatically updated at the same time. See more in Versions.

Order

When a new Read the Docs version is created, all rules with a successful match will have their action triggered, in the order they appear on the Automation Rules page.

Examples

Activate all new tags

Match: Any version
Version type: Tag
Action: Activate version

Activate only new branches that belong to the `1.x` release

Custom match: ^1\.\d+$
Version type: Branch
Action: Activate version

Delete an active version when a branch is deleted

Match: Any version
Version type: Branch
Action: Delete version

Set as default new tags that have the `-stable` or `-release` suffix

Custom match: -(stable|release)$
Version type: Tag
Action: Set version as default

Note

You can also create two rules: one to match -stable and other to match -release.

Activate all new tags and branches that start with `v` or `V`

Custom match: ^[vV]
Version type: Tag
Action: Activate version

Custom match: ^[vV]
Version type: Branch
Action: Activate version

Activate all new tags that don’t contain the `-nightly` suffix

Custom match: .*(?<!-nightly)$
Version type: Tag
Action: Activate version

How to create reproducible builds

Your documentation depends on a number of dependencies to be built. If your docs don’t have reproducible builds, an update in a dependency can break your builds when least expected, or make your docs look different from your local version. This guide will help you to keep your builds working over time, so that you can focus on content.

Note

This page explains how to pin the versions that correctly build your project. The versions used in this page are just for illustrative purpose. They are not the latest nor the recommended versions. It is up to you to find those versions.

Define OS and tool versions in the config file 

We recommend defining the explicit version of the OS and tool versions used to build your documentation using the .readthedocs.yaml. This file provides you per version settings, and those settings live in your Git repository.

This allows you to validate changes using pull requests, and ensures that all your versions can be rebuilt from a reproducible configuration.

.readthedocs.yaml

version: 2

# Explicitly set the OS and Python versions
build:
  os: "ubuntu-24.04"
  tools:
    nodejs: "20"
    python: "3.12"

Use a requirements file for Python dependencies 

We recommend using a Pip requirements file or Conda environment file to pin Python dependencies. This ensures that top-level dependencies and extensions don’t change.

A configuration file with explicit dependencies looks like this:

.readthedocs.yaml

# Explicitly set the version of Python and its requirements
python:
  install:
    - requirements: docs/requirements.txt

docs/requirements.txt

# Defining the exact version will make sure things don't break
sphinx==5.3.0
sphinx_rtd_theme==1.1.1
sphinx-notfound-page==1.0.2

Tip

Remember to update your docs’ dependencies from time to time to get new improvements and fixes. It also makes it easy to manage in case a version reaches its end of support date.

Pin your transitive dependencies 

Once you have pinned your own dependencies, the next things to worry about are the dependencies of your dependencies. These are called transitive dependencies, and they can upgrade without warning if you do not pin these packages as well.

We recommend pip-tools to help address this problem. It allows you to specify a requirements.in file with your top-level dependencies, and it generates a requirements.txt file with the full set of transitive dependencies pinned.

docs/requirements.in

sphinx==5.3.0

docs/requirements.txt

#
# This file is autogenerated by pip-compile with Python 3.10
# by the following command:
#
#    pip-compile docs/requirements.in
#
alabaster==0.7.12
    # via sphinx
babel==2.11.0
    # via sphinx
certifi==2022.12.7
    # via requests
charset-normalizer==2.1.1
    # via requests
docutils==0.19
    # via sphinx
idna==3.4
    # via requests
imagesize==1.4.1
    # via sphinx
jinja2==3.1.2
    # via sphinx
markupsafe==2.1.1
    # via jinja2
packaging==22.0
    # via sphinx
pygments==2.13.0
    # via sphinx
pytz==2022.7
    # via babel
requests==2.28.1
    # via sphinx
snowballstemmer==2.2.0
    # via sphinx
sphinx==5.3.0
    # via -r docs.in
sphinxcontrib-applehelp==1.0.2
    # via sphinx
sphinxcontrib-devhelp==1.0.2
    # via sphinx
sphinxcontrib-htmlhelp==2.0.0
    # via sphinx
sphinxcontrib-jsmath==1.0.1
    # via sphinx
sphinxcontrib-qthelp==1.0.3
    # via sphinx
sphinxcontrib-serializinghtml==1.1.5
    # via sphinx
urllib3==1.26.13
    # via requests

See also

Configuration file reference: Configuration file reference
Build process overview: Build process information
Build process customization: Customizing builds to do more

Build process overview

Once a project has been added and a build is triggered, Read the Docs executes a set of pre-defined jobs to build and upload documentation. This page explains in detail what happens behind the scenes, and includes an overview of how you can change this process.

Understanding the build process

Understanding how your content is built helps with debugging any problems you might hit. It also gives you the knowledge to customize the build process.

Note

All the steps are run inside a Docker container, using the image defined in build.os. The build has access to all pre-defined environment variables and custom environment variables.

The build process includes the following jobs:

checkout:

Checks out a project’s code from the Git repository. On Read the Docs for Business, this environment includes the SSH deploy key that gives access to the repository.

system_dependencies:

Installs operating system and runtime dependencies. This includes specific versions of a language (e.g. Python, Node.js, Go, Rust) and also apt packages.

build.tools can be used to define a language version, and build.apt_packages to define apt packages.

create_environment:

Creates a Python environment to install all the dependencies in an isolated and reproducible way. Depending on what’s defined by the project, a virtualenv or a conda environment will be used.

Note

This step is only executed if the sphinx or mkdocs keys are defined.

install:

Installs default and project dependencies. This includes any requirements you have configured in Requirements file.

If the project has extra Python requirements, python.install can be used to specify them.

Tip

We strongly recommend pinning all the versions required to build the documentation to avoid unexpected build errors.

Note

This step is only executed if the sphinx or mkdocs keys are defined.

build:

Runs the main command to build the documentation for each of the formats declared (formats). It will use Sphinx (sphinx) or MkDocs (mkdocs) depending on the project.

upload:

Once the build process finishes successfully, the resulting artifacts (HTML, PDF, etc.) are uploaded to our servers. Our CDN is then purged so your docs are always up to date.

See also

If you require additional build steps or customization, it’s possible to run user-defined commands and customize the build process.

Cancelling builds

There may be situations where you want to cancel a running build. Cancelling builds allows your team to speed up review times and also help us reduce server costs and our environmental footprint.

A couple common reasons you might want to cancel builds are:

the build has an external dependency that hasn’t been updated
there were no changes on the documentation files

For these scenarios, Read the Docs supports three different mechanisms to cancel a running build:

Manually:

Project administrators can go to the build detail page and click Cancel build.

Automatically:

When Read the Docs detects a push to a version that is already building, it cancels the running build and starts a new build using the latest commit.

Programmatically:

You can use user-defined commands on build.jobs or build.commands (see Build process customization) to check for your own cancellation condition and then return exit code 183 to cancel a build. You can exit with the code 0 to continue running the build.

When this happens, Read the Docs will notify your Git provider the build succeeded (✅), so the pull request doesn’t have any failing checks.

Tip

Take a look at Skip builds based on conditions page for some examples.

Automatic disabling of builds

To reduce resource consumption and improve build queue times for all users, Read the Docs will automatically disable builds for projects that have too many consecutive failed builds on their default version.

When a project has 25 consecutive failed builds on its default version, we will disable builds for the project.

This helps ensure that projects with persistent build issues don’t consume resources that could be used by active projects.

Note

This only applies to the default version of a project. Builds on other versions (branches, tags, pull requests) are not counted towards this limit.

If your project has been disabled due to consecutive build failures, you’ll need to re-enable from your project settings. Make sure to fix the underlying issue to avoid being disabled again.

Build resources

Every build has limited resources assigned to it. Our build limits are:

30 minutes build time (upgradable)
7GB of memory (upgradable)
Concurrent builds vary based on your pricing plan

If you are having trouble with your documentation builds, you can reach our support at support@readthedocs.com.

Build process customization

Read the Docs has a well-defined build process that works for many projects. We also allow customization of builds in two ways:

Customize our standard build process: Keep using the default commands for MkDocs or Sphinx, but extend or override the ones you need.
Define a build process from scratch: This option gives you full control over your build. Read the Docs supports any tool that generates HTML.

Extend or override the build process

In the normal build process, the pre-defined jobs checkout, system_dependencies, and upload are executed. If you define a sphinx or mkdocs configuration, the create_environment, install, and build jobs will use the default commands for the selected tool. If no tool configuration is specified, these jobs won’t execute anything by default.

The jobs where users can customize our default build process are:

Step	Customizable jobs
Checkout	`post_checkout`
System dependencies	`pre_system_dependencies`, `post_system_dependencies`
Create environment	`pre_create_environment`, `create_environment`, `post_create_environment`
Install	`pre_install`, `install`, `post_install`
Build	`pre_build`, `build`, `post_build`
Upload	No customizable jobs currently

Note

Any other pre-defined jobs (checkout, system_dependencies, upload) cannot be overridden or skipped.

These jobs are defined using the configuration file with the build.jobs key. This example configuration defines commands to be executed before installing and after the build has finished, and also overrides the default build command for the htmlzip format, while keeping the default commands for the html and pdf formats:

.readthedocs.yaml

version: 2
formats: [htmlzip, pdf]
sphinx:
   configuration: docs/conf.py
python:
   install:
     - requirements: docs/requirements.txt
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  jobs:
    pre_install:
      - bash ./scripts/pre_install.sh
    build:
      # The default commands for generating the HTML and pdf formats will still run.
      htmlzip:
        - echo "Override default build command for htmlzip format"
        - mkdir -p $READTHEDOCS_OUTPUT/htmlzip/
        - echo "Hello, world!" > $READTHEDOCS_OUTPUT/htmlzip/index.zip
    post_build:
      - curl -X POST \
        -F "project=${READTHEDOCS_PROJECT}" \
        -F "version=${READTHEDOCS_VERSION}" https://example.com/webhooks/readthedocs/

Features and limitations

The current working directory is at the root of your project’s cloned repository.
Environment variables are expanded for each individual command (see Environment variable reference).
Each command is executed in a new shell process, so modifications done to the shell environment do not persist between commands.
Any command returning non-zero exit code will cause the build to fail immediately (note there is a special exit code to cancel the build).
build.os and build.tools are required when using build.jobs.
If the sphinx or mkdocs configuration is defined, the create_environment, install, and build jobs will use the default commands for the selected tool.
If neither of the sphinx or mkdocs configurations are defined, the create_environment, install, and build jobs will default to run nothing, giving you full control over the build process.

Where to put files

It is your responsibility to generate HTML and other formats of your documentation when overriding the steps from build.jobs.build. The contents of the $READTHEDOCS_OUTPUT/<format>/ directory will be hosted as part of your documentation.

We store the base folder name _readthedocs/ in the environment variable $READTHEDOCS_OUTPUT and encourage that you use this to generate paths.

Supported formats are published if they exist in the following directories:

$READTHEDOCS_OUTPUT/html/ (required)
$READTHEDOCS_OUTPUT/htmlzip/
$READTHEDOCS_OUTPUT/pdf/
$READTHEDOCS_OUTPUT/epub/

Note

Remember to create the folders before adding content to them. You can ensure that the output folder exists by adding the following command:

mkdir -p $READTHEDOCS_OUTPUT/html/

Search support

Read the Docs will automatically index the content of all your HTML files, respecting the search option.

You can access the search from the Read the Docs dashboard, or by using the Server side search API.

Note

In order for Read the Docs to index your HTML files correctly, they should follow the conventions described at Server side search integration.

Alternative syntax

Alternatively, you can use the build.commands key to completely override the build process.

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  commands:
    - pip install pelican
    - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/

But we recommend using build.jobs instead:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  jobs:
    install:
      - pip install pelican
    build:
      html:
        - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/

build.jobs offers the same functionality as build.commands, but in a more structured way that allows you to define different commands for each format, while also supporting installing system dependencies via build.apt_packages.

Custom Git checkout commands (advanced)

Read the Docs supports overriding the default checkout job with a custom sequence of git commands. This is useful for advanced workflows like sparse checkouts or custom cloning strategies.

To enable this feature, go to your project’s dashboard and update Settings ‣ Custom Git checkout commands. Enter one command per line.

Note

When you define custom Git checkout commands, Read the Docs will not run the default Git clone or checkout. Your commands must perform the clone and checkout of the desired revision.

Tip

If you just want to run some extra commands after the default Git checkout, like unshallowing the clone or fetching extra branches, you should use the build.jobs.post_checkout user-defined job instead.

In case you want to clone submodules, you can use the submodules config key for that.

Commands are executed in order, in the repository working directory. You can use pre-defined environment variables such as READTHEDOCS_GIT_CLONE_URL, READTHEDOCS_GIT_IDENTIFIER, and READTHEDOCS_REPOSITORY_PATH.

Example of custom Git checkout commands

git clone --no-checkout --filter=blob:none --depth 1 $READTHEDOCS_GIT_CLONE_URL .
git sparse-checkout init --cone
git sparse-checkout set docs
git checkout $READTHEDOCS_GIT_IDENTIFIER

Warning

This is an advanced feature. Incorrect commands can prevent builds from checking out code or can expose sensitive files in your repository. If you are unsure, use build customization with build.jobs instead.

Examples

We’ve included some common examples where using build.jobs will be useful. These examples may require some adaptation for each projects’ use case, we recommend you use them as a starting point.

Unshallow git clone

Read the Docs does not perform a full clone in the checkout job in order to reduce network data and speed up the build process. Instead, it performs a shallow clone and only fetches the branch or tag that you are building documentation for. Because of this, extensions that depend on the full Git history will fail. To avoid this, it’s possible to unshallow the git clone:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-20.04"
  tools:
    python: "3.10"
  jobs:
    post_checkout:
      - git fetch --unshallow || true

If your build also relies on the contents of other branches, it may also be necessary to re-configure git to fetch these:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-20.04"
  tools:
    python: "3.10"
  jobs:
    post_checkout:
      - git fetch --unshallow || true
      - git config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*' || true
      - git fetch --all --tags || true

Generate documentation from annotated sources with Doxygen

It’s possible to run Doxygen as part of the build process to generate documentation from annotated sources:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-20.04"
  tools:
    python: "3.10"
  jobs:
    pre_build:
    # Note that this HTML won't be automatically uploaded,
    # unless your documentation build includes it somehow.
      - doxygen

Use MkDocs extensions with extra required steps

There are some MkDocs extensions that require specific commands to be run to generate extra pages before performing the build. For example, pydoc-markdown

.readthedocs.yaml

version: 2
mkdocs:
  configuration: mkdocs.yml
build:
  os: "ubuntu-20.04"
  tools:
    python: "3.10"
  jobs:
    pre_build:
      - pydoc-markdown --build --site-dir "$READTHEDOCS_OUTPUT/html"

Avoid having a dirty Git index

Read the Docs needs to modify some files before performing the build to be able to integrate with some of its features. Because of this reason, it could happen the Git index gets dirty (it will detect modified files). In case this happens and the project is using any kind of extension that generates a version based on Git metadata (like setuptools_scm), this could cause an invalid version number to be generated. In that case, the Git index can be updated to ignore the files that Read the Docs has modified.

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-20.04"
  tools:
    python: "3.10"
  jobs:
    pre_install:
      - git update-index --assume-unchanged environment.yml docs/conf.py

Perform a check for broken links

Sphinx comes with a linkcheck builder that checks for broken external links included in the project’s documentation. This helps ensure that all external links are still valid and readers aren’t linked to non-existent pages.

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-20.04"
  tools:
    python: "3.10"
  jobs:
    pre_build:
      - python -m sphinx -b linkcheck -D linkcheck_timeout=1 docs/ $READTHEDOCS_OUTPUT/linkcheck

Support Git LFS (Large File Storage)

In case the repository contains large files that are tracked with Git LFS, there are some extra steps required to be able to download their content. It’s possible to use post_checkout user-defined job for this.

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-20.04"
  tools:
    python: "3.10"
  jobs:
    post_checkout:
      # Download and uncompress the binary
      # https://git-lfs.github.com/
      - wget https://github.com/git-lfs/git-lfs/releases/download/v3.1.4/git-lfs-linux-amd64-v3.1.4.tar.gz
      - tar xvfz git-lfs-linux-amd64-v3.1.4.tar.gz git-lfs
      # Modify LFS config paths to point where git-lfs binary was downloaded
      - git config filter.lfs.process "`pwd`/git-lfs filter-process"
      - git config filter.lfs.smudge  "`pwd`/git-lfs smudge -- %f"
      - git config filter.lfs.clean "`pwd`/git-lfs clean -- %f"
      # Make LFS available in current repository
      - ./git-lfs install
      # Download content from remote
      - ./git-lfs fetch
      # Make local files to have the real content on them
      - ./git-lfs checkout

Install Node.js dependencies

It’s possible to install Node.js together with the required dependencies by using user-defined build jobs. To setup it, you need to define the version of Node.js to use and install the dependencies by using build.jobs.post_install:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.9"
    nodejs: "16"
  jobs:
    post_install:
      # Install dependencies defined in your ``package.json``
      - npm ci
      # Install any other extra dependencies to build the docs
      - npm install -g jsdoc

Install dependencies with Poetry

Projects managed with Poetry, can use the post_create_environment user-defined job to use Poetry for installing Python dependencies. Take a look at the following example:

.readthedocs.yaml

version: 2

build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  jobs:
    post_install:
      # Install poetry
      # https://python-poetry.org/docs/#installing-manually
      - pip install poetry
      # Install dependencies with 'docs' dependency group
      # https://python-poetry.org/docs/managing-dependencies/#dependency-groups
      # VIRTUAL_ENV needs to be set manually for now.
      # See https://github.com/readthedocs/readthedocs.org/pull/11152/
      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs

sphinx:
  configuration: docs/conf.py

Install dependencies with `uv`

Read the Docs supports uv natively in python.install. Projects using uv can use the configuration methods referenced at python.install instead of overriding build.jobs.

The following example uses uv sync with a dependency group named docs. If a uv.lock file exists, it is respected.

.readthedocs.yaml

version: 2

build:
  os: ubuntu-24.04
  tools:
    python: "3.13"

python:
  install:
    - method: uv
      command: sync
      groups:
        - docs

sphinx:
    configuration: docs/conf.py

Use build.jobs only when you need an advanced uv workflow that isn’t covered by python.install, such as adding specific arguments to the uv command.

Install dependencies from Dependency Groups

Python Dependency Groups are a way of storing lists of dependencies in your pyproject.toml.

pip version 25.1+ as well as many other tools support Dependency Groups. This example uses pip and installs from a group named docs:

.readthedocs.yaml

version: 2

build:
   os: ubuntu-24.04
   tools:
      python: "3.13"
   jobs:
      install:
         # Since the install step is overridden, pip is no longer updated automatically.
         - pip install --upgrade pip
         - pip install --group 'docs'

For more information on relevant pip usage, see the pip user guide on Dependency Groups.

Install dependencies with `pixi`

Projects can use pixi, to install Python dependencies, usually reducing the time taken to install compared to conda or pip. Take a look at the following example:

.readthedocs.yaml

version: 2

build:
   os: ubuntu-24.04
   tools:
       python: "latest"
   jobs:
      create_environment:
         - asdf plugin add pixi
         - asdf install pixi latest
         - asdf global pixi latest
      install:
         # assuming you have an environment called "docs"
         - pixi install -e docs
      build:
         html:
            - pixi run -e docs sphinx-build -T -b html docs $READTHEDOCS_OUTPUT/html

MkDocs projects could use NO_COLOR=1 pixi run -e docs mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html instead.

Update Conda version

Projects using Conda may need to install the latest available version of Conda. This can be done by using the pre_create_environment user-defined job to update Conda before creating the environment. Take a look at the following example:

.readthedocs.yaml

 version: 2

 build:
   os: "ubuntu-22.04"
   tools:
     python: "miniconda3-4.7"
   jobs:
     pre_create_environment:
       - conda update --yes --quiet --name=base --channel=defaults conda

sphinx:
   configuration: docs/conf.py

 conda:
   environment: environment.yml

Using Pelican

Pelican is a well-known static site generator that’s commonly used for blogs and landing pages. If you are building your project with Pelican you could use a configuration file similar to the following:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"
  jobs:
    install:
      - pip install pelican[markdown]
    build:
      html:
        - pelican --settings docs/pelicanconf.py --output $READTHEDOCS_OUTPUT/html/ docs/

Using Docsify

Docsify generates documentation websites on the fly, without the need to build static HTML. These projects can be built using a configuration file like this:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  jobs:
    build:
      html:
        - mkdir --parents $READTHEDOCS_OUTPUT/html/
        - cp --recursive docs/* $READTHEDOCS_OUTPUT/html/

Using Asciidoc

Asciidoctor is a fast processor for converting and generating documentation from AsciiDoc source. The Asciidoctor toolchain includes Asciidoctor.js which you can use with custom build commands. Here is an example configuration file:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    nodejs: "20"
  jobs:
    install:
      - npm install -g asciidoctor
    build:
      html:
        - asciidoctor -D $READTHEDOCS_OUTPUT/html index.asciidoc

Using pydoctor

Pydoctor is an easy-to-use standalone API documentation tool for Python. Here is an example configuration file:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  jobs:
    install:
      - pip install pydoctor
    build:
      html:
        - |
          pydoctor \
            --project-version=${READTHEDOCS_GIT_IDENTIFIER} \
            --project-url=${READTHEDOCS_GIT_CLONE_URL%*.git} \
            --html-viewsource-base=${READTHEDOCS_GIT_CLONE_URL%*.git}/tree/${READTHEDOCS_GIT_COMMIT_HASH} \
            --html-base-url=${READTHEDOCS_CANONICAL_URL} \
            --html-output $READTHEDOCS_OUTPUT/html/ \
            ./src/my_project

Generate text format with Sphinx

There might be various reasons why would you want to generate your documentation in text format (secondary to html). One of such reasons would be generating LLM friendly documentation.

See the following example for how to add generation of additional text format to your existing documentation. Deviations from standard build configuration are highlighted/emphasized:

.readthedocs.yaml

version: 2

sphinx:
  configuration: docs/conf.py

python:
  install:
  - requirements: docs/requirements.txt

build:
  os: ubuntu-22.04
  tools:
    python: "3.12"
  jobs:
    post_build:
      - mkdir -p $READTHEDOCS_OUTPUT/html/
      - sphinx-build -n -b text docs $READTHEDOCS_OUTPUT/html/

The generated .txt files will be placed in the html directory, together with .html files.

Git integration (GitHub, GitLab, Bitbucket)

Your Read the Docs account can be connected to your Git provider’s account. Connecting your account provides the following features:

🔑️ Easy login: Log in to Read the Docs with your GitHub, Bitbucket, or GitLab account.
🔁️ List your projects: Select a project to automatically import from all your Git repositories and organizations. See: Adding a documentation project.
⚙️ Automatic configuration: Have your Git repository automatically configured with your Read the Docs webhook, which allows Read the Docs to build your docs on every change to your repository.
🚥️ Commit status: See your documentation build status as a commit status indicator on pull request builds.

See also

Manually add your project: Using a different provider? You can configure it manually. Read the Docs still supports other providers such as Gitea or GitHub Enterprise.

Getting started

✅️ Signed up with your Git provider?

If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab credentials, you’re all done. Your account is connected.

The rest of this guide explains how the automatic configuration works.

⏩️️ Signed up with your email address?

If you have signed up to Read the Docs with your email address, you can add the connection to the Git provider afterward. You can also add a connection to an additional Git provider this way.

Please follow How to connect your Read the Docs account to your Git provider in this case.

Once you have your account connected, you can follow the Adding a documentation project guide to actually add your project to Read the Docs.

How automatic configuration works

When your Read the Docs account is connected to GitHub, Bitbucket, or GitLab and you add a new Read the Docs project:

Read the Docs automatically creates a Read the Docs Integration that matches your Git provider.
Read the Docs creates an incoming webhook with your Git provider, which is automatically added to your Git repository’s settings using the account connection.

After project creation, you can continue to configure the project. All settings can be modified, including the ones that were automatically created.

Tip

A single Read the Docs account can connect to many different Git providers. This allows you to have a single login for all your various identities.

Read the Docs incoming webhook

Note

When using our GitHub App, Read the Docs subscribes to all required events. You don’t need to create a webhook on your repository.

Accounts with GitHub, Bitbucket, and GitLab integration automatically have Read the Docs’ incoming webhook configured on all Git repositories that are imported. Other setups can set up the webhook through manual configuration.

When an incoming webhook notification is received, Read the Docs ensures that it matches an existing project. Once the webhook is validated, an action is taken based on the information inside of the webhook.

Possible webhook action outcomes are:

Builds the latest commit.
Synchronizes your versions based on the latest tag and branch data in Git.
Creates a pull request build.
Runs your automation rules.

Screenshot of the Dashboard view for the incoming webhook — All calls to the incoming webhook are logged. Each call can trigger builds and version synchronization.

On Read the Docs for Business, Git integration makes it possible for us to synchronize your Git repository’s access rights from your Git provider. That way, the same access rights are effective on Read the Docs and you don’t have to configure access in two places. See more in our Single sign-on with GitHub, Bitbucket, or GitLab.

How does the connection work?

Read the Docs uses OAuth to connect to your account at GitHub, Bitbucket, or GitLab. You are asked to grant permissions for Read the Docs to perform a number of actions on your behalf.

At the same time, we use this process for authentication (login) since we trust that GitHub, Bitbucket, or GitLab have verified your user account and email address.

By granting Read the Docs the requested permissions, we are issued a secret OAuth token from your Git provider. Using the secret token, we can automatically configure repositories during project creation. We also use the token to send back build statuses and preview URLs for pull requests.

Note

Access granted to Read the Docs can always be revoked. This is a function offered by all Git providers.

Git provider integrations

If your project is using Organizations (Read the Docs for Business) or maintainers (Read the Docs Community), then you need to be aware of who is setting up the integration for the project.

The Read the Docs user who sets up the project through the automatic import should also have admin rights to the Git repository.

A Git provider integration is active through the authentication of the user that creates the integration. If this user is removed, make sure to verify and potentially recreate all Git integrations for the project.

Note

When using our GitHub App, If the original user who connected the repository to Read the Docs loses access to the project or repository, the GitHub App will still have access to the repository, and the integrations will continue to work.

Permissions for connected accounts

Read the Docs does not generally ask for write permission to your repository code (with one exception detailed below). However, we do need permissions for authorizing your account so that you can log in to Read the Docs with your connected account credentials.

Read the Docs requests the following permissions (more precisely, OAuth scopes) when connecting your Read the Docs account to GitHub.

Read access to your email address (user:email): We ask for this so you can create a Read the Docs account and log in with your GitHub credentials.
Administering webhooks (admin:repo_hook): We ask for this so we can create webhooks on your repositories when you import them into Read the Docs. This allows us to build the docs when you push new commits.
Read access to your organizations (read:org): We ask for this so we know which organizations you have access to. This allows you to filter repositories by organization when importing repositories.
Repository status (repo:status): Repository statuses allow Read the Docs to report the status (e.g. passed, failed, pending) of pull requests to GitHub.

Note

Read the Docs for Business asks for one additional permission (repo) to allow access to private repositories and to allow us to set up SSH keys to clone your private repositories. Unfortunately, this is the permission for read/write control of the repository but there isn’t a more granular permission that only allows setting up SSH keys for read access.

We request permissions for:

Administering your repositories (repository:admin): We ask for this so we can create webhooks on your repositories when you import them into Read the Docs. This allows us to build the docs when you push new commits. NB! This permission scope does not include any write access to code.
Reading your account information including your email address: We ask for this so you can create a Read the Docs account and log in with your Bitbucket credentials.
Read access to your team memberships: We ask for this so we know which organizations you have access to. This allows you to filter repositories by organization when importing repositories.
Read access to your repositories: We ask for this so we know which repositories you have access to.

To read more about Bitbucket permissions, see official Bitbucket documentation on API scopes

Like the others, we request permissions for:

Reading your account information (read_user)
API access (api) which is needed to create webhooks in GitLab

GitHub permission troubleshooting

Repositories not in your list to import.

Many organizations require approval for each OAuth application that is used, or you might have disabled it in the past for your personal account. This can happen at the personal or organization level, depending on where the project you are trying to access has permissions from.

You need to make sure that you have granted access to the Read the Docs OAuth App to your personal GitHub account. If you do not see Read the Docs in the OAuth App settings, you might need to disconnect and reconnect the GitHub service.

See also

GitHub docs on requesting access to your personal OAuth for step-by-step instructions.

GitHub App

Warning

Our GitHub App is currently in beta, see our blog post for more information.

We are in the process of migrating our GitHub OAuth application to a GitHub App. We have two GitHub Apps, one for each of our platforms:

Features

When using GitHub, Read the Docs uses a GitHub App to interact with your repositories. This has the following benefits over using an OAuth application:

More control over which repositories Read the Docs can access. You don’t need to grant access to all your repositories in order to create an account or connect a project to a single repository.
No need to create webhooks on your repositories. The GitHub App subscribes to all required events when you install it.
No need to create a deploy key on your repository (Read the Docs for Business only). The GitHub App can clone your private repositories using a temporal token.
If the original user who connected the repository to Read the Docs loses access to the project or repository, the GitHub App will still have access to the repository.
You can revoke access to the GitHub App at any time from your GitHub settings.
Never out of sync with changes on your repository. The GitHub App subscribes to all required events and will always keep your project up to date with your repository.

Adding a project from a repository

To add a project from a repository, you need to install the Read the Docs GitHub App and grant access to that repository. Use the links below to complete the installation and permissions, then create the project from your Read the Docs account.

Once you have installed the GitHub App, in Read the Docs, click on the Projects tab, and click on Add project, search for the repository you want to create a project for, and then follow the instructions from there.

Connect a repository to an existing project

In case you manually added a project on Read the Docs, or if you want to connect your project to a different repository, you need to install the Read the Docs GitHub App and grant access to the repository you want to connect. As with adding a project, complete installation and permissions via the links below, and select the repository from your project settings on Read the Docs.

Once you have installed the GitHub App, go to the Settings page of the project in Read the Docs, and select the repository you want to connect from the Connected repository dropdown.

Manually migrating a project

We recommend using the migration page to migrate your projects from the old OAuth application to the new GitHub App.

But in case you need to manually migrate a project, you can follow these steps:

Go to the Settings page of your Read the Docs project, and click on the Integrations tab in Read the Docs, and delete all the integrations that are listed there.
Go to the settings page of your GitHub repository, click on the GitHub Webhooks tab, and delete all the webhooks with URLs that start with:
- https://readthedocs.org/api/v2/webhook/<your-project-slug> or https://app.readthedocs.org/api/v2/webhook/<your-project-slug> for Read the Docs Community.
- https://readthedocs.com/api/v2/webhook/<your-project-slug> or https://app.readthedocs.com/api/v2/webhook/<your-project-slug> for Read the Docs Business.
For projects using Read the Docs Business, go to the settings page of your GitHub repository, click on the GitHub Deploy keys tab, and delete the deploy with a title matching the format support@readthedocs.com (<your-project-slug>).
Connect the project to the repository.

Revoking access

Warning

If you revoke access to the GitHub App with any of the methods below, all projects linked to that repository will stop working, but the projects and its documentation will still be available. If you grant access to the repository again, you will need to manually connect your project to the repository.

You can revoke access to the Read the Docs GitHub App at any time from your GitHub settings. All revocation options happen from your account or organization settings; no action is required inside Read the Docs until you decide to reconnect a project.

There are three ways to revoke access to the Read the Docs GitHub App:

Revoke access to one or more repositories:: Remove the repositories from the list of repositories that the GitHub App has access to.
Suspend the GitHub App:: This will suspend the GitHub App and revoke access to all repositories. The installation and configuration will still be available, and you can re-enable the GitHub App at any time.
Uninstall the GitHub App:: This will uninstall the GitHub App and revoke access to all repositories. The installation and configuration will be removed, and you will need to re-install the GitHub App and reconfigure it to use it again.

Security

When cloning private repositories (Read the Docs for Business only) Read the Docs creates an installation access token, which has read access to the contents permission, and it’s scoped to the repository to be cloned.

This token is valid for one hour and GitHub automatically grants read access to the metadata permission, which allows to query the repository collaborators, events, and other metadata. By default, Read the Docs doesn’t show this token during the build, but the token is available during the whole build process. Make sure to not print it in your build logs, and that only trusted users are able to trigger builds on your project.

Note

If your repository is public, Read the Docs will not create an installation access token.

Note

The build log page is publicly accessible only if your project and version to build are marked as public. See more in Privacy levels.

Troubleshooting

Repository not found in the repository list

Make sure you have installed the corresponding GitHub App in your GitHub account or organization, and have granted access to the repository your project will be connected to.

If you still can’t see the repository in the list, you may need to wait a couple of minutes and refresh the page, or click on the “Refresh your repositories” button on the project creation page.

Repository is in the list, but isn’t usable

Make sure you have admin access to the repository you are trying to use for your project. If you are using Read the Docs Community, make sure your project is public, or use Read the Docs for Business to create projects from private repositories.

If you still can’t use the repository for your project, you may need to wait a couple of minutes and refresh the page, or click on the “Refresh your repositories” button on the project creation page.

Pull request previews

Your project can be configured to build and preview documentation for every new pull request. Previewing changes during review makes it easier to catch formatting and display issues before they go live.

Features

Build on pull request events

We create and build a new version when a pull request is opened, and rebuild it whenever a new commit is pushed.

Build status report

Your project’s pull request build status will show as one of your pull request’s checks. This status will update as the build is running, and will show a success or failure status when the build completes.

Build overview with changed files

We create a comment on the pull request including a link to the preview of the documentation, and a list of the files that changed between the current pull request and the latest version of the project’s documentation.

Note

This feature is only available for projects connected to a GitHub App.

Pull request notifications

A pull request notification can be shown at the top of preview pages, which let readers know they aren’t viewing an active version of the project. New projects have this notification disabled by default; enable it from Settings → Addons → Notifications.

Visual diff

Visual diff shows proposed changes by visually highlighting the differences between the current pull request and the latest version of the project’s documentation.

Press d to toggle between Visual diff and normal pull request preview.

See also

How to configure pull request builds: A guide to configuring pull request builds on Read the Docs.

Security

If pull request previews are enabled for your project, anyone who can open a pull request on your repository will be able to trigger a build of your documentation. For this reason, pull request previews are served from a different domain than your main documentation (org.readthedocs.build and com.readthedocs.build).

Builds from pull requests have access to environment variables that are marked as Public only, if you have environment variables with private information, make sure they aren’t marked as Public. See Environment variables and build process for more information.

On Read the Docs for Business you can set pull request previews to be private or public, If you didn’t import your project manually and your repository is public, the privacy level of pull request previews will be set to Public. Public pull request previews are available to anyone with the link to the preview, while private previews are only available to users with access to the Read the Docs project.

Warning

If you set the privacy level of pull request previews to Private, make sure that only trusted users can open pull requests in your repository.

Setting pull request previews to private on a public repository can allow a malicious user to access read-only APIs using the user’s session that is reading the pull request preview. Similar to GHSA-pw32-ffxw-68rh.

Build failure notifications

Build notifications can alert you when your documentation builds fail so you can take immediate action. We offer the following methods for being notified:

Email notifications:

Read the Docs allows you to configure build notifications via email. When builds fail, configured email addresses are notified.

Build Status Webhooks:

Build notifications can happen via webhooks. This means that we are able to support a wide variety of services that receive notifications.

Slack and Discord are supported through ready-made templates.

Webhooks can be customized through your own template and a variety of variable substitutions.

Note

We don’t trigger email notifications or build status webhooks on builds from pull requests.

See also

How to setup email notifications: Enable email notifications on failed builds, so you always know that your docs are deploying successfully.
Setting up outgoing webhooks: Steps for setting up build notifications via webhooks, including examples for popular platforms like Slack and Discord.

Environment variable overview

Read the Docs allows you to define your own environment variables to be used in the build process. It also defines a set of default environment variables with information about your build. These are useful for different purposes:

Custom environment variables are useful for adding build secrets such as API tokens.
Default environment variables are useful for varying your build specifically for Read the Docs or specific types of builds on Read the Docs.

Custom environment variables are defined in the dashboard interface in Admin ‣ Environment variables. Environment variables are defined for a project’s entire build process, with 2 important exceptions.

Aside from storing secrets, there are other patterns that take advantage of environment variables, like reusing the same monorepo configuration in multiple documentation projects. In cases where the environment variable isn’t a secret, like a build tool flag, you should also be aware of the alternatives to environment variables.

See also

How to use custom environment variables: A practical example of adding and accessing custom environment variables.
Environment variable reference: Reference to all pre-defined environment variables for your build environments.
Public API reference: Environment variables: Reference for managing custom environments via Read the Docs’ API.

Environment variables and build process

When a build process is started, pre-defined environment variables and custom environment variables are added at each step of the build process. The two sets of environment variables are merged together during the build process and are exposed to all of the executed commands, with pre-defined variables taking precedence over custom environment variables.

There are two noteworthy exceptions for custom environment variables:

Build checkout step: Custom environment variables are not available during the checkout step of the build process
Pull request builds: Custom environment variables that are not marked as Public will not be available in pull request builds

Limitations

Individual environment variables are limited to 48 KB in size.
The total size of all environment variables in a project is limited to 256 KB.

Patterns of using environment variables

Aside from storing secrets, environment variables are also useful if you need to make either your .readthedocs.yaml or the commands called in the build process behave depending on pre-defined environment variables or your own custom environment variables.

Example: Multiple projects from the same Git repo

If you have the need to build multiple documentation websites from the same Git repository, you can use an environment variable to configure the behavior of your build commands or Sphinx conf.py file.

An example of this is found in the documentation project that you are looking at now. Using the Sphinx extension sphinx-multiproject, the following configuration code decides whether to build the user or developer documentation. This is defined by the PROJECT environment variable:

Read the Docs’ conf.py [1] is used to build 2 documentation projects.

from multiproject.utils import get_project

# (...)

multiproject_projects = {
    "user": {
        "use_config_file": False,
        "config": {
            "project": "Read the Docs user documentation",
        },
    },
    "dev": {
        "use_config_file": False,
        "config": {
            "project": "Read the Docs developer documentation",
        },
    },
}


docset = get_project(multiproject_projects)

Alternatives to environment variables

In some scenarios, it’s more feasible to define your build’s environment variables using the .readthedocs.yaml configuration file. Using the dashboard for administering environment variables may not be the right fit if you already know that you want to manage environment variables as code.

Consider the following scenario:

The environment variable is not a secret.

and
The environment variable is used just once for a custom command.

In this case, you can define the environment variable as code using Build process customization. The following example shows how a non-secret single-purpose environment variable can also be used.

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.12"
  jobs:
    post_build:
      - EXAMPLE_ENVIRONMENT_VARIABLE=foobar command --flag

Environment variable reference

All build processes have the following environment variables automatically defined and available for each build step:

READTHEDOCS

Whether the build is running inside Read the Docs.

Default:: True

READTHEDOCS_PRODUCTION_DOMAIN

Domain where Read the Docs application/dashboard and API are running.

Example:: readthedocs.org
Example:: readthedocs.com
Example:: app.readthedocs.org
Example:: app.readthedocs.com
Example:: devthedocs.org
Example:: devthedocs.com

READTHEDOCS_PROJECT: The slug of the project being built. For example, my-example-project.

READTHEDOCS_LANGUAGE

The locale name, or the identifier for the locale, for the project being built. This value comes from the project’s configured language code, which is in lowercase and uses a dash as a separator.

Example:: en
Example:: it
Example:: de-at
Example:: es
Example:: pt-br

READTHEDOCS_VERSION: The slug of the version being built, such as latest, stable, or a branch name like feature-1234. For pull request builds, the value will be the pull request number.

READTHEDOCS_VERSION_NAME: The verbose name of the version being built, such as latest, stable, or a branch name like feature/1234.

READTHEDOCS_VERSION_TYPE

The type of the version being built.

Example:: branch
Example:: tag
Example:: external (for pull request builds)
Example:: unknown

READTHEDOCS_VIRTUALENV_PATH

Path for the virtualenv that was created for this build. Only exists for builds using Virtualenv and not Conda.

Example:: /home/docs/checkouts/readthedocs.org/user_builds/project/envs/version

READTHEDOCS_OUTPUT

Base path for well-known output directories. Files in these directories will automatically be found, uploaded, and published.

You need to concatenate an output format to this variable. Currently valid formats are html, pdf, htmlzip, and epub. (e.g. $READTHEDOCS_OUTPUT/html/ or $READTHEDOCS_OUTPUT/pdf/) You also need to create the directory before moving outputs into the destination. You can create it with the following command mkdir -p $READTHEDOCS_OUTPUT/html/. Note that only html supports multiple files, the other formats should have one and only one file to be uploaded.

See also

Where to put files: Information about using custom commands to generate output that will automatically be published once your build succeeds.

READTHEDOCS_CANONICAL_URL

Canonical base URL for the version that is built. If the project has configured a custom domain (e.g. docs.example.com) it will be used in the resulting canonical URL. Otherwise, your project’s default subdomain will be used.

The path for the language and version is appended to the domain, so the final canonical base URLs can look like the following examples:

Example:: https://docs.example.com/en/latest/
Example:: https://docs.readthedocs.io/ja/stable/
Example:: https://example--17.org.readthedocs.build/fr/17/

READTHEDOCS_REPOSITORY_PATH

Path where the repository was cloned.

Example:: /home/docs/checkouts/readthedocs.org/user_builds/test-builds/checkouts/latest

READTHEDOCS_GIT_CLONE_URL

URL for the remote source repository, from which the documentation is cloned. It could be HTTPS, SSH or any other URL scheme supported by Git. This is the same URL defined in your Project’s dashboard in Admin ‣ Settings ‣ Repository URL.

Example:: https://github.com/readthedocs/readthedocs.org
Example:: git@github.com:readthedocs/readthedocs.org.git

READTHEDOCS_GIT_IDENTIFIER

Contains the Git identifier that was checked out from the remote repository URL. Possible values are either a branch or tag name.

Example:: v1.x
Example:: bugfix/docs-typo
Example:: feature/signup
Example:: update-readme

Note

When building pull requests, this variable contains the numeric ID of the pull request, as we don’t have access to the branch name.

READTHEDOCS_GIT_COMMIT_HASH

Git commit hash identifier checked out from the repository URL.

Example:: 1f94e04b7f596c309b7efab4e7630ed78e85a1f1

See also

Environment variable overview: General information about how environment variables are used in the build process.
How to use custom environment variables: Learn how to define your own custom environment variables, in addition to the pre-defined ones.

Versions

Read the Docs supports publishing multiple versions of your documentation. This allows your users to read the exact documentation for the specific version of the project they are using.

Versioning is useful for many reasons, but a few common use cases are:

Shipping API client libraries that release versions across time.
Having a “stable” and “latest” branch so that users can see the current release and the upcoming changes.
Having a private development branch and a public stable branch so that in development releases aren’t accidentally seen by users until they are released.

Versions are Git tags and branches

When you add a project to Read the Docs, all Git tags and branches are created as Inactive and Not Hidden versions by default. During initial setup, Read the Docs also creates a latest version that points to the default branch defined in your Git repository (usually main). This version should always exist and is the default version for your project.

If your project has any tags or branches with a name following semantic versioning (with or without a v prefix), we also create a stable version tracking your greatest stable semantic version number release. It excludes pre-release versions indicated by alphas, betas, and similar unstable notations, according to semantic versioning. If you want a custom stable version, create either a tag or branch in your project with that name.

Note

If you have at least one tag, tags will take preference over branches when selecting the stable version.

When you have Git integration (GitHub, GitLab, Bitbucket) configured for your repository, we will automatically build each version when you push a commit.

Version states

Each version of your documentation has a state that changes the visibility of it to other users.

Active or Inactive

Active docs are visible, and builds can be triggered for the documentation.
Inactive versions have their documentation content deleted and builds cannot be triggered.

Hidden or Not hidden

Not hidden docs are listed on the flyout menu on the docs site and are shown in search results.
Hidden docs are not listed on the flyout menu on the docs site and are not shown in search results.

Hiding a version doesn’t make it private, any user with a link to its docs can still see it. This is useful when:

You no longer support a version, but you don’t want to remove its docs.
You have a work in progress version and don’t want to publish its docs just yet.

Hidden versions are listed as Disallow: /path/to/version/ in the default robots.txt support created by Read the Docs.

Public or Private (only available on Business hosting)

Public versions are visible to everyone, and are browsable by unauthenticated users.
Private versions are available only to people who have permissions to see them. They will return a 404 Not Found when visited by people without viewing permissions. If you want to share your docs temporarily, see Sharing private documentation.

If you want unauthenticated people to be able to view the build page of your public versions, you’ll need to the set the privacy level of your project to public.

Version syncing

Versions are automatically synced when the following events happen:

A commit is pushed to your Git repository and you have a Git integration configured.
A build for any of your version is triggered.

If you find that your versions are out of date, triggering a build is the best approach to ensuring they are synced again.

Managing your versions

When you activate a version, a build will be triggered to automatically deploy your documentation.

When you deactivate a version, all of the artifacts of your version will be deleted and a 404 Not Found page will be served for it.

You can change the state for each version of your documentation in the Versions tab of your project.

Version URL identifier (slug)

Each version of your project has a unique URL identifier (slug). This identifier is used to reference the version in your documentation, dashboard, and API.

A version slug is automatically generated from the name of the branch or tag in your repository, some special characters like spaces and / are replaced with a dash (-), and the name is lowercased. If the resulting slug collides with another one, a suffix is added (_a, _b, etc.).

You can change the slug of a version in the versions tab of your project, but you should take the following into account:

Changing the slug of an active version will result on its previous documentation being deleted, and a new build being triggered. Be careful when renaming active versions, specially old ones that might not build anymore.
Any URL referencing your version with the old slug will return a 404 Not Found page. You can use an exact redirect to redirect users to the new URL,
You may still see the original name of the version in some places, as changing the slug only affects the URL used in your documentation and how the APIs identify that version. We are considering adding another field to be used for display in the future.
Sorting of versions in the version selector is done based on the slug, changing the slug of a version may change the order in which they are shown to your users. We are considering adding another field to be used for sorting in the future.
You can’t change the slug of versions that are managed by Read the Docs, like latest and stable.
Slugs must be unique for each version of your project.
The slug can contain lowercase letters, numbers, dashes (-), underscores (_) and dots (.). If you try to use a slug that contains any other character, you’ll get an error message with a suggestion of a valid slug.

Warning

Changing the slug of an active version will result on its previous documentation being deleted, and a new build being triggered. Be careful when renaming active versions, specially old ones that might not build anymore.

Disabling versioning completely

You can configure a single version project, and the version will be hidden from the URL.

Version warning notifications

As part of Read the Docs Addons, Read the Docs displays notifications in the following situations:

Non-stable notification

A notification on all non-stable versions is shown to clearly communicate to readers they may be reading an outdated version of the documentation.

Specifically, when a version is being shown that is not the stable version, and there is a stable version available.

Latest version notification

A notification shown on the latest version tells readers they are reading the latest/development version of the documentation that may include features not yet deployed.

Specifically, when the latest version is being shown, and there’s also an active stable version that is not hidden.

Each of these notifications can be configured by project admins in Configuring Read the Docs Addons.

Redirects on root URLs

When a user hits the root URL for your documentation, for example https://pip.readthedocs.io/, they will be redirected to the Default version. This defaults to latest, but another common configuration is setting it to your stable version.

Versioning workflows

Read the Docs makes certain assumptions about your documentation version defaults, all of which can be reconfigured if necessary:

The latest version points to the most up to date development code. If you develop on a branch that is different than the default for your version control system, set the Default Branch to the branch you use.
Tags are semantic versioning compatible (according to PEP 440) snapshots of your documentation. The most recent semantic tag maps to the stable version.

Semantic versioning allows “normal” version numbers like 1.4.2, as well as pre-releases like this: 2.0a1. The stable version of your documentation never includes a pre-release. An optional v prefix like v1.4.2 or v2.0a1 is also allowed.
Branches are assumed to be long-lived branches, This is most useful for release branches, which are maintained over time for a specific release. An example would be a 2.1 branch that is kept up to date with the latest 2.1.x release.

Subprojects

In this article, you can learn more about how several documentation projects can be combined and presented to the reader on the same website.

Read the Docs can be configured to make other projects available on the website of the main project as subprojects. This allows for documentation projects to share a search index and a namespace or custom domain, but still be maintained independently.

This is useful for:

Organizations that need all their projects visible in one documentation portal or landing page
Projects that document and release several packages or extensions
Organizations or projects that want to have a common search function for several sets of documentation

For a main project example-project, a subproject example-project-plugin can be made available as follows:

Main project: https://example-project.readthedocs.io/en/latest/
Subproject: https://example-project.readthedocs.io/projects/plugin/en/latest/

See also

Managing subprojects: Learn how to create and manage subprojects
How to link to other documentation projects with Intersphinx: Learn how to use references between different Sphinx projects, for instance between subprojects

Using aliases

Adding an alias for the subproject allows you to override the URL that is used to access it, giving more control over how you want to structure your projects. You can choose an alias for the subproject when it is created.

You can set your subproject’s project name and slug however you want, but we suggest prefixing it with the name of the main project.

Typically, a subproject is created with a <mainproject>- prefix, for instance if the main project is called example-project and the subproject is called plugin, then the subproject’s Read the Docs project slug will be example-project-plugin. When adding the subproject, the alias is set to plugin and the project’s URL becomes example-project.readthedocs.io/projects/plugin.

When you add a subproject, the subproject will not be directly available anymore from its own domain. For instance, example-project-plugin.readthedocs.io/ will redirect to example-project.readthedocs.io/projects/plugin.

See also

URL path prefixes: On Read the Docs for Business Pro plans and higher, you can customize the /projects/ prefix or remove it entirely.

Custom domain on subprojects

Adding a custom domain to a subproject is not allowed, since your documentation will always be served from the domain of the parent project.

Separate release cycles

By using subprojects, you can present the documentation of several projects even though they have separate release cycles.

Your main project may have its own versions and releases, while all of its subprojects maintain their own individual versions and releases. We recommend that documentation follows the release cycle of whatever it is documenting, meaning that your subprojects should be free to follow their own release cycle.

This is solved by having an individual flyout menu active for the project that’s viewed. When the user navigates to a subproject, they are presented with a flyout menu matching the subproject’s versions and Offline formats (PDF, ePub, HTML).

Search

Search on the parent project will include results from its subprojects, and readers can filter results by subproject from the search modal. If you search on the v1 version of the parent project, results from the v1 version of its subprojects will be included, or from the default version for subprojects that don’t have a v1 version.

This is currently the only way to share search results between projects, we do not yet support sharing search results between sibling subprojects or arbitrary projects.

The subprojects filter in the search modal can be turned off from the parent project’s Settings, in the left bar, under Search, by disabling Show subprojects filter in search modal.

Localization and Internationalization

In this article, we explain high-level approaches to internationalizing and localizing your documentation.

By default, Read the Docs assumes that your documentation is or might become multilingual one day. The initial default language is English and therefore you often see the initial build of your documentation published at /en/latest/, where the /en denotes that it’s in English. By having the en URL component present from the beginning, you are ready for the eventuality that you would want a second language.

Read the Docs supports hosting your documentation in multiple languages. Read below for the various approaches that we support.

Projects with one language 

If your documentation isn’t in English (the default), you should indicate which language you have written it in.

It is easy to set the Language of your project. On the project Admin page (or Import page), simply select your desired Language from the dropdown. This will tell Read the Docs that your project is in the language. The language will be represented in the URL for your project.

For example, a project that is in Spanish will have a default URL of /es/latest/ instead of /en/latest/.

Projects with multiple translations 

See also

How to manage translations for Sphinx projects: Describes the whole process for a Sphinx documentation projects with multiples languages in the same repository and how to keep the translations updated on time.

Each language must have its own project on Read the Docs. You will choose one to be the parent project, and add each of the other projects as “Translations” of the parent project.

Let’s use godot as an example.

The godot project is the parent. Each translation then has its own project, for example godot-es. The Language for godot-es is set to Spanish. Then, on the Translations page of the godot project, godot-es is set as translation.

This has the results of serving:

godot at https://docs.godotengine.org/en/stable/
godot-es at https://docs.godotengine.org/es/stable/

It also gets included in the Read the Docs flyout menu:

Note

The default language of a custom domain is determined by the language of the parent project that the domain was configured on. See Custom domains for more information.

Translation workflows 

When you work with translations, the workflow of your translators becomes a critical component.

Considerations include:

Are your translators able to use a Git workflow? For instance, are they able to translate directly via GitHub?
Do you benefit from machine translation?
Do you need different roles, for instance do you need translators and editors?
What is your source language?
When are your translated versions published?

There are many translation platforms that support this workflow. These include:

Because Read the Docs builds your Git repository, you can use any of the above solutions. Any solution that synchronizes your translations with your Git repository will ensure that your translations are automatically published with Read the Docs.

URL versioning schemes

The URL versioning scheme of your project defines the URL of your documentation, and if your project supports multiple versions or translations.

Read the Docs supports three different versioning schemes:

Multiple versions with translations.
Multiple versions without translations.
Single version without translations.

See also

Versions: General explanation of how versioning works on Read the Docs.
URL path prefixes: Customize the URL structure of your documentation with custom path prefixes.

Multiple versions with translations

This is the default versioning scheme, it’s the recommend one if your project has multiple versions, and has or plans to support translations.

The URLs of your documentation will look like:

/en/latest/
/en/1.5/
/es/latest/install.html
/es/1.5/contributing.html

Multiple versions without translations

Use this versioning scheme if you want to have multiple versions of your documentation, but don’t want to have translations.

The URLs of your documentation will look like:

/latest/
/1.5/install.html

Warning

This means you can’t have translations for your documentation.

Single version without translations

Having a single version of a documentation project can be considered the better choice in cases where there should only always exist one unambiguous copy of your project. For example:

A research project may wish to only expose readers to their latest list of publications and research data.
A SaaS application might only ever have one version live.

The URLs of your documentation will look like:

/
/install.html

Warning

This means you can’t have translations or multiple versions for your documentation.

How to change the URL versioning scheme of your project

Changing the versioning scheme of your project will affect the URLs of your documentation, any existing links to your documentation will break. If you want to keep the old URLs working, you can create redirects.

Go the Admin tab of your project.
Click on Settings.
Select the new versioning scheme in the URL versioning scheme dropdown.
Click on Save.

Custom domains

By configuring a custom domain for your project, your project can serve documentation from a domain you control, for instance docs.example.com. This is great for maintaining a consistent brand for your product and its documentation.

Default subdomains

Without a custom domain configured, your project’s documentation is served from a Read the Docs domain using a unique subdomain for your project:

<project name>.readthedocs.io for Read the Docs Community.
<organization name>-<project name>.readthedocs-hosted.com for Read the Docs for Business. The addition of the organization name allows multiple organizations to have projects with the same name.

See also

How to manage custom domains: How to create and manage custom domains for your project.

Features

Automatic SSL: SSL certificates are automatically issued through Cloudflare for every custom domain. No extra set up is required beyond configuring your project’s custom domain.
CDN caching: Response caching is provided through a CDN for all documentation projects, including projects using a custom domain. CDN caching improves page response time for your documentation’s users, and the CDN edge network provides low latency response times regardless of location.
Multiple domains: Projects can be configured to be served from multiple domains, which always includes the project’s default subdomain. Only one domain can be configured as the canonical domain however, and any requests to non-canonical domains and subdomains will redirect to the canonical domain.
Canonical domains: The canonical domain configures the primary domain the documentation will serve from, and also sets the domain search engines use for search results when hosting from multiple domains. Projects can only have one canonical domain, which is the project’s default subdomain if no other canonical domain is defined.

See also

Canonical URLs: How canonical domains affect your project’s canonical URL, and why canonical URLs are important.
Subprojects: How to share a custom domain between multiple projects.

URL path prefixes

URL path prefixes allow you to customize the URL structure of your documentation, giving you more control over how your documentation is organized and presented.

Note

This is a Read the Docs for Business feature available on Pro and higher plans. Contact Read the Docs support to enable custom URL path prefixes for your project.

What are URL path prefixes?

By default, Read the Docs serves documentation from the following URL patterns:

Project type	Default URL pattern
Multi-version with translations	`/<language>/<version>/<filename>`
Multi-version without translations	`/<version>/<filename>`
Single version without translations	`/<filename>`
Subproject (multi-version with translations)	`/projects/<subproject-alias>/<language>/<version>/<filename>`
Subproject (multi-version without translations)	`/projects/<subproject-alias>/<version>/<filename>`
Subproject (single version without translations)	`/projects/<subproject-alias>/<filename>`

URL path prefixes let you customize these URL patterns by:

Adding a prefix to your project’s documentation URLs
Changing or removing the /projects/ prefix used for subprojects

Use cases

Here are some common scenarios where custom URL path prefixes are useful:

Proxy documentation behind your main website: If you want to serve your documentation as part of your main website (for example, at https://example.com/docs/), you can configure your web server to proxy requests to Read the Docs and use a custom prefix of /docs/ to match. Your documentation would then be served from https://example.com/docs/en/latest/ instead of https://example.com/en/latest/.
Remove or customize the /projects/ prefix from subproject URLs: By default, subprojects are served from URLs like https://docs.example.com/projects/plugin/en/latest/. You can change this prefix to something shorter or remove it entirely, so your subproject is served from https://docs.example.com/plugin/en/latest/ or https://docs.example.com/libs/plugin/en/latest/.
Organize documentation with meaningful URL paths: You can use prefixes to create a more meaningful URL structure. For example, you could use /api/ for API documentation and /guides/ for user guides.

Getting started

To enable this feature for your project:

Ensure you have a Pro plan or higher subscription.
Contact Read the Docs support with your project name and desired URL structure.
Our support team will configure the custom prefixes for your project.

Tip

When planning your URL structure, consider how it will affect existing links to your documentation. You may need to set up redirects to ensure old URLs continue to work.

See also

Subprojects: Learn how to set up subprojects and share a custom domain
Custom domains: Configure a custom domain for your documentation
URL versioning schemes: Learn about different URL versioning schemes

Documentation notifications

Documentation notifications alert users to information about the documentation they are viewing. These notifications can be enabled or disabled by the project maintainer, and are displayed to the user in the rendered documentation.

Overview

The current notifications are:

Pull request warning: Show a notification on builds from pull requests, with a link back to the pull request for giving feedback.
Latest version warning: Show a notification on latest version, warning users that they are reading docs from a development version.
Non-stable version warning: Show a notification on non-stable versions, warning users that they are reading docs from a non-stable release.

Manage notifications

To manage notifications for your project:

Go to the dashboard.
Click on a project name.
Go to Settings.
In the left bar, go to Addons.
Configure each Addon in the Notifications section.

Canonical URLs

A canonical URL allows you to specify the preferred version of a web page to prevent duplicated content. Here are some examples of when a canonical URL is used:

Search engines use your canonical URL to link users to the correct version and domain of your documentation.
Many popular chat clients and social media networks generate link previews, using your canonical URL as the final destination.

If canonical URLs aren’t used, it’s easy for outdated documentation to be the top search result for various pages in your documentation. This is not a perfect solution for this problem, but generally people finding outdated documentation is a big problem, and this is one of the suggested ways to solve it from search engines.

How Read the Docs generates canonical URLs

The canonical URL takes the following into account:

The default version of your project (usually “latest” or “stable”).
The canonical custom domain if you have one, otherwise the default subdomain will be used.

For example, if you have a project named example-docs with a custom domain https://docs.example.com, then your documentation will be served at https://example-docs.readthedocs.io and https://docs.example.com. Without specifying a canonical URL, a search engine like Google will index both domains.

You’ll want to use https://docs.example.com as your canonical domain. This means that when Google indexes a page like https://example-docs.readthedocs.io/en/latest/, it will know that it should really point at https://docs.example.com/en/latest/, thus avoiding duplicating the content.

Note

If you want your custom domain to be set as the canonical, you need to set Canonical: This domain is the primary one where the documentation is served from in the Admin > Domains section of your project settings.

How to specify the canonical URL

A canonical URL is automatically passed to the build process as READTHEDOCS_CANONICAL_URL environment variable. You can use this variable to configure your documentation tool to use it (eg. Sphinx does this via the html_baseurl config, MkDocs via site_url and Pelican with SITEURL)

Content Delivery Network (CDN) and caching

A CDN is used for making documentation pages fast for your users. CDNs increase speed by caching documentation content in multiple data centers around the world, and then serving docs from the data center closest to the user.

We support CDNs on both of our sites:

On Read the Docs Community,
we are able to provide a CDN to all the projects that we host. This service is graciously sponsored by Cloudflare.
On Read the Docs for Business,
the CDN is included as part of all of our plans. We use Cloudflare for this as well.

CDN benefits

Having a CDN in front of your documentation has many benefits:

Improved reliability: Since docs are served from multiple places, one can go down and the docs are still accessible.
Improved performance: Data takes time to travel across space, so connecting to a server closer to the user makes documentation load faster.

Automatic cache refresh

We automatically refresh the cache on the CDN when the following actions happen:

Your project is saved.
Your domain is saved.
A new version of your documentation is built.

By refreshing the cache according to these rules, readers should never see outdated content. This makes the end-user experience seamless and fast.

Sitemap support

Sitemaps allow you to inform search engines about URLs that are available for crawling. This makes your content more discoverable, and improves your Search Engine Optimization (SEO).

How it works

The sitemap.xml file is read by search engines to index your documentation. It contains information such as:

When a URL was last updated.
How often that URL changes.
How important this URL is in relation to other URLs on the site.
What translations are available for a page.

Read the Docs automatically generates a sitemap.xml for your project. The sitemap includes public and not hidden versions of your documentation and when they were last updated, sorted by version number.

This allows search engines to prioritize results based on the version number, sorted by semantic versioning.

Custom `sitemap.xml`

You can provide a custom sitemap.xml file with your docs build output. Read the Docs looks for this file in the default version of your project, because sitemap.xml is served from the root of your docs domain.

If this custom file exists, it is served as-is. If it does not exist, Read the Docs serves the generated sitemap instead.

You can also point crawlers to a different sitemap URL via robots.txt. See robots.txt support for details.

For example, in robots.txt:

User-agent: *
Allow: /

Sitemap: https://docs.example.com/en/stable/sitemap.xml

`404 Not Found` pages

If you want your project to use a custom or branded 404 Not Found page, you can put a 404.html or 404/index.html at the top level of your project’s HTML output.

How it works

When our servers return a 404 Not Found error, we check if there is a 404.html or 404/index.html in the root of your project’s output.

The following locations are checked, in order:

/404.html or 404/index.html in the current documentation version.
/404.html or 404/index.html in the default documentation version.

Tool integration

Documentation tools will have different ways of generating a 404.html or 404/index.html file. We have examples for some of the most popular tools below.

We recommend the sphinx-notfound-page extension, which Read the Docs maintains. It automatically creates a 404.html page for your documentation, matching the theme of your project. See its documentation for how to install and customize it.

If you want to create a custom 404.html, Sphinx uses the html_extra_path option to add static files to the output. You need to create a 404.html file and put it under the path defined in html_extra_path.

If you are using the DirHTML builder, no further steps are required. Sphinx will automatically apply the <page-name>/index.html folder structure to your 404 page: 404/index.html. Read the Docs also detects 404 pages named this way.

MkDocs automatically generates a 404.html which Read the Docs will use. However, assets will not be loaded correctly unless you define the site_url configuration value as your site’s canonical base URL.

`robots.txt` support

The robots.txt files allow you to customize how your documentation is indexed in search engines. It’s useful for:

Hiding various pages from search engines
Disabling certain web crawlers from accessing your documentation
Disallowing any indexing of your documentation

Read the Docs automatically generates one for you with a configuration that works for most projects. By default, the automatically created robots.txt:

Hides versions which are set to Hidden from being indexed.
Allows indexing of all other versions.

Warning

robots.txt files are respected by most search engines, but they aren’t a guarantee that your pages will not be indexed. Search engines may choose to ignore your robots.txt file, and index your docs anyway.

If you require private documentation, please see Sharing private documentation.

How it works

You can customize this file to add more rules to it. The robots.txt file will be served from the default version of your project. This is because the robots.txt file is served at the top-level of your domain, so we must choose a version to find the file in. The default version is the best place to look for it.

Tool integration

Documentation tools will have different ways of generating a robots.txt file. We have examples for some of the most popular tools below.

Sphinx uses the html_extra_path configuration value to add static files to its final HTML output. You need to create a robots.txt file and put it under the path defined in html_extra_path.

MkDocs needs the robots.txt to be at the directory defined by the docs_dir configuration value.

`llms.txt` support

The llms.txt file is a standard for providing LLM-friendly content to AI assistants and other language models. It allows you to provide a custom file that:

Gives AI models structured information about your documentation
Helps AI understand your project’s structure and content
Provides a more focused view of your documentation for AI consumption

Read the Docs supports serving custom llms.txt files from your documentation.

How it works

The llms.txt file will be served from the default version of your project at https://your-project.readthedocs.io/llms.txt. This is because the llms.txt file is served at the top-level of your domain, so we must choose a version to find the file in. The default version is the best place to look for it.

If you also provide a llms-full.txt file, Read the Docs will serve it from https://your-project.readthedocs.io/llms-full.txt using the same rules.

To use this feature:

Create a llms.txt file in your documentation source
Configure your documentation tool to include it in the build output
Read the Docs will automatically serve it at the root of your domain

Note

The llms.txt file will only be served if:

Your default version is public
Your default version is active
Your default version has been built
The llms.txt file exists in your build output

Tool integration

Documentation tools will have different ways of generating a llms.txt file. We have examples for some of the most popular tools below.

Sphinx uses the html_extra_path configuration value to add static files to its final HTML output. You need to create a llms.txt file and put it under the path defined in html_extra_path.

You can also use the sphinx-llm extension to automatically generate an llms.txt file from your documentation.

MkDocs needs the llms.txt to be at the directory defined by the docs_dir configuration value.

You can also use the mkdocs-llmstxt plugin to automatically generate an llms.txt file from your documentation.

Alternative: Using redirects

If you want to serve your llms.txt file from a versioned path (like /en/latest/llms.txt), you can create an exact redirect from /llms.txt to /en/latest/llms.txt. This gives you more control over which version serves the file.

Markdown for AI agents: Read the Docs also serves a Markdown version of your documentation pages to AI agents that request it, via content negotiation.

Markdown for AI agents

Read the Docs serves a Markdown version of documentation pages to clients that request it, using HTTP content negotiation. Markdown is smaller and easier to parse than rendered HTML, which makes it a better format for AI agents and language models to consume.

This feature is enabled automatically on all documentation domains hosted on Read the Docs, with no configuration required. Browsers continue to receive the regular HTML version of your documentation.

A request with Accept: text/markdown returns a Markdown response:

$ curl -i https://docs.readthedocs.com/platform/stable/ -H "Accept: text/markdown"
HTTP/2 200
content-type: text/markdown; charset=utf-8
vary: accept
x-markdown-tokens: 1496
content-signal: ai-train=yes, search=yes, ai-input=yes

---
description: Automate building, versioning, and hosting of your technical documentation continuously on Read the Docs.
title: Read the Docs: documentation simplified
---

...

This feature is powered by Cloudflare. See the Cloudflare blog post on Markdown for agents for more details about how the conversion works.

See also

llms.txt support: Serve a custom llms.txt file to guide AI agents to the most relevant pages of your documentation.
AI agent skills: Use Read the Docs Agent Skills to help AI agents work with Read the Docs APIs and configuration.

Offline formats (PDF, ePub, HTML)

This page will provide an overview of a core Read the Docs feature: building docs in multiple formats.

Read the Docs supports the following formats by default:

PDF
ePub
Zipped HTML

This means that every commit that you push will automatically update your offline formats as well as your documentation website.

Use cases

This functionality is great for anyone who needs documentation when they aren’t connected to the internet. Users who are about to get on a plane can grab a single file and have the entire documentation during their trip. Many academic and scientific projects benefit from these additional formats.

PDF versions are also helpful to automatically create printable versions of your documentation. The source of your documentation will be structured to support both online and offline formats. This means that a documentation project displayed as a website can be downloaded as a PDF, ready to be printed as a report or a book.

Offline formats also support having the entire documentation in a single file. Your entire documentation can now be delivered as an email attachment, uploaded to an eReader, or accessed and searched locally without online latency. This makes your documentation project easy to redistribute or archive.

Accessing offline formats

You can download offline formats in the Project dashboard > Downloads:

When you are browsing a documentation project, they can also be accessed directly from the Flyout menu.

Examples

If you want to see an example, you can download the Read the Docs documentation in the following formats:

ePub

Zipped HTML

Continue learning

Downloadable documentation formats are built by your documentation framework. They are then published by Read the Docs and included in your Flyout menu. Therefore, it’s your framework that decides exactly how each output is built and which formats are supported:

Sphinx: All output formats are built mostly lossless from the documentation source, meaning that your documentation source (reStructuredText or Markdown/MyST) is built from scratch for each output format.
MkDocs and Docsify + more: The common case for most documentation frameworks is that several alternative extensions exist supporting various output formats. Most of the extensions export the HTML outputs as another format (for instance PDF) through a conversion process.

Because Sphinx supports the generation of offline formats through an official process, we are also able to support it officially. Other alternatives can also work, provided that you identify which extension you want to use and configure the environment for it to run. Other formats aren’t natively supported by Read the Docs, but support is coming soon.

See also

Other pages in our documentation are relevant to this feature, and might be a useful next step.

How to enable offline formats - Guide to enabling and disabling this feature.
formats - Configuration file options for offline formats.
Where to put files - Where to put offline format output when using custom build commands.

Visual diff

Get a list of documentation files that changed between the pull request and the latest version of the documentation, and see their differences highlighted visually on the documentation pages.

While seeing changes in source files is helpful, it can be difficult to understand how those changes will look in the rendered documentation, or their impact on the documentation as a whole. Read the Docs makes it easy to see the changes in the rendered documentation.

Show diff menu in preview

To enable or disable this feature for your project:

Go the Settings tab of your project.
Click on Addons, and click on Visual diff.
Check or uncheck the Enable visual diff option.
Click on Save.

When enabled, a new UI element appears at the top right of the page showing a dropdown selector containing all the files that have changed in that pull request build.

You can select any of those files from the dropdown to jump directly into that page. Once there, you can toggle Visual Diff on and off by pressing the Show diff link from the UI element, or pressing the d key if you have hotkeys enabled.

Visual diff shows all the sections that have changed, highlighting their differences with red/green background colors. You can jump between each of these chunks by clinking on the up/down arrows.

Show build overview in pull requests

Note

This feature is only available for projects connected to a GitHub App.

To enable or disable this feature for your project:

Go the Settings tab of your project.
Click on Pull request builds.
Check or uncheck the Show build overview in a comment option.
Click on Update.

When enabled, a comment is added to the pull request when changes are detected between the pull request and the latest version of the documentation.

General settings

Ignored files

You can configure a list of files or patterns to be ignored when listing the files that changed in the pull request. This is useful when you have files that have a date in them, or listing/archive files that show changes without content changes in those files.

Go the Settings tab of your project.
Click on Addons, and click on File tree diff.
In the Ignored files field, add one or more patterns to ignore, one per line.
Click on Save.

Patterns are matched against the relative paths of the HTML files produced by the build, you should try to match index.html, not docs/index.rst, nor /en/latest/index.html. Patterns can include one or more of the following special characters:

* matches everything, including slashes.
? matches any single character.
[seq] matches any character in seq.

Base version

The base version is the version of the documentation that is used to compare against the pull request. By default, this is the latest version of the documentation. This is useful if your latest version doesn’t point the default branch of your repository.

Note

This option can be changed by contacting Site support.

When the first successful build of a pull request runs, Read the Docs takes a snapshot of the base version’s current file manifest and pins it as the baseline for that pull request. Subsequent builds of the pull request are compared against this pinned snapshot instead of whatever the base version happens to contain at that moment. This prevents unrelated files from appearing as changed when the base branch moves forward while the pull request is open.

How main content is detected

The visual diff compares the “main content” of HTML pages, ignoring headers, footers, navigation, and other page elements that aren’t part of the documentation content itself. This helps avoid false positives, like all pages being marked as changed because of a date or commit hash being updated in the footer.

For details on how the main content area is detected, see Detection logic.

Tip

If the heuristic root element picked by Visual Diff is wrong for your project theme, set the CSS main content selector under Settings > Addons. Visual Diff honors this override; other features like Server Side Search do not.

Limitations and known issues

The diff considers HTML files only.
The diff is done between the files from the latest successful build of the pull request and the default base version (latest by default). A snapshot of the base version’s manifest is saved on the first successful build of the pull request, so the diff stays stable as the base branch moves forward. If the pull request is later updated against a newer base, the snapshot is not currently refreshed automatically, and the diff may show stale differences until this is addressed in a future update.
Invisible changes. Some sections may be highlighted as changed, even when they haven’t actually visually changed. This can happen when the underlying HTML changes without a corresponding visual change, for example, if a link’s URL is updated
Tables may be shown to have changes when they have not actually changed. This is due to subtle variations in how HTML tables are rendered, and will be fixed in a future version.
The background of diff chunks may be incorrect when we are unable to detect the correct main parent element for the chunk.

Link previews

Link previews allows you to see the content of the link you are about to click when you hover over it. This gives you the ability to quickly preview where a link points, so you can keep your context while reading but learn more from other resources.

Link previews will only be generated for internal links–links that point to pages within your documentation site. No link previews will be generated for links to external sites or links that appear outside of the primary content of the documentation page (eg. nav bars).

You can see an example of a link preview by hovering over the following link: Addons.

Enabling link previews

Go to the new dashboard.
Click on a project name.
Go to Settings, then in the left bar, go to Addons.
Go to Link previews and check Enabled.
Save your settings – a rebuild of your project isn’t required!

Troubleshooting link previews

We perform some heuristic to detect the documentation tool used to generate the page based on its HTML structure. This auto-detection may fail, resulting in the content rendered inside the popup being incorrect. If you are experiencing this, you can specify the CSS selector for the main content in Settings > Addons > Advanced. See Detection logic for how this content is detected and guidance on choosing a good selector. You can also open an issue in the addons repository so we improve our heuristic.

Link previews won’t be generated if JavaScript is not enabled in your web browser or if all cookies are blocked.

How to embed content from your documentation

Read the Docs allows you to embed content from any of the projects we host and specific allowed external domains (currently, docs.python.org, docs.scipy.org, docs.sympy.org, numpy.org) This allows reuse of content across sites, making sure the content is always up to date.

There are a number of use cases for embedding content, so we’ve built our integration in a way that enables users to build on top of it. This guide will show you some of our favorite integrations:

Contextualized tooltips on documentation pages 

Tooltips on your own documentation are really useful to add more context to the current page the user is reading. You can embed any content that is available via an HTML id.

We built an addon called Link previews on top of our Embed API that you can enable from the addons settings of your project using the dashboard.

Inline help on application website 

This allows us to keep the official documentation as the single source of truth, while having great inline help in our application website as well. On the “Automation Rules” admin page we could embed the content of our Automation rules documentation page and be sure it will be always up to date.

Note

We recommend you point at tagged releases instead of latest. Tags don’t change over time, so you don’t have to worry about the content you are embedding disappearing.

The following example will fetch the section “Creating an automation rule” in page automation-rules.html from our own docs and will populate the content of it into the #help-container div element.

<script type="text/javascript">
var params = {
  'url': 'https://docs.readthedocs.io/en/latest/automation-rules.html%23creating-an-automation-rule',
  // 'doctool': 'sphinx',
  // 'doctoolversion': '4.2.0',
  // 'maincontent': 'div#main',
};
var url = 'https://app.readthedocs.org/api/v3/embed/?' + $.param(params);
$.get(url, function(data) {
  $('#help-container').content(data['content']);
});
</script>

<div id="help-container"></div>

You can modify this example to subscribe to .onclick Javascript event, and show a modal when the user clicks in a “Help” link.

Tip

Take into account that if the title changes, your section argument will break. To avoid that, you can manually define Sphinx references above the sections you don’t want to break. For example,

.. in your .rst document file

.. _unbreakable-section-reference:

Creating an automation rule
---------------------------

This is the text of the section.

.. in your .md document file

(unbreakable-section-reference)=
## Creating an automation rule

This is the text of the section.

To link to the section “Creating an automation rule” you can send section=unbreakable-section-reference. If you change the title it won’t break the embedded content because the label for that title will still be unbreakable-section-reference.

Please, take a look at the Sphinx :ref: role documentation for more information about how to create references.

Calling the Embed API directly 

Embed API lives under https://app.readthedocs.org/api/v3/embed/ URL and accept the URL of the content you want to embed. Take a look at its own documentation to find out more details.

You can click on the following links and check a live response directly in the browser as examples:

Note

All relative links to pages contained in the remote content will continue to point at the remote page.

Server side search

Read the Docs provides full-text search across all of the pages of all projects, this is powered by Elasticsearch.

See also

Search query syntax: Syntax options for searching Read the Docs projects
Server side search API: Reference to the Server Side Search API

Search features

Read the Docs has the following search features:

Search across subprojects

Subprojects allow you to host multiple discrete projects on a single domain. Every subproject hosted on that same domain is included in the search results of the main project.

Search results land on the exact content you were looking for

We index every heading in the document, allowing you to get search results exactly to the content that you are searching for. Try this out by searching for “full-text search”.

Full control over which results should be listed first

Set a custom rank per page, allowing you to deprecate content, and always show relevant content to your users first. See search.ranking.

Search across projects you have access to

Search across all the projects you have access to in your Dashboard. Don’t remember where you found that document the other day? No problem, you can search across them all.

You can also specify what projects you want to search using the project:{name} syntax, for example: “project:docs project:dev search”. See Search query syntax.

Special query syntax for more specific results

We support a full range of search queries. You can see some examples at Special queries.

Configurable

Tweak search results according to your needs using a configuration file. You can also enable or disable the search modal, and toggle the subprojects filter shown inside it, from your project’s Settings, in the left bar, under Search.

Ready to use

We override the default search engine of your Sphinx project with ours to provide you with all these benefits within your project. We fallback to the built-in search engine from your project if ours doesn’t return any results, just in case we missed something 😄.

API

Integrate our search as you like. See Server side search API.

Analytics

Know what your users are searching for. See Search analytics

Search as you type

Search as-you-type allows users to quickly find exactly what they are looking for while typing. It also saves recent searches, for future reference.

Try it by pressing / (forward slash) and typing.

Configuring search

You can configure search options for your project from the dashboard:

Go to the dashboard.
Click on a project name.
Go to Settings.
In the left bar, go to Search.

From there you can toggle Enable search modal, which controls whether the Read the Docs search modal is shown in your documentation, and Show subprojects filter in search modal, which controls whether readers can filter search results by subproject.

How main content is detected

Server Side Search indexes the “main content” of HTML pages, ignoring headers, footers, navigation, and other page elements that aren’t part of the documentation content itself. This keeps results focused and avoids repeated elements like nav menus from polluting relevance.

For details on how the main content area is detected, see Detection logic.

Search query syntax

When searching on Read the Docs with server side search, you can use some parameters in your query in order to search on given projects, versions, or to get more accurate results.

Parameters

Parameters are in the form of name:value, they can appear anywhere in the query, and depending on the parameter, you can use one or more of them.

Any other text that isn’t a parameter will be part of the search query. If you don’t want your search term to be interpreted as a parameter, you can escape it like project\:docs.

Note

Unknown parameters like foo:bar don’t require escaping.

The available parameters are:

project

Indicates the project and version to include results from (this doesn’t include subprojects or translations). If the version isn’t provided, the default version will be used. More than one parameter can be included.

Examples:

project:docs test
project:docs/latest test
project:docs/stable project:dev test

subprojects

Include results from the given project and its subprojects. If the version isn’t provided, the default version of all projects will be used. If a version is provided, all subprojects matching that version will be included, and if they don’t have a version with that name, we use their default version. More than one parameter can be included.

Examples:

subprojects:docs test
subprojects:docs/latest test
subprojects:docs/stable subprojects:dev test

user

Include results from projects the given user has access to. The only supported value is @me, which is an alias for the current user. Only one parameter can be included. If duplicated, the last one will override the previous one.

Examples:

user:@me test

Permissions

If the user doesn’t have permission over one version, or if the version doesn’t exist, we don’t include results from that version.

The API will return all the projects that were used in the final search, with that information you can check which projects were used in the search.

Limitations

In order to keep our search usable for everyone, you can search up to 100 projects at a time. If the resulting query includes more than 100 projects, they will be omitted from the final search.

This syntax is only available when using our search API V3 or when using the global search (https://app.readthedocs.org/search/).

Searching multiple versions of the same project isn’t supported, the last version will override the previous one.

Special queries

Read the Docs uses the Simple Query String feature from Elasticsearch. This means that as the search query becomes more complex, the results yielded become more specific.

Exact phrase search

If a query is wrapped in " (double quotes), then only those results where the phrase is exactly matched will be returned.

Examples:

"custom css"
"adding a subproject"
"when a 404 is returned"

Prefix query

* (asterisk) at the end of any term signifies a prefix query. It returns the results containing the words with the specific prefix.

Examples:

test*
build*

Fuzziness

~N (tilde followed by a number) after a word indicates edit distance (fuzziness). This type of query is helpful when the exact spelling of the keyword is unknown. It returns results that contain terms similar to the search term.

Examples:

doks~1
test~2
getter~2

Words close to each other

~N (tilde followed by a number) after a phrase can be used to match words that are near to each other.

Examples:

"dashboard admin"~2
"single documentation"~1
"read the docs policy"~5

Redirects

Over time, a documentation project may want to rename and move contents around. Redirects allow changes in a documentation project to happen without bad user experiences.

If you do not manage URL structures, users will eventually encounter 404 File Not Found errors. While this may be acceptable in some cases, the bad user experience of a 404 page is usually best to avoid.

Built-in redirects ⬇️: Allows for simple and long-term sharing of external references to your documentation.
User-defined redirects ⬇️: Makes it easier to move contents around

See also

How to use custom URL redirects in documentation projects: This guide shows you how to add redirects with practical examples.
Best practices for linking to your documentation: Information and tips about creating and handling external references.
How to deprecate content: A guide to deprecating features and other topics in a documentation.

Built-in redirects

This section explains the redirects that are automatically active for all projects and how they are useful. Built-in redirects are especially useful for creating and sharing incoming links, which is discussed in depth in Best practices for linking to your documentation.

Page redirects at `/page/`

You can link to a specific page and have it redirect to your default version, allowing you to create links on external sources that are always up to date. This is done with the /page/ URL prefix.

For instance, you can reach the page you are reading now by going to https://docs.readthedocs.io/page/guides/best-practice/links.html.

Another way to handle this is the latest version. You can set your latest version to a specific version and just always link to latest. You can reach this page by going to https://docs.readthedocs.io/en/latest/guides/best-practice/links.html.

Root URL redirect at `/`

A link to the root of your documentation (<slug>.readthedocs.io/) will redirect to the default version, as set in your project settings.

This works for both readthedocs.io (Read the Docs Community), readthedocs-hosted.com (Read the Docs for Business), and custom domains.

For example:

docs.readthedocs.io -> docs.readthedocs.io/en/stable/

Warning

You cannot use the root redirect to reference specific pages. / only redirects to the default version, whereas /some/page.html will not redirect to /en/latest/some/page.html. Instead, use Page redirects at /page/.

You can choose which is the default version for Read the Docs to display. This usually corresponds to the most recent official release from your project.

Root language redirect at `/<lang>/`

A link to the root language of your documentation (<slug>.readthedocs.io/en/) will redirect to the default version of that language.

For example, accessing the English language of the project will redirect you to the its default version (stable):

https://docs.readthedocs.io/en/ -> https://docs.readthedocs.io/en/stable/

Shortlink with `https://<slug>.rtfd.io`

Links to rtfd.io are treated the same way as readthedocs.io. They are intended to be easy and short for people to type.

You can reach these docs at https://docs.rtfd.io.

User-defined redirects

Page redirects

Page Redirects let you redirect a page across all versions of your documentation.

Note

Since page redirects apply to all versions of a project, From URL doesn’t need to include the /<language>/<version> prefix (for example, /en/latest), only the path to the page. Page redirects don’t apply to translations or subprojects, which need their own redirect rules. If you need a redirect for a specific language or version URL, use Exact redirects with the fully-specified path.

Exact redirects

Exact Redirects take into account the full URL (including language and version), allowing you to create a redirect for a specific version or language of your documentation.

Clean/HTML URLs redirects

If you decide to change the style of the URLs of your documentation, you can use Clean URL to HTML or HTML to clean URL redirects to redirect users to the new URL style.

For example, if a previous page was at /en/latest/install.html, and now is served at /en/latest/install/, or vice versa, users will be redirected to the new URL.

Limitations and observations

Read the Docs Community users are limited to 100 redirects per project, and Read the Docs for Business users have a number of redirects limited by their plan.
By default, redirects only apply on pages that don’t exist. Forced redirects allow you to apply redirects on existing pages.
Redirects aren’t applied on previews of pull requests. You should treat these domains as ephemeral and not rely on them for user-facing content.
You can redirect to URLs outside Read the Docs, just include the protocol in To URL, e.g https://example.com.
A wildcard can be used at the end of From URL (suffix wildcard) to redirect all pages matching a prefix. Prefix and infix wildcards are not supported.
If a wildcard is used in From URL, the part of the URL that matches the wildcard can be used in To URL with the :splat placeholder.
Redirects without a wildcard match paths with or without a trailing slash, e.g. /install matches /install and /install/.
The order of redirects matters. If multiple redirects match the same URL, the first one will be applied. The order of redirects can be changed from your project’s dashboard.
If an infinite redirect is detected, a 404 error will be returned, and no other redirects will be applied.

Examples

Redirecting a page

Say you move the example.html page into a subdirectory of examples: examples/intro.html. You can create a redirect with the following configuration:

Type: Page Redirect
From URL: /example.html
To URL: /examples/intro.html

Users will now be redirected:

From https://docs.example.com/en/latest/example.html to https://docs.example.com/en/latest/examples/intro.html.
From https://docs.example.com/en/stable/example.html to https://docs.example.com/en/stable/examples/intro.html.

If you want this redirect to apply to a specific version of your documentation, you can create a redirect with the following configuration:

Type: Exact Redirect
From URL: /en/latest/example.html
To URL: /en/latest/examples/intro.html

Note

Use the desired version and language instead of latest and en.

Redirecting a directory

Say you rename the /api/ directory to /api/v1/. Instead of creating a redirect for each page in the directory, you can use a wildcard to redirect all pages in that directory:

Type: Page Redirect
From URL: /api/*
To URL: /api/v1/:splat

Users will now be redirected:

From https://docs.example.com/en/latest/api/ to https://docs.example.com/en/latest/api/v1/.
From https://docs.example.com/en/latest/api/projects.html to https://docs.example.com/en/latest/api/v1/projects.html.

If you want this redirect to apply to a specific version of your documentation, you can create a redirect with the following configuration:

Type: Exact Redirect
From URL: /en/latest/api/*
To URL: /en/latest/api/v1/:splat

Note

Use the desired version and language instead of latest and en.

Redirecting a directory to a single page

Say you put the contents of the /examples/ directory into a single page at /examples.html. You can use a wildcard to redirect all pages in that directory to the new page:

Type: Page Redirect
From URL: /examples/*
To URL: /examples.html

Users will now be redirected:

From https://docs.example.com/en/latest/examples/ to https://docs.example.com/en/latest/examples.html.
From https://docs.example.com/en/latest/examples/intro.html to https://docs.example.com/en/latest/examples.html.

If you want this redirect to apply to a specific version of your documentation, you can create a redirect with the following configuration:

Type: Exact Redirect
From URL: /en/latest/examples/*
To URL: /en/latest/examples.html

Note

Use the desired version and language instead of latest and en.

Redirecting a page to the latest version

Say you want your users to always be redirected to the latest version of a page, your security policy (/security.html) for example. You can use a wildcard with a forced redirect to redirect all versions of that page to the latest version:

Type: Page Redirect
From URL: /security.html
To URL: https://docs.example.com/en/latest/security.html
Force Redirect: True

Users will now be redirected:

From https://docs.example.com/en/v1.0/security.html to https://docs.example.com/en/latest/security.html.
From https://docs.example.com/en/v2.5/security.html to https://docs.example.com/en/latest/security.html.

Note

To URL includes the domain, this is required, otherwise the redirect will be relative to the current version, resulting in a redirect to https://docs.example.com/en/v1.0/en/latest/security.html.

Redirecting an old version to a new one

Let’s say that you want to redirect your readers of your version 2.0 of your documentation under /en/2.0/ because it’s deprecated, to the newest 3.0 version of it at /en/3.0/. You can use an exact redirect to do so:

Type: Exact Redirect
From URL: /en/2.0/*
To URL: /en/3.0/:splat

Users will now be redirected:

From https://docs.example.com/en/2.0/dev/install.html to https://docs.example.com/en/3.0/dev/install.html.

Note

For this redirect to work, your old version must be disabled, if the version is still active, you can use the Force Redirect option.

Creating a shortlink

Say you want to redirect https://docs.example.com/security to https://docs.example.com/en/latest/security.html, so it’s easier to share the link to the page. You can create a redirect with the following configuration:

Type: Exact Redirect
From URL: /security
To URL: /en/latest/security.html

Users will now be redirected:

From https://docs.example.com/security (no trailing slash) to https://docs.example.com/en/latest/security.html.
From https://docs.example.com/security/ (trailing slash) to https://docs.example.com/en/latest/security.html.

Migrating your docs to Read the Docs

Say that you previously had your docs hosted at https://docs.example.com/dev/, and choose to migrate to Read the Docs with support for multiple versions and translations. Your documentation will now be served at https://docs.example.com/en/latest/, but your users may have bookmarks saved with the old URL structure, for example https://docs.example.com/dev/install.html.

You can use an exact redirect with a wildcard to redirect all pages from the old URL structure to the new one:

Type: Exact Redirect
From URL: /dev/*
To URL: /en/latest/:splat

Users will now be redirected:

From https://docs.example.com/dev/install.html to https://docs.example.com/en/latest/install.html.

Migrating your documentation to another domain

You can use an exact redirect with the force option to migrate your documentation to another domain, for example:

Type: Exact Redirect
From URL: /*
To URL: https://newdocs.example.com/:splat
Force Redirect: True

Users will now be redirected:

From https://docs.example.com/en/latest/install.html to https://newdocs.example.com/en/latest/install.html.

Changing your Sphinx builder from `html` to `dirhtml`

When you change your Sphinx builder from html to dirhtml, all your URLs will change from /page.html to /page/. You can create a redirect of type HTML to clean URL to redirect all your old URLs to the new style.

Traffic analytics

Read the Docs aggregates statistics about visits to your documentation. This is mainly information about how often pages are viewed, and which return a 404 Not Found error code.

Traffic analytics let you see which documents your users are reading. This allows you to understand how your documentation is being used, so you can focus on expanding and updating parts people are reading most.

To see a list of the top pages from the last month, go to the Settings tab of your project, and then click on Traffic analytics under Maintaining.

Enabling traffic analytics

Go to the new dashboard.
Click on a project name.
Go to Settings, then in the left bar, go to Addons.
Go to Analytics and check Analytics enabled.

Data storage

The duration of analytics data stored depends on which site you’re using:

On Read the Docs Community, the last 90 days are stored.
On Read the Docs for Business, storage duration starts at 30 days and increases with plan level.

See also

Our plan pricing: Compare our plan pricing and analytics storage duration.
Search analytics: See what users are searching for in your documentation.

Search analytics

When someone visits your documentation and uses the built-in server side search feature, Read the Docs will collect analytics on their search queries.

These are aggregated into a simple view of the “Top queries in the past 30 days”. You can also download this data.

This is helpful to optimize your documentation in alignment with your readers’ interests. You can discover new trends and expand your documentation to new needs.

Using search analytics

To see a list of the top queries and an overview from the last month, go to the Admin tab of your project, and then click on Search Analytics.

In Top queries in the past 30 days, you see all the latest searches ordered by their popularity. The list itself is often longer than what meets the eye, Scroll downwards on the list itself to see more results.

Understanding your analytics

In Top queries in the past 30 days, you can see the most popular terms that users have searched for. Next to the search query, the number of actual results for that query is shown. The number of times the query has been used in a search is displayed as the searches number.

If you see a search term that doesn’t have any results, you could apply that term in documentation articles or create new ones. This is a great way to understand missing gaps in your documentation.
If a search term is often used but the documentation article exists, it can also indicate that it’s hard to navigate to the article.
Repeat the search yourself and inspect the results to see if they are relevant. You can add keywords to various pages that you want to show up for searches on that page.

In Daily search totals, you can see trends that might match special events in your project’s publicity. If you wish to analyze these numbers in details, click Download all data to get a CSV formatted file with all available search analytics.

Data storage

The duration of analytics data stored depends on which site you’re using:

On Read the Docs Community, the last 90 days are stored.
On Read the Docs for Business, storage duration starts at 30 days and increases with plan level.

See also

Our plan pricing: Compare our plan pricing and analytics storage duration.
Traffic analytics: See how users are using your documentation.

Security logs

Security logs allow you to audit what has happened recently in your organization or account. This feature is quite important for many security compliance programs, as well as the general peace of mind of knowing what is happening on your account. We store the IP address and the browser used on each event, so that you can confirm this access was from the intended person.

Security logs are only visible to organization owners. You can invite other team members as owners.

See also

Security policy: General information and reference about how security is handled on Read the Docs.

User security log

We store a user security log for the latest 90 days of activity. This log is useful to validate that no unauthorized events have occurred.

The security log tracks the following events:

Authentication on the dashboard.
Authentication on documentation pages (Business hosting only).
When invitations to manage a project are sent, accepted, revoked or declined.

Authentication failures and successes are both tracked.

Logs are available in <Username dropdown> ‣ Settings ‣ Security Log.

Organization security log

Note

This feature is only available on Read the Docs for Business.

The length of log storage varies with your plan, check our pricing page for more details. Your organization security log is a great place to check periodically to ensure there hasn’t been unauthorized access to your organization.

Organization logs track the following events:

Authentication on documentation pages from your organization.
User accesses a documentation page from your organization (Enterprise plans only).
User accesses a documentation’s downloadable formats (Enterprise plans only).
Invitations to organization teams are sent, revoked or accepted.

Authentication failures and successes are both tracked.

Logs are available in <Username dropdown> ‣ Organizations ‣ <Organization name> ‣ Settings ‣ Security Log.

If you have any additional information that you wished the security log was capturing, you can always reach out to Site support.

See also

Security reports: Security information related to our own platform, personal data treatment, and how to report a security issue.

Status badges

Status badges let you show the state of your documentation to your users. They will show if the latest build has passed, failed, or is in an unknown state. They are great for embedding in your README, or putting inside your actual doc pages.

You can see a badge in action in the Read the Docs README.

Display states

Badges have the following states which can be shown to users:

Green: passing - the last build was successful.
Red: failing - the last build failed.
Yellow: unknown - we couldn’t figure out the status of your last build.

An example of each is shown here:

green red yellow

Automatically generated

On the dashboard of a project, an example badge is displayed together with code snippets for reStructuredText, Markdown, and HTML.

Badges are generated on-demand for all Read the Docs projects, using the following URL syntax:

https://app.readthedocs.org/projects/<project-slug>/badge/?version=<version>&style=<style>

Style

You can pass the style GET argument to get custom styled badges. This allows you to match the look and feel of your website. By default, the flat style is used.

Style	Badge
flat - default
flat-square
for-the-badge
plastic
social

Version-specific badges

You can change the version of the documentation your badge points to. To do this, you can pass the version GET argument to the badge URL. By default, it will point at the default version you have specified for your project.

The badge URL looks like this:

https://app.readthedocs.org/projects/<project-slug>/badge/?version=latest

Badges on dashboard pages

On each project home page there is a badge that communicates the status of the default version. If you click on the badge icon, you will be given snippets for reStructuredText, Markdown, and HTML to make embedding it easier.

Badges for private projects

Note

This feature is only available on Read the Docs for Business.

For private projects, a badge URL cannot be guessed. A token is needed to display it. Private badge URLs are displayed on a private project’s dashboard in place of public URLs.

How to structure your documentation

A documentation project’s ultimate goal is to be read and understood by a reader. Readers need to be able to discover the information that they need. Without an defined structure, readers either won’t find information that they need or get frustrated on the way.

One of the largest benefits of a good structure is that it removes questions that keep authors from writing documentation. Starting with a blank page is often the hardest part of documentation, so anything we can do to remove this problem is a win.

Choosing a structure

Good news! You don’t have to invent all of the structure yourself, since a lot of experience-based work has been done to come up with a universal documentation structure.

In order to avoid starting with a blank page, we recommend a simple process:

Choose a structure for your documentation. We recommend Diátaxis for this.
Find a example project or template to start from.
Start writing by filling in the structure.

This process helps you get started quickly, and helps keep things consistent for the reader of your documentation.

Diátaxis Methodology

The documentation you’re reading is written using the Diátaxis framework. It has four major parts as summarized by this image:

https://diataxis.fr/_images/diataxis.png

We recommend that you read more about it in the official Diátaxis documentation.

Explaining the structure to your users

One of the benefits of Diátaxis is that it’s a well-known structure, and users might already be familiar with it. As long as you stick to the structure, your users should be able to use existing experience to navigate.

Using the names that are defined (eg. Tutorials, Explanation) in a user-facing way also helps here.

Best practices for linking to your documentation

Once you start to publish documentation, external sources will inevitably link to specific pages in your documentation.

Sources of incoming links vary greatly depending on the type of documentation project that is published. They can include everything from old emails to GitHub issues, wiki articles, software comments, PDF publications, or StackOverflow answers. Most of these incoming sources are not in your control.

Read the Docs makes it easier to create and manage incoming links by redirecting certain URLs automatically and giving you access to define your own redirects.

In this article, we explain how our built-in redirects work and what we consider “best practice” for managing incoming links.

See also

Versions: Read more about how to handle versioned documentation and URL structures.
Redirects: Overview of all the redirect features available on Read the Docs. Many of the redirect features are useful either for building external links or handling requests to old URLs.
How to use custom URL redirects in documentation projects: How to add a user-defined redirect, step-by-step. Useful if your content changes location!

Best practice: “permalink” your pages

You might be familiar with the concept of permalinks from blogging. The idea is that a blog post receives a unique link as soon as it’s published and that the link does not change afterward. Incoming sources can reference the blog post even though the blog changes structure or the post title changes.

When creating an external link to a specific documentation page, chances are that the page is moved as the documentation changes over time.

How should a permalink look for a documentation project? Firstly, you should know that a permalink does not really exist in documentation but it is the result of careful actions to avoid breaking incoming links.

As a documentation owner, you most likely want users clicking on incoming links to see the latest version of the page.

Good practice ✅

Use page redirects if you are linking to the page in the default version of the default language. This allows links to continue working even if those defaults change.
If you move a page that likely has incoming references, create a custom redirect rule.
Links to other Sphinx projects should use intersphinx.
Use minimal filenames that don’t require renaming often.
When possible, keep original file names rather than going for low-impact URL renaming. Renaming an article’s title is great for the reader and great for SEO, but this does not have to involve the URL.
Establish your understanding of the latest and default version of your documentation at the beginning. Changing their meaning is disruptive to incoming links.
Keep development versions hidden so people do not find them on search engines by mistake. This is the best way to ensure that nobody links to URLs that are intended for development purposes.
Use a version warning notifications to ensure the reader is aware in case they are reading an old (archived) version.

Tip

Using Sphinx?: If you are using :ref: for cross-referencing, you may add as many reference labels to a headline as you need, keeping old reference labels. This will make refactoring documentation easier and avoid that external projects referencing your documentation through intersphinx break.

Questionable practice 🟡

Avoid using specific versions in links unless users need that exact version. Versions get outdated.
Avoid using a public latest for development versions and do not make your default version a development branch. Publishing development branches can mean that users are reading instructions for unreleased software or draft documentation.

Tip

404 pages are also okay!

If documentation pages have been removed or moved, it can make the maintainer of the referring website aware that they need to update their link. Users will be aware that the documentation project still exists but has changed.

The default Read the Docs 404 page is designed to be helpful, but you can also design your own, see 404 Not Found pages.

Security considerations for documentation pages

This article explains the security implications of documentation pages, this doesn’t apply to the main dashboard (readthedocs.org/readthedocs.com), only to documentation pages (readthedocs.io, readthedocs-hosted.com, and custom domains).

See also

Cross-site requests: Learn about cross-origin requests in our public APIs.

Cross-origin requests

Read the Docs allows cross-origin requests for documentation resources it serves. However, internal and proxied APIs, typically found under the /_/ path don’t allow cross-origin requests.

To facilitate this, the following headers are added to all responses from documentation pages:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, HEAD, OPTIONS

These headers allow cross-origin requests from any origin and only allow the GET, HEAD and OPTIONS methods. It’s important to note that passing credentials (such as cookies or HTTP authentication) in cross-origin requests is not allowed, ensuring access to public resources only.

Having cross-origin requests enabled allows third-party websites to make use of files from your documentation (as long as they are public), which allows various third-party integrations to work.

If needed, the Access-Control headers can be changed for your documentation pages by contacting support. You are responsible for providing the correct values for these headers, and making sure they don’t break your documentation pages.

Cookies

On Read the Docs Community, we don’t use cookies, as all resources are public.

On Read the Docs for Business, we use cookies to store user sessions. These cookies are set when a user authenticates to access private documentation. Session cookies have the SameSite attribute set to None, which allows them to be sent in cross-origin requests where allowed (see Cross-origin requests), for example, when embedding private documentation pages in an iframe (see Embedding documentation pages).

Embedding documentation pages

Embedding documentation pages in an iframe is allowed. Read the Docs doesn’t set the X-Frame-Options or Content-Security-Policy headers, which means that the browser’s default behavior is used.

Embedding private documentation pages in an iframe is possible, but it requires users to be previously authenticated in the embedded domain.

It’s important to note that embedding documentation pages in an iframe does not grant the parent page access the iframe’s content. Documentation pages serve static content only, and the exposed APIs are read-only, making the exploitation of a clickjacking vulnerability extremely unlikely.

If needed, the X-Frame-Options and Content-Security-Policy headers can be set on your documentation pages by contacting support. You are responsible for providing the correct values for these headers, and making sure they don’t break your documentation pages.

Main content detection

Read the Docs detects the main content area of HTML pages to focus on the documentation content itself, ignoring headers, footers, navigation, and other page elements.

Feature usage

Different features use this detection in different ways:

Visual diff: Uses a documentation-tool specific heuristic first. If you configure a custom selector it overrides that heuristic.
Link previews: Uses the custom selector (if set) to scope links; otherwise falls back to heuristics here.
Server side search: Always uses heuristics; it ignores any configured custom selector.

Detection logic

The main content node is detected using the following logic, in order of priority:

Elements with role="main" attribute: This ARIA role is used by many static site generators and themes to indicate the main content area.
The <main> HTML tag: The semantic HTML5 element for main content.
Parent of the first <h1> tag: If no explicit main content markers are found, the system assumes all sections are siblings under a common parent, and uses the parent of the first heading as the main content container.
The <body> tag: As a last resort, if none of the above are found, the entire body is used.

Tip

Following the ARIA conventions will also improve the accessibility of your site. See also https://webaim.org/techniques/semanticstructure/.

Improving detection

If your documentation uses a non-standard structure, Read the Docs may not correctly identify the main content area.

To improve detection, consider:

Adding a role="main" attribute to your main content container
Using a <main> HTML tag in your theme
Ensuring your main content has at least one <h1> heading

Configuring a custom selector

If the automatic detection does not work for your project, you can explicitly set the CSS selector for the main content node in your project settings:

Go to your project’s Settings.
Click Addons.
Open Advanced
Fill in the CSS main content selector field (for example: div#main or .my-content). Leave it blank to use automatic detection.
Save the settings.

When this selector is configured, it overrides the heuristic detection only for addons that honor it (currently Visual Diff and Link Previews). Choose a stable container whose structure does not change between builds to avoid spurious diffs or missed link previews. It will not affect search indexing unless we add support in the future.

Examples of good selectors:

div#content (an id that wraps all page content)
div[role="main"] (ARIA role usage)

Warning

Avoid overly broad selectors like body or ones matching multiple nodes (e.g. a class applied to multiple elements).

Example structures

Using role=”main” or <main> tag

<html>
   <head>
      ...
   </head>
   <body>
      <div>
         This content isn't processed
      </div>

      <div role="main">
         All content inside the main node is processed
      </div>

      <footer>
         This content isn't processed
      </footer>
   </body>
</html>

Inferring from first h1 tag

If a main node isn’t found, we try to infer the main node from the parent of the first section with a h1 tag. Example:

<html>
   <head>
      ...
   </head>
   <body>
      <div>
         This content isn't processed
      </div>

      <div id="parent">
         <h1>First title</h1>
         <p>
            The parent of the h1 title will
            be taken as the main node,
            this is the div tag.
         </p>

         <h2>Second title</h2>
         <p>More content</p>
      </div>
   </body>
</html>

Fallback to body tag

If a section title isn’t found, we default to the body tag. Example:

<html>
   <head>
      ...
   </head>
   <body>
      <p>Content</p>
   </body>
</html>

AI agent skills

Trying to figure out how to pass up-to-date information to AI agents is a hard problem. We have experimented with MCP servers and llms.txt, but we have found that Agent Skills are the current best way to handle this problem explicitly.

Read the Docs Skills are a collection of Agent Skills that help AI agents work with Read the Docs APIs and configuration. They are designed to keep agent output aligned with our documented behavior and reduce manual verification. This page highlights two foundational skills that cover the most common workflows: the Read the Docs API skill and the Read the Docs Config Writer skill.

What is a skill?

A skill is a small, self-contained package with a SKILL.md that teaches an agent how to perform a specific task. Skills are automatically discovered by compatible agents. When a request matches a skill description, the agent loads the relevant SKILL.md and follows its steps. To learn more about Agent Skills, see the Agent Skills home page.

Featured skills

Read the Docs API: Interact with the Read the Docs REST API. If you want to manage updates to your project (eg. adding a redirect for the current PR), this skill will help you do that.
Read the Docs Config Writer: Create or update .readthedocs.yaml configuration files. Use it to adjust build images, tools, dependency installs, or build jobs.

Install and use

Clone the repository and use the skill directories directly:

git clone https://github.com/readthedocs/skills.git

If your agent supports the Agent Skills CLI, you can install the repository with:

npx skills add readthedocs/skills

Point your agent at the skills/ directory and ask a question that matches a skill description.

Available skills

See the Read the Docs Skills repository for the latest list of skills and details.

See also

Configuration file overview: Learn about the .readthedocs.yaml configuration file.
Public REST API: Read the Read the Docs API documentation.
Markdown for AI agents: Read the Docs serves a Markdown version of documentation pages to AI agents via content negotiation.

Custom script

The Custom Script addon allows you to inject a custom JavaScript file into your documentation at serve time. This enables you to modify or enhance frozen documentation without rebuilding it.

Configure custom scripts

To add or update a custom script for your project:

Go to the Settings tab of your project.
Click Addons, then Custom Script.
Enter the URL of your JavaScript file.
Click Save.

Using custom scripts

This addon allows specifying a URL to a JavaScript file that will be injected into all pages of your documentation. The script can be hosted on Read the Docs itself (as a relative URL) or on an external server (as an absolute URL).

Common use cases for custom scripts include:

Fixing bugs or adding features to frozen documentation
Injecting analytics or tracking code
Customizing the appearance or behavior of specific documentation versions

Accessing Addons data from your script

Custom scripts are loaded asynchronously after the initial page load, which means the readthedocs-addons-data-ready event has already been fired by the time your script executes. To access the Addons data from your custom script, check the window.ReadTheDocsEventData object first, then subscribe to the event for future updates (for example, when the URL changes in a single-page application):

function handleReadTheDocsData(data) {
  // Access the Addons data here
  console.log("Project slug:", data.projects.current.slug);

  // You can filter by version to apply changes selectively
  if (data.versions.current.slug === "v3.0") {
    // Do something specific for version v3.0
  }
}

// The event "readthedocs-addons-data-ready" has been already fired when this script is run.
// We need to check for `window.ReadTheDocsEventData` first, and if it's available
// use that data to call the handler.
if (window.ReadTheDocsEventData !== undefined) {
  handleReadTheDocsData(window.ReadTheDocsEventData.data());
}

// After that, we subscribe to the Read the Docs Addons event to access data
// on future dispatchs (e.g. when a URL changes on a SPA)
document.addEventListener("readthedocs-addons-data-ready", function (event) {
  handleReadTheDocsData(event.detail.data());
});

Business hosting

We offer Read the Docs for Business for building and hosting documentation for private repositories.

In order to get started quickly, you can start a free 30-day trial to test out the platform.

See also

Read the Docs features: A high-level overview of platform features, and the pricing page has a feature breakdown by subscription level.

Commercial documentation solutions

In addition to providing the same features as Read the Docs Community, commercial subscriptions to Read the Docs add additional features and run on separate infrastructure.

The following list is a high-level overview of the areas covered by Read the Docs for Business. If you want a full feature breakdown, please refer to our pricing page.

Private repositories and private documentation

The largest difference between the community solution and our commercial offering is the ability to connect to private repositories, to restrict documentation access to certain users, or to share private documentation via private hyperlinks.

Priority support

We have a dedicated support team that responds to support requests during business hours.

Advertising-free

All commercially hosted documentation is always ad-free.

Business features

Enjoy additional functionality specifically for larger organizations such as team management, single sign-on, and audit logging.

See also

Organizations
Single sign-on (SSO)
Security logs

Organizations

Note

This feature is only available on Read the Docs for Business.

In this article, we explain how the organizations feature allows you to manage access to your projects. On Read the Docs for Business, your account is linked to an organization. Organizations allow you to define both individual and team permissions for your projects.

See also

How to manage organization owners and teams: A step-by-step guide to managing organization owners and teams.

Important objects

Owners – Get full access to both view and edit the organization and all projects
Members – Get access to a subset of the organization projects
Teams – Where you give members access to a set of projects.

The best way to think about this relationship is:

Owners will create Teams to assign permissions to all Members.

Warning

Owners, Members, and Teams behave differently if you are using Single sign-on with GitHub, Bitbucket, or GitLab.

Team types

You can create two types of teams:

Admin – Team members have full access to administer the projects assigned to the team. Members are allowed to change all of the settings, set notifications, and perform any action under the Admin tab for each project.
Read Only – Team members are only able to read the documentation of each project, and not able to change anything about each project.

Example

ACME would set up Owners of their organization, for example, Frank Roadrunner would be an owner. He has full access to the organization and all projects.

Wile E. Coyote is a contractor, and will just have access to the new project Road Builder.

Roadrunner would set up a Team called Contractors. That team would have Read Only access to the Road Builder project. Then he would add Wile E. Coyote to the team. This would give him access to just this one project inside the organization.

Single sign-on (SSO)

Note

This feature is only available on Read the Docs for Business.

Single sign-on is an optional feature on Read the Docs for Business for all users. By default, you will use teams within Read the Docs to manage user authorization. SSO will allow you to grant permissions to your organization’s projects in an easy way.

Currently, we support two different types of single sign-on:

Authentication and authorization are managed by the identity provider (GitHub, Bitbucket or GitLab)
Authentication (only) is managed by the identity provider (Google Workspace account with a verified email address)

Single sign-on with GitHub, Bitbucket, or GitLab

Using an identity provider that supports authentication and authorization allows organization owners to manage who has access to projects on Read the Docs, directly from the provider itself. If a user needs access to your documentation project on Read the Docs, that user just needs to be granted permissions in the Git repository associated with the project.

Once you enable this option, your existing Read the Docs teams will not be used. All authentication will be done using your git provider, including any two-factor authentication and additional single sign-on that they support.

Learn how to configure this SSO method with our How to setup single sign-on (SSO) with GitHub, GitLab, or Bitbucket.

SSO with Google Workspace

This feature allows you to easily manage access to users with a specific email address (e.g. employee@company.com), where company.com is a registered Google Workspace domain. As this identity provider does not provide information about which projects a user has access to, permissions are managed by the internal Read the Docs’s teams authorization system.

This feature is only available on the Pro plan and above. Learn how to configure this SSO method with our How to setup single sign-on (SSO) with Google Workspace.

SSO with SAML

Note

This feature is in beta, and will be available for Enterprise plans only. Contact support to enable this feature for your organization.

At the moment only Okta is supported as a SAML identity provider.

This feature allows you to easily manage access to users that are part of your identity provider. As SAML doesn’t provide information about which projects a user has access to, permissions are managed by the internal Read the Docs’s teams authorization system. Learn how to configure this SSO method with our guide.

Requesting additional providers

We are always interested in hearing from our users about what authentication needs they have. You can reach out to our Site support to talk with us about any additional authentication needs you might have.

Tip

Many additional providers can be supported via GitHub, Bitbucket, and GitLab SSO. We will depend on those sites in order to authenticate you, so you can use all your existing SSO methods already configured on those services.

Sharing private documentation

Note

This feature is only available on Read the Docs for Business.

Sharing private documentation is useful for giving quick access to your documentation to users outside of your organization. It allows you to share specific projects or versions of a project with users who don’t have access to your organization.

Common sharing use cases include:

Sharing a project with contractors or partners.
Sharing documentation for your product only to specific customers.
Embedding documentation in a SaaS application dashboard.

See also

API v3: You can automate sharing methods via /api/v3/projects/<project_slug>/sharing/.

Creating a shared item

Go into your project’s Admin page and click on Sharing.
Click on New Share
Select access type (secret link, password, or HTTP header token), add an expiration date and a Description to help with managing access in the future.
Check Allow access to all versions? if you want to grant access to all versions, or uncheck that option and select the specific versions you want to grant access to.
Click Save.
Get the info needed to share your documentation with other users:
- Secret link: copy the link that is generated
- Password: copy the link and password
- HTTP header token: Copy the token, and then pass the Authorization header in your HTTP request.
Give that information to the person who you want to give access.

Note

You can always revoke access by removing the sharing item on this page.

Proxy example

Below is an example of how to configure Nginx to proxy requests to Read the Docs while adding the token in the Authorization header.

server {
    listen 80;
    server_name docs.example.com;

    location / {
        proxy_pass https://docs-example.readthedocs-hosted.com;

        # Add Authorization header with the token
        proxy_set_header Authorization "Token <TOKEN>";

        # Optionally forward other headers
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

How to manage your subscription

We want to make it easy to manage your billing information. All organization owners can manage the subscription for that organization. It’s easy to achieve a number of common tasks in this dashboard:

Update your credit card information.
Upgrade, downgrade, or cancel your plan.
View, download, and pay invoices.
Add additional tax (VAT/EIN) or contact email addresses on your invoices.

You can always find our most up-to-date pricing information on our pricing page.

Managing your subscription

Navigate to the subscription management page.
Click Manage Subscription.

This action will take you to the Stripe billing portal where you can manage your subscription.

Note

You will need to be an organization owner to view subscription information. If you do not have permission, you can ask one of your existing organization owners to make any required changes.

Cancelling your subscription

Cancelling your subscription can be done following the instructions in Managing your subscription. Your subscription will remain active for the remainder of the current billing period, and will not renew for the next billing period.

We cannot cancel subscriptions through an email request, as email is an insecure method of verifying a user’s identity. If you email us about this, we require you to verify your identity by logging into your Read the Docs account and submitting an official support request there.

Billing information

We provide both monthly and annual subscriptions for all plans. Annual plans are given a 2 month discount compared to monthly billing. We support credit card billing for all plans. Pro and Enterprise plans can use invoice-based and PO billing for annual subscriptions.

Tip

We recommend paying by credit card for all users, as this greatly simplifies the billing process.

Discounts and credits

We do not generally discount our software. We provide an ad-supported service to the community with Read the Docs Community, but we do have one standard discount that we offer.

Non-profit and academic organizations

Our community hosting, provided for open source projects, is generally where we recommend most academic projects to host their projects. If you have constraints on how public your documentation can be, our commercial hosting is probably a better fit.

We offer a 50% discount on all of our commercial plans to certified academic and non-profit organizations. Please contact Site support to request this discount.

Privacy levels

Note

This feature is only available on Read the Docs for Business.

Privacy levels allow you to set the visibility of your project and its versions. This allows you to specify what information is available to the public and what is private. Privacy can be controlled at the level of the project and each version, and nothing more granular (eg. specific directories or URLs) can be controlled.

Project privacy

By default, only users that belong to your organization can see the dashboard of your project and its builds. If you want users outside your organization to be able to see the dashboard of your project, and the build output of public versions you can set the privacy level of your project to Public.

You can set the project privacy level in your dashboard by navigating to Admin ‣ Settings and changing Privacy level to Public.

Making a project public doesn’t give access to any versions. So if you want all your versions to be accessible, you need to configure those to be Public as well.

Version privacy

Each version of your documentation can be set to either Public or Private. This allows you to control who can see the documentation for a specific version.

Documentation for public versions is visible to everyone.
Private versions are available only to people who have permissions to see them. They will not display on any list view, and will 404 when visited by people without viewing permissions. If you want to share your docs temporarily, see Sharing private documentation.

You can set the privacy level for each version in your dashboard by navigating to Versions ‣ $version … Drop down ‣ Configure version and changing Privacy level to Public.

Recommended workflow

We recommend defaulting everything to private, and only making versions public when you are ready to share them with the world. This allows you to work on your documentation in private, and only share it when you are ready.

How-to guides: project setup and configuration

The following how-to guides help you solve common tasks and challenges in the setup and configuration stages.

⏩️ Connecting your Read the Docs account to your Git provider: Steps to connect an account on GitHub, Bitbucket, or GitLab with your Read the Docs account.
⏩️ Configuring a Git repository manually: If you are connecting a Git repository from another provider (for instance Gitea or Codeberg), this guide tells you how to add and configure the webhook manually.
⏩️ Managing custom domains: Hosting your documentation using your own domain name, such as docs.example.com.
⏩️ Using custom URL redirects in documentation projects: Configuring your Read the Docs project for redirecting visitors from one location to another.
⏩️ Managing subprojects: Use subprojects to nest multiple projects into a single custom domain or single documentation project.
⏩️ Using a .readthedocs.yaml file in a sub-folder: This guide shows how to configure a Read the Docs project to use a custom path for the .readthedocs.yaml build configuration. Monorepos that have multiple documentation projects in the same Git repository can benefit from this feature.
⏩️ Hiding a version: Is your version (flyout) menu overwhelmed and hard to navigate? Here’s how to make it shorter.
⏩️ How to change the URL versioning scheme of your project: Change how the URLs of your documentation look like, and if your project supports multiple versions or translations.

See also

Read the Docs tutorial: All you need to know to get started.

How to connect your Read the Docs account to your Git provider

In this how to article, we cover how to connect an account on GitHub, Bitbucket, or GitLab with your Read the Docs account. This is relevant if you have signed up for Read the Docs with your email or want to connect additional providers.

If you are going to import repositories from GitHub, Bitbucket, or GitLab, you should connect your Read the Docs account to your Git provider first.

Note

If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab credentials, you’re all done. Your account is connected ✅️. You only need this how-to if you want to connect additional Git providers.

Adding a connection

To connect your Read the Docs account with a Git provider, go to the main login menu: <Username dropdown> > Settings > Connected Services.

From here, you’ll be able to connect to your GitHub, Bitbucket, or GitLab account. This process will ask you to authorize an integration with Read the Docs.

Screenshot of example OAuth dialog on GitHub — An example of how your OAuth dialog on GitHub may look.

After approving the request, you will be taken back to Read the Docs. You will now see the account appear in the list of connected services.

Screenshot of Read the Docs "Connected Services" page with multiple services connected — Connected Services [1] [2] shows the list of Git providers that

Now your connection is ready and you will be able to import and configure Git repositories with just a few clicks.

See also

Git integration (GitHub, GitLab, Bitbucket): Learn how the connected account is used for automatically configuring Git repositories and Read the Docs projects and which permissions that are required from your Git provider.

Removing a connection

You may at any time delete the connection from Read the Docs. Delete the connection makes Read the Docs forget the immediate access, but you should also disable our OAuth Application from your Git provider.

On GitHub, navigate to Authorized OAuth Apps.
On Bitbucket, navigate to Application Authorizations.
On GitLab, navigate to Applications

How to manually configure a Git repository integration

In this guide, you will find the steps to manually integrate your Read the Docs project with any Git provider using webhooks. Manual integration is most useful for Git providers that we don’t support with automatic configuration. Automatic configuration is supported for GitHub, Bitbucket, and GitLab.

Git repositories that are imported manually do not have the required setup to send back a commit status. If you need this integration, you have to configure the repository automatically.

Manual integration setup

You need to configure your Git provider integration to call a webhook that alerts Read the Docs of changes. Read the Docs will sync versions and build your documentation whenever a Git commit happens.

Go to the Settings page for your GitHub project
Click Webhooks > Add webhook
For Payload URL, use the URL of the integration on your Read the Docs project, found on the project’s Admin > Integrations page. You may need to prepend https:// to the URL.
For Content type, both application/json and application/x-www-form-urlencoded work
Fill the Secret field with the value from the integration on Read the Docs
Select Let me select individual events, and mark Branch or tag creation, Branch or tag deletion, Pull requests and Pushes events
Ensure Active is enabled; it is by default
Finish by clicking Add webhook. You may be prompted to enter your GitHub password to confirm your action.

You can verify if the webhook is working at the bottom of the GitHub page under Recent Deliveries. If you see a Response 200, then the webhook is correctly configured. For a 403 error, it’s likely that the Payload URL is incorrect.

Payload validation

All integrations are created with a secret token, this offers a way to verify that a webhook request is legitimate.

This validation is done according to each provider:

Managing Integrations

To manually set up an integration, go to Admin > Integrations > Add integration dashboard page and select the integration type you’d like to add.

As an example, the URL pattern looks like this: https://app.readthedocs.org/api/v2/webhook/<project-name>/<id>/*. Use this URL when setting up a new integration with your provider.

Using the generic API integration

For repositories that are not hosted with a supported provider, we also offer a generic API endpoint for triggering project builds. Similar to webhook integrations, this integration has a specific URL, which can be found on the project’s Integrations dashboard page (Admin > Integrations).

Token authentication is required to use the generic endpoint, you will find this token on the integration details page. The token should be passed in as a request parameter, either as form data or as part of JSON data input.

Parameters

This endpoint accepts the following arguments during an HTTP POST:

branches

The names of the branches to trigger builds for. This can either be an array of branch name strings, or just a single branch name string.

Default: latest

token

The integration token found on the project’s Integrations dashboard page (Admin > Integrations).

default_branch

This is the default branch of the repository (ie. the one checked out when cloning the repository without arguments)

Optional

For example, to build the dev branch of project example-project using the integration token 1234:

$ curl \
    --data "branches=dev&token=1234&default_branch=main" \
    https://app.readthedocs.org/api/v2/webhook/example-project/1/

import requests

URL = "https://app.readthedocs.org/api/v2/webhook/example-project/1/"
TOKEN = "1234"
response = requests.post(
    URL,
    data={"branches": "dev", "token": TOKEN, "default_branch": "main"},
)
print(response.json())

A command like the one above could be called from a cron job or from a Git hook.

Authentication

This endpoint requires authentication. If authenticating with an integration token, a check will determine if the token is valid and matches the given project. If instead an authenticated user is used to make this request, a check will be performed to ensure the authenticated user is an owner of the project.

Troubleshooting Git provider webhooks

Debugging webhooks

If you are experiencing problems with an existing webhook, you may be able to use the integration detail page to help debug the issue. Each project integration, such as a webhook or the generic API endpoint, stores the HTTP exchange that takes place between Read the Docs and the external source. You’ll find a list of these exchanges in any of the integration detail pages.

Webhook activation failed. Make sure you have the necessary permissions

If you find this error, make sure your user has permissions over the repository. In case of GitHub, check that you have granted access to the Read the Docs OAuth App to your organization. A similar workflow is required for other supported providers.

My project isn’t automatically building

If your project isn’t automatically building, you can check your integration on Read the Docs to see the payload sent to our servers. If there is no recent activity on your Read the Docs project webhook integration, then it’s likely that your Git provider is not configured correctly. If there is payload information on your Read the Docs project, you might need to verify that your versions are configured to build correctly.

How to manage custom domains

This guide describes how to host your documentation using your own domain name, such as docs.example.com.

Adding a custom domain 

To setup your custom domain, follow these steps:

Go the Admin tab of your project.
Click on Domains.
Enter the domain where you want to serve the documentation from (e.g. docs.example.com).
Mark the Canonical option if you want use this domain as your canonical domain.
Click on Add.
At the top of the next page you’ll find the value of the DNS record that you need to point your domain to. For Read the Docs Community this is readthedocs.io, and for Business hosting the record is in the form of <hash>.domains.readthedocs.com. If you are using Cloudflare, make sure to disable the proxy status (orange cloud) for the CNAME record.

Note

For a subdomain like docs.example.com add a CNAME record, and for a root domain like example.com use an ANAME or ALIAS record.

Warning

If you delete a domain, make sure to also remove the DNS records for that domain. Otherwise, another user may add the same domain to their project and serve that content from your domain (domain hijacking).

SSL certificates are automatically provisioned for your domain once the DNS record (CNAME or ANAME/ALIAS) is pointed to Read the Docs, no extra action or certificate request is needed. Certificates are managed by Cloudflare and are typically issued within a few minutes, but may take up to one hour. See SSL certificate issue delays for more troubleshooting options.

To see if your DNS change has propagated, you can use a tool like dig to inspect your domain from your command line. As an example, our blog’s DNS record looks like this:

dig +short CNAME blog.readthedocs.com
 readthedocs.io.

Warning

We don’t support pointing subdomains or root domains to a project using A records. DNS A records require a static IP address and our IPs may change without notice.

Removing a custom domain 

To remove a custom domain:

Go the Admin tab of your project.
Click on Domains.
Click the Remove button next to the domain.
Click Confirm on the confirmation page.
Remove the DNS record for the domain from your DNS provider.

Warning

Once a domain is removed, your previous documentation domain is no longer served by Read the Docs, and any request for it will return a 404 Not Found!

Warning

If you delete a domain, make sure to also remove the DNS records for that domain. Otherwise, another user may add the same domain to their project and serve that content from your domain (domain hijacking).

Strict Transport Security (HSTS) and other custom headers 

By default, we do not return a Strict Transport Security header (HSTS) for user custom domains. This is a conscious decision as it can be misconfigured in a not easily reversible way. For both Read the Docs Community and Read the Docs for Business, HSTS and other custom headers can be set upon request.

We always return the HSTS header with a max-age of at least one year for our own domains including *.readthedocs.io, *.readthedocs-hosted.com, readthedocs.org and readthedocs.com.

Note

Please contact Site support if you want to add a custom header to your domain.

Multiple documentation sites as sub-folders of a domain 

You may host multiple documentation repositories as sub-folders of a single domain. For example, docs.example.org/projects/repo1 and docs.example.org/projects/repo2. This is a way to boost the SEO of your website.

See also

Subprojects: Further information about hosting multiple documentation repositories, using the subproject feature.

Troubleshooting 

“Error 1014: CNAME Cross-User Banned” when using Cloudflare 

Read the Docs uses Cloudflare to manage SSL certificates for custom domains, CDN caching, and other features that require the domain to be completely managed by our Cloudflare account.

If you see an “Error 1014: CNAME Cross-User Banned” message, it means that the domain is already managed by another Cloudflare account. To fix this, you need to:

Log in your Cloudflare account (https://www.cloudflare.com/).
Select your domain.
Click on “DNS”.
Find your CNAME record and click on “Edit”.
Uncheck the “Proxy status” (orange cloud) option.
Leave everything else unchanged.
Click on save.

SSL certificate issue delays 

The status of your domain validation and certificate can always be seen on the details page for your domain under Admin > Domains > YOURDOMAIN.TLD (details).

Domains are usually validated and a certificate issued within minutes. However, if you setup the domain in Read the Docs without provisioning the necessary DNS changes and then update DNS hours or days later, this can cause a delay in validating because there is an exponential back-off in validation.

Tip

Loading the domain details in the Read the Docs dashboard and saving the domain again will force a revalidation.

Disallowed DNS configurations 

In order to prevent some common cases of domain hijacking, we disallow some DNS configurations:

CNAME records pointing to another CNAME record (doc.example.com -> docs.example.com -> readthedocs.io).
CNAME records pointing to the APEX domain (www.example.com -> example.com -> readthedocs.io).

This prevents attackers from taking over unused domains with CNAME records pointing to domains that are on Read the Docs.

Warning

Users shouldn’t rely on these restrictions to prevent domain hijacking. We recommend regularly reviewing your DNS records, removing any that are no longer needed or that don’t exist on Read the Docs, or registering all valid domains in your project.

The validation process period has ended 

After you add a new custom domain, you have 30 days to complete the configuration. Once that period has ended, we will stop trying to validate your domain. If you still want to complete the configuration, go to your domain and click on Save to restart the process.

Migrating from GitBook 

If your custom domain was previously used in GitBook, contact GitBook support (via live chat in their website) to remove the domain name from their DNS Zone in order for your domain name to work with Read the Docs, otherwise it will always redirect to GitBook.

Managing subprojects

Subprojects can be used to nest projects together under a single parent project, which is most commonly used to share a single custom domain across multiple projects.

See also

Subprojects: Learn what the subproject feature can do, how it works, and how to use custom domains and subproject aliases.

Adding a subproject

The following steps can be used to connect two existing projects together:

Go to Settings ‣ Subprojects for the project that will act as your parent project.
Click Add subproject
Choose a project to connect as a subproject using the Subproject dropdown

Note

For users of Read the Docs Community: You need to be maintainer of a subproject in order to choose it from your main project.
For users of Read the Docs for Business: You need to have admin access to the subproject in order to choose it from your main project.

If you would like the subproject to use a different name in the URL structure of your built documentation, you can alter that subproject Alias field – otherwise leave this blank.
Click on Add subproject

After adding the subproject, the URL the project is served from will by changed to the URL displayed in the updated list of subprojects.

Project subproject list with a new subproject added

Updating a subproject

You can update a subproject by clicking the configure button in the list of subprojects. On the following page, it’s possible to change both the subproject and its alias using the Subproject dropdown and the Alias field. Click Update subproject to save your changes.

The URL the subproject documentation is served from will be updated after you save your changes.

Deleting a subproject

You can delete a subproject connection by clicking the delete button in the list of subprojects. Confirm the deletion on the popup that shows to delete the subproject connection.

The subproject connection will be removed and the project that was configured as a subproject will return to being served from it’s own domain. This will not remove either project, only the subproject relationship will be removed.

How to hide a version and keep its documentation online

If you manage a project with a lot of versions, the version (flyout) menu of your docs can be easily overwhelmed and hard to navigate.

_images/flyout-overwhelmed.png — Overwhelmed flyout menu

You can deactivate the version to remove its docs, but removing its docs isn’t always an option. To not list a version in the flyout menu while keeping its docs online, you can mark it as hidden. Go to the Versions tab of your project, click on Edit and mark the Hidden option.

Users that have a link to your old version will still be able to see your docs. And new users can see all your versions (including hidden versions) in the versions tab of your project at https://app.readthedocs.org/projects/<your-project>/versions/

Check the docs about versions’ states for more information.

How to use a .readthedocs.yaml file in a sub-folder

This guide shows how to configure a Read the Docs project to use a custom path for the .readthedocs.yaml build configuration. Monorepos that have multiple documentation projects in the same Git repository can benefit from this feature.

By default, Read the Docs will use the .readthedocs.yaml at the top level of your Git repository. But if a Git repository contains multiple documentation projects that need different build configurations, you will need to have a .readthedocs.yaml file in multiple sub-folders.

See also

sphinx-multiproject: If you are only using Sphinx projects and want to share the same build configuration, you can also use the sphinx-multiproject extension.
How to use custom environment variables: You might also be able to reuse the same configuration file across multiple projects, using only environment variables. This is possible if the configuration pattern is very similar and the documentation tool is the same.

Implementation considerations

This feature is currently project-wide. A custom build configuration file path is applied to all versions of your documentation.

Warning

Changing the configuration path will apply to all versions. Different versions of the project may not be able to build again if this path is changed.

Adding an additional project from the same repository

Once you have added the first project from the Import Wizard, you will need to repeat this process again to add the additional project from the same repository.

Setting the custom build configuration file

Once you have added a Git repository to a project that needs a custom configuration file path, navigate to Admin ‣ Settings and add the path to the Build configuration file field.

Screenshot of where to find the :guilabel:`Build configuration file` setting.

After pressing Save, you need to ensure that relevant versions of your documentation are built again.

Tip

Having multiple different build configuration files can be complex. We recommend setting up 1-2 projects in your Monorepo and getting them to build and publish successfully before adding additional projects to the equation.

Next steps

Once you have your monorepo pattern implemented and tested and it’s ready to roll out to all your projects, you should also consider the Read the Docs project setup for these individual projects.

Having individual projects gives you the full flexibility of the Read the Docs platform to make individual setups for each project.

For each project, it’s now possible to configure:

Sets of maintainers (or organizations on Read the Docs for Business)
Custom redirect rules
Custom domains
Automation rules
Traffic analytics
Additional documentation tools with individual build processes: One project might use Sphinx, while another project setup might use Asciidoctor.

…and much more. All settings for a Read the Docs project is available for each individual project.

See also

Managing subprojects: More information on nesting one project inside another project. In this setup, it is still possible to use the same monorepo for each subproject.

Other tips

For a monorepo, it’s not desirable to have changes in unrelated sub-folders trigger new builds.

Therefore, you should consider setting up conditional build cancellation rules. The configuration is added in each .readthedocs.yaml, making it possible to write one conditional build rules per documentation project in the Monorepo 💯️

How to use custom URL redirects in documentation projects

In this guide, you will learn the steps necessary to configure your Read the Docs project for redirecting visitors from one location to another.

User-defined redirects are issued by our servers when a reader visits an old URL, which means that the reader is automatically redirected to a new URL.

See also

Best practices for linking to your documentation: The need for a redirect often comes from external links to your documentation. Read more about handling links in this explanation of best practices.
Redirects: If you want to know more about our implementation of redirects, you can look up more examples in our reference before continuing with the how-to.

Adding a redirect rule

Redirects are configured in the project dashboard, go to Admin > Redirects.

After clicking Add Redirect, you need to select a Redirect Type. This is where things get a bit more complicated you need to fill in specific information according to that choice.

Choosing a Redirect Type

There are different types of redirect rules targeting different needs. For each choice in Redirect Type, you can mark the choice in order to experiment and preview the final rule generated.

Screenshot of the Redirect "Add Redirect" form

Here is a quick overview of the options available in Redirect Type:

Page redirect

With this option, you can specify a page in your documentation to redirect elsewhere. The rule triggers no matter the version of your documentation that the user is visiting. This rule can also redirect to another website.

Read more about this option in Page redirects

Exact redirect

With this option, you can specify a page in your documentation to redirect elsewhere. The rule is specific to the language and version of your documentation that the user is visiting. This rule can also redirect to another website.

Read more about this option in Exact redirects

Clean URL to HTML

If you choose to change the style of your URLs from clean URLs (/en/latest/tutorial/) to HTML URLs (/en/latest/tutorial.html), you can redirect all mismatches automatically.

Read more about this option in Clean/HTML URLs redirects

HTML to clean URL

Similarly to the former option, if you choose to change the style of your URLs from HTML URLs (/en/latest/tutorial.html) to clean URLs (/en/latest/tutorial/), you can redirect all mismatches automatically.

Read more about this option in Clean/HTML URLs redirects

Note

By default, redirects are followed only if the requested page doesn’t exist (404 File Not Found error). If you need to apply a redirect for files that exist, you can have a Apply even if the page exists option visible. This option is only available on some plan levels. Please ask support to enable it for you.

Defining the redirect rule

As mentioned before, you can pick and choose a Redirect Type that fits your redirect need. When you have entered a From URL and To URL and the redirect preview looks good, you are ready to save the rule.

Saving the redirect

The redirect is not activated before you click Save. Before clicking, you are free to experiment and preview the effects. Your redirect rules is added and effective immediately after saving it.

After adding the rule, you can add more redirects as needed. There are no immediate upper bounds to how many redirect rules a project may define.

Editing and deleting redirect rules

You can always revisit Admin > Redirects. in order to delete a rule or edit it.

When editing a rule, you can change its Redirect Type and its From URL or To URL.

Changing the order of redirects

The order of redirects is important, if you have multiple rules that match the same URL, the first redirect in the list will be used.

You can change the order of the redirect from the Admin > Redirects page, by using the up and down arrow buttons.

New redirects are added at the start of the list (i.e. they have the highest priority).

How-to guides: build process

⏩️ Set up email notifications: Email notifications can alert you when your builds fail. This is the most simple way to monitor your documentation builds.
⏩️ Setting up outgoing webhooks: Outgoing webhooks can used to send updates on builds to other services. We show examples using webhooks to connect to popular platforms like Slack and Discord.
⏩️ Configuring pull request builds: Have your documentation built and access a preview for every pull request builds.
⏩️ Using custom environment variables: Extra environment variables, for instance secrets, may be needed in the build process and can be defined from the project’s dashboard.
⏩️ Managing versions automatically: Automating your versioning on Read the Docs means you only have to handle your versioning logic in Git. Learn how to define rules to automate creation of new versions on Read the Docs, entirely using your Git repository’s version logic.
⏩️ Skip builds based on conditions: Use the special exit code 183 to programmatically cancel builds based on custom conditions. This helps save resources by avoiding unnecessary documentation builds.

How to setup email notifications

In this brief guide, you can learn how to setup a simple build notification via email.

Read the Docs allows you to configure emails that will be notified on failing builds. This makes sure that you are aware of failures happening in an otherwise automated process.

See also

Setting up outgoing webhooks: How to use webhooks to be notified about builds on popular platforms like Slack and Discord.
Pull request previews: Configure automated feedback and documentation site previews for your pull requests.

Email notifications

Follow these steps to add an email address to be notified about build failures:

Go to Admin ‣ Notifications in your project.
Fill in the Email field under the New Email Notifications heading
Press Add and the email is saved and will be displayed in the list of Existing notifications.

The newly added email address will be notified once a build fails.

Note

We don’t send email notifications on builds from pull requests.

Setting up outgoing webhooks

When a project build is triggered, successful or failed, Read the Docs can notify external APIs using outgoing webhooks. These webhooks contain information about the build and build status and can allow an external service to use this information for alerting, monitoring, and many other custom configurations.

See also

How to setup email notifications: Setup basic email notifications for build failures.
Pull request previews: Configure automated feedback and documentation site previews for your pull requests.

Note

Builds for pull requests do not trigger outgoing webhooks.

Creating a new webhook

To create a new outgoing webhook for your project:

Go to Settings ‣ Outgoing webhooks in your project.
Click Add webhook.
Fill in the URL field with the target URL for your endpoint.
Select the which events will trigger the webhook.
Modify the JSON payload field or leave the default (see below for more).
Click on Add webhook

Every time one of the selected events trigger, Read the Docs will send a POST request to your webhook target URL. The default payload will look like this:

{
    "event": "build:triggered",
    "name": "docs",
    "slug": "docs",
    "version": "latest",
    "commit": "2552bb609ca46865dc36401dee0b1865a0aee52d",
    "build": "15173336",
    "start_date": "2021-11-03T16:23:14",
    "build_url": "https://app.readthedocs.org/projects/docs/builds/15173336/",
    "docs_url": "https://docs.readthedocs.io/en/latest/"
}

When a webhook is sent, a new entry will be added to the Recent activity list. You can click on each entry to see the webhook request, response, and the request payload.

Custom payloads

You can customize the payload of the webhook to fit the expected structure of your target endpoint. The payload structure must be valid JSON but can contain any of our payload variable substitutions.

Variable substitutions

The following variable strings can be used in a custom payload to substitute information about the build and project in the webhook body.

{{ event }}: Event that triggered the webhook, one of build:triggered, build:failed, or build:passed.
{{ build.id }}: Build ID.
{{ build.commit }}: Commit corresponding to the build, if present (otherwise "").
{{ build.url }}: URL of the build, for example https://app.readthedocs.org/projects/docs/builds/15173336/.
{{ build.docs_url }}: URL of the documentation corresponding to the build, for example https://docs.readthedocs.io/en/latest/.
{{ build.start_date }}: Start date of the build (UTC, ISO format), for example 2021-11-03T16:23:14.
{{ organization.name }}: Organization name (Commercial only).
{{ organization.slug }}: Organization slug (Commercial only).
{{ project.slug }}: Project slug.
{{ project.name }}: Project name.
{{ project.url }}: URL of the project dashboard.
{{ version.slug }}: Version slug.
{{ version.name }}: Version name.

Examples

{
  "attachments": [
    {
      "color": "#db3238",
      "blocks": [
        {
          "type": "section",
          "text": {
            "type": "mrkdwn",
            "text": "*Read the Docs build failed*"
          }
        },
        {
          "type": "section",
          "fields": [
            {
              "type": "mrkdwn",
              "text": "*Project*: <{{ project.url }}|{{ project.name }}>"
            },
            {
              "type": "mrkdwn",
              "text": "*Version*: {{ version.name }} ({{ build.commit }})"
            },
            {
              "type": "mrkdwn",
              "text": "*Build*: <{{ build.url }}|{{ build.id }}>"
            }
          ]
        }
      ]
    }
  ]
}

See also

Slack Incoming Webhooks documentation

{
  "username": "Read the Docs",
  "content": "Read the Docs build failed",
  "embeds": [
    {
      "title": "Build logs",
      "url": "{{ build.url }}",
      "color": 15258703,
      "fields": [
        {
          "name": "*Project*",
          "value": "{{ project.url }}",
          "inline": true
        },
        {
          "name": "*Version*",
          "value": "{{ version.name }} ({{ build.commit }})",
          "inline": true
        },
        {
          "name": "*Build*",
          "value": "{{ build.url }}"
        }
      ]
    }
  ]
}

See also

Discord webhooks documentation

Verifying the payload

After you add a new webhook, Read the Docs will generate a secret key for it and use the key to generate a hash signature (HMAC-SHA256) for each payload. This signature is included in the X-Hub-Signature header of each request.

We highly recommend using this signature to verify that the webhook is coming from Read the Docs. To do so, you can add some custom code on your server, like this:

import hashlib
import hmac
import os


def verify_signature(payload, request_headers):
    """
    Verify that the signature of payload is the same as the one coming from request_headers.
    """
    digest = hmac.new(
        key=os.environ["WEBHOOK_SECRET"].encode(),
        msg=payload.encode(),
        digestmod=hashlib.sha256,
    )
    expected_signature = digest.hexdigest()

    return hmac.compare_digest(
        request_headers["X-Hub-Signature"].encode(),
        expected_signature.encode(),
    )

Legacy webhooks

Webhooks created before the custom payloads functionality was added to Read the Docs send a payload with the following structure:

{
    "name": "Read the Docs",
    "slug": "rtd",
    "build": {
        "id": 6321373,
        "commit": "e8dd17a3f1627dd206d721e4be08ae6766fda40",
        "state": "finished",
        "success": false,
        "date": "2017-02-15 20:35:54"
    }
}

To migrate to the new webhooks and keep a similar structure, you can use this as the webhook custom payload:

{
    "name": "{{ project.name }}",
    "slug": "{{ project.slug }}",
    "build": {
        "id": "{{ build.id }}",
        "commit": "{{ build.commit }}",
        "state": "{{ event }}",
        "date": "{{ build.start_date }}"
    }
}

Troubleshooting webhooks and payload discovery

You can use public tools to discover, inspect, and test outgoing webhooks. These tools act as catch-all endpoints for HTTP requests and respond with a 200 OK HTTP status code. You can use these payloads to develop your webhook services. You should exercise caution when using these tools as you might be sending sensitive data to external tools.

These public tools include:

Beeceptor: Create a temporary HTTPS endpoint and inspect incoming payloads. It lets you respond custom response code or messages from named HTTP mock server.
Webhook Tester: Inspect and debug incoming payloads. It lets you inspect all incoming requests to it’s URL/bucket.

How to configure pull request builds

In this section, you can learn how to configure pull request builds.

To enable pull request builds for your project, your Read the Docs project needs to be connected to a repository from a supported Git provider. See Limitations for more information.

Go to your project dashboard
Go to Settings, then Pull request builds
Enable the Build pull requests for this project option
Click on Update

Tip

Pull requests opened before enabling pull request builds will not trigger new builds automatically. Push a new commit to the pull request to trigger its first build.

Privacy levels

Note

Privacy levels are only supported on Business hosting.

If you didn’t import your project manually and your repository is public, the privacy level of pull request previews will be set to Public, otherwise it will be set to Private. Public pull request previews are available to anyone with the link to the preview, while private previews are only available to users with access to the Read the Docs project.

Warning

If you set the privacy level of pull request previews to Private, make sure that only trusted users can open pull requests in your repository.

Setting pull request previews to private on a public repository can allow a malicious user to access read-only APIs using the user’s session that is reading the pull request preview. Similar to GHSA-pw32-ffxw-68rh.

To change the privacy level:

Go to your project dashboard
Go to Settings, then Pull request builds
Select your option in Privacy level of builds from pull requests
Click on Update

Privacy levels work the same way as normal versions.

Limitations

Pull requests are only available for GitHub and GitLab currently. Bitbucket is not yet supported.
To enable this feature, your Read the Docs project needs to be connected to a repository from a supported Git provider.
If your project is using our GitHub App, you don’t need to configure a webhook. For GitLab, and projects using our old GitHub integration, you need to make sure that your webhook is configured to send pull request events, not just push events.
Builds from pull requests have the same memory and time limitations as regular builds.
Additional formats like PDF aren’t built in order to reduce build time.
Read the Docs doesn’t index search on pull request builds. This means that Addons search and the Read the Docs Search API will return no results.
The built documentation is kept for 90 days after the pull request has been closed or merged.
In order to have pull request build links automatically added to your pull requests, you must configure an automation to accomplish this with your Git provider. For example, see these instructions to configure with GitHub Actions.

Troubleshooting

No new builds are started when I open a pull request

The most common cause when using GitHub is that your Read the Docs project is not connected to the corresponding repository on GitHub.

If you are using our old GitHub integration, make sure that your repository’s webhook is configured to send pull request events. You can re-sync your project’s webhook integration to reconfigure the Read the Docs webhook.

To re-sync your project’s webhook, go to your project’s admin dashboard, Integrations, and then select the webhook integration for your provider. Follow the directions to re-sync the webhook, or create a new webhook integration.

You may also notice this behavior if your Read the Docs account is not connected to your Git provider account, or if it needs to be reconnected. You can (re)connect your account by going to your <Username dropdown>, Settings, then to Connected Services.

Pull request build links (such as those generated from the official GitHub Action) return a 404 error

This means that a build is not being triggered.

Verify your repository’s webhook is properly synced with Read the Docs, and configured to send pull request events. For GitHub, you can check this by visiting the “Webhooks” section of the repository’s “Settings” page. For your Read the Docs webhook, under “Which events would you like to trigger this webhook?”, choose “Send Me Everything,” or manually select push events and all events relevant to pull requests.

Build status is not being reported to your Git provider

If opening a pull request does start a new build, but the build status is not being updated with your Git provider, then your connected account may have out dated or insufficient permissions.

Make sure that you have granted access to the Read the Docs GitHub OAuth App for your personal or organization GitHub account.

See also

Debugging webhooks
GitHub permission troubleshooting

How to use custom environment variables

If extra environment variables are needed in the build process, you can define them from the project’s dashboard.

See also

Environment variable overview: Learn more about how Read the Docs applies environment variables in your builds.

Go to your project’s Admin ‣ Environment Variables and click on Add Environment Variable. You will then see the form for adding an environment variable:

Screenshot of the form for adding an environment variable

Fill in the Name field, this is the name of your variable, for instance SECRET_TOKEN or PIP_EXTRA_INDEX_URL.
Fill in the Value field with the environment variable’s value, for instance a secret token or a build configuration.
Check the Public option if you want to expose this environment variable to builds from pull requests.

Warning

If you make your environment variable public, any user that can create a pull request on your repository will be able to see the value of this environment variable. In other words, do not use this option if your environment variable is a secret.

Finally, click on Save. Your custom environment variable is immediately active for all future builds and you are ready to start using it.

Note that once you create an environment variable, you won’t be able to edit or view its value. The only way to edit an environment variable is to delete and create it again.

Keep reading for a few examples of using environment variables. ⬇️

Accessing environment variables in code

After adding an environment variable, you can read it from your build process, for example in your Sphinx’s configuration file:

conf.py

import os
import requests

# Access to our custom environment variables
username = os.environ.get("USERNAME")
password = os.environ.get("PASSWORD")

# Request a username/password protected URL
response = requests.get(
    "https://httpbin.org/basic-auth/username/password",
    auth=(username, password),
)

Accessing environment variables in build commands

You can also use any of these variables from user-defined build jobs in your project’s configuration file:

.readthedocs.yaml

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: 3.10
  jobs:
    post_install:
      - curl -u ${USERNAME}:${PASSWORD} https://httpbin.org/basic-auth/username/password

Note

If you use ${SECRET_ENV} in a command in .readthedocs.yaml, the private value of the environment variable is not substituted in log entries of the command. It will also be logged as ${SECRET_ENV}.

How to manage versions automatically

In this guide, we show you how to define rules to automate creation of new versions on Read the Docs, using your Git repository’s version logic. Automating your versioning on Read the Docs means you only have to handle your versioning logic in Git.

See also

Versions: Learn more about versioning of documentation in general.
Automation rules: Reference for all different rules and actions possible with automation.

Adding a new automation rule

First you need to go to the automation rule creation page:

Navigate to Admin ‣ Automation Rules.
Click on Add Rule and you will see the following form.

In the Automation Rule form, you need to fill in 4 fields:

Enter a Description that you can refer to later. For example, entering “Create new stable version” is a good title, as it explains the intention of the rule.
Choose a Match, which is the pattern you wish to detect in either a Git branch or tag.
- Any version matches all values.
- SemVer versions matches only values that have the SemVer format.
- Custom match matches your own pattern (entered below). If you choose this option, a field Custom match will automatically appear below the drop-down where you can add a regular expression in Python regex format.
Choose a Version type. You can choose between Tag or Branch, denoting Git tag or Git branch.
Finally, choose the Action:

Now your rule is ready and you can press Save. The rule takes effect immediately when a new version is created, but does not apply to old versions.

Tip

Examples of common usage: See the list of examples for rules that are commonly used.
Want to test if your rule works?: If you are using Git in order to create new versions, create a Git tag or branch that matches the rule and check if your automation action is triggered. After the experiment, you can delete both from Git and Read the Docs.

Ordering your rules

The order your rules are listed in Admin ‣ Automation Rules matters. Each action will be performed in that order, so earlier rules have a higher priority.

You can change the order using the up and down arrow buttons.

Note

New rules are added at the start of the list (i.e. they have the highest priority).

Skip builds based on conditions

Read the Docs provides a special build cancellation mechanism that allows you to programmatically skip builds based on custom conditions. This is useful when you want to avoid unnecessary documentation builds, saving build time and resources.

How it works

When any command in your build process exits with the special exit code 183, Read the Docs will immediately cancel the build. The build will be marked as cancelled and will not consume build time or resources beyond that point.

Note

Why exit code 183?

The exit code 183 was chosen because it represents the word “skip” encoded in ASCII.

>>> sum(list("skip".encode("ascii")))
439
>>> 439 % 256  # Unix exit codes are limited to 0-255
183

The 256 modulo operation is necessary because Unix exit codes are limited to 0-255, and any value larger than 255 is automatically reduced by taking the modulo 256.

When to skip builds

There are several scenarios where you might want to skip documentation builds:

Save resources on irrelevant changes: Skip builds when changes don’t affect documentation, such as changes only to source code, tests, or CI configuration files.
Avoid redundant builds: Skip builds for draft pull requests, work-in-progress branches, or commits with specific markers like [skip ci] in the commit message.
Conditional documentation updates: Only build documentation when specific files or directories are modified, such as the docs/ folder or configuration files.
Branch-specific logic: Skip builds on certain branches that don’t require documentation updates, such as experimental or development branches.

Examples

The following examples demonstrate common use cases for skipping builds. All examples use the build.jobs configuration key in your .readthedocs.yaml file.

Skip builds when documentation files haven’t changed

This example skips pull request builds when there are no changes to documentation-related files compared to the main branch:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.12"
  jobs:
    post_checkout:
      # Cancel building pull requests when there aren't changes in the docs directory or YAML file.
      # If there are no changes (git diff exits with 0) we force the command to return with 183.
      # This is a special exit code on Read the Docs that will cancel the build immediately.
      - |
        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml;
        then
          exit 183;
        fi

You can customize this example by:

Adding more paths to check: docs/ .readthedocs.yaml requirements/docs.txt
Checking against a different branch: origin/develop instead of origin/main
Using different comparison operators to check for specific file patterns

Skip builds based on commit message

This example skips builds when the commit message contains [skip ci] or [ci skip]:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.12"
  jobs:
    post_checkout:
      # Use `git log` to check if the latest commit contains "skip ci",
      # in that case exit the command with 183 to cancel the build
      - (git --no-pager log --pretty="tformat:%s -- %b" -1 | paste -s -d " " | grep -viq "skip ci") || exit 183

This pattern is commonly used in CI/CD systems to skip builds for administrative commits, such as version bumps or documentation typos.

Skip builds for specific branch patterns

This example skips builds for branches that match certain patterns, such as personal development branches:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.12"
  jobs:
    post_checkout:
      # Skip builds for branches starting with "dev/" or "experiment/"
      - |
        if echo "$READTHEDOCS_GIT_IDENTIFIER" | grep -qE "^(dev|experiment)/"; then
          exit 183;
        fi

Skip builds based on file types

This example skips builds when all changes are to non-documentation files, such as only images or data files:

.readthedocs.yaml

version: 2
build:
  os: "ubuntu-22.04"
  tools:
    python: "3.12"
  jobs:
    post_checkout:
      # Skip if only non-documentation files changed (e.g., only images or data files)
      - |
        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; then
          # Get list of changed files
          CHANGED_FILES=$(git diff --name-only origin/main)
          # Check if any changed files are documentation-related.
          # If ALL files are non-documentation (grep finds no documentation files),
          # then we skip the build by exiting with 183.
          if ! echo "$CHANGED_FILES" | grep -qE "\.(rst|md|py|yaml|yml|txt|toml)$"; then
            exit 183;
          fi
        fi

Best practices

When implementing skip build logic, consider these best practices:

Test your conditions locally: Before deploying skip build logic, test your bash conditions locally to ensure they work as expected. Remember that the condition failing will cancel your build.
Be specific with your conditions: Write clear and specific conditions to avoid accidentally skipping builds that should run. Overly broad conditions might prevent important documentation updates.
Document your skip logic: Add comments in your .readthedocs.yaml file explaining why builds are skipped and under what conditions. This helps future maintainers understand the configuration.
Consider the impact on pull requests: If you skip builds on pull requests, reviewers won’t have preview documentation. Make sure this aligns with your team’s review process.
Use environment variables: Leverage Read the Docs environment variables like READTHEDOCS_VERSION_TYPE to make your conditions more precise.

Limitations

Be aware of these limitations when using the skip build feature:

No partial cancellation: Once a build is cancelled with exit code 183, the entire build stops immediately. You cannot selectively skip only certain parts of the build process.
Not available in configuration file: You cannot skip builds using conditions in the .readthedocs.yaml configuration syntax itself. All logic must be implemented in bash commands.
Build is counted as cancelled: Cancelled builds appear in your build history as cancelled, not as skipped or successful. This is different from builds that never start due to branch/version filters.
No failure notifications are sent: When a build is skipped via exit code 183, Read the Docs does not send build:failed webhook notifications or failure emails for it. The build is treated as an intentional skip rather than a failure. Note that a build:triggered webhook may still have been delivered earlier, before the build command had a chance to exit with 183.
Pull request status is reported as successful: When a commit status is sent to your Git provider (for pull request builds), it is reported as successful so that the pull request is not blocked from merging.

Troubleshooting

Build is not being skipped

Verify your condition logic is correct by testing it locally
Check that the command is returning exit code 183 specifically
Ensure you’re using the correct environment variables
Review the build logs to see if your condition is being evaluated

Builds are being skipped unexpectedly

Review your condition logic to ensure it’s not too broad
Check for syntax errors in your bash commands
Verify that file paths and branch names are correct
Test the condition in different scenarios (PRs, branches, tags)

Cannot access Git information

Some Git operations require a full clone. If you need Git history, you might need to unshallow the clone
Ensure you’re running your skip logic in post_checkout to have access to the repository

How-to guides: upgrading and maintaining projects

⏩️ Creating reproducible builds: Using Sphinx, themes and extensions means that your documentation project needs to fetch a set of dependencies, each with a special version. Over time, using an unspecified version means that documentation projects suddenly start breaking. In this guide, you learn how to secure your project against sudden breakage. This is one of our most popular guides!
⏩️ Using Conda as your Python environment: Read the Docs supports Conda and Mamba as an environment management tools. In this guide, we show the practical steps of using Conda or Mamba.

How to use Conda as your Python environment

Read the Docs supports Conda as an environment management tool, along with Virtualenv. Conda support is useful for people who depend on C libraries, and need them installed when building their documentation.

This work was funded by Clinical Graphics – many thanks for their support of open source.

Activating conda

Conda support is available using a Configuration file overview, see conda.

Our Docker images use Miniconda, a minimal conda installer. After specifying your project requirements using a conda environment.yml file, Read the Docs will create the environment (using conda env create) and add the core dependencies needed to build the documentation.

Creating the `environment.yml`

There are several ways of exporting a conda environment:

conda env export will produce a complete list of all the packages installed in the environment with their exact versions. This is the best option to ensure reproducibility, but can create problems if done from a different operative system than the target machine, in our case Ubuntu Linux.
conda env export --from-history will only include packages that were explicitly requested in the environment, excluding the transitive dependencies. This is the best option to maximize cross-platform compatibility, however it may include packages that are not needed to build your docs.
And finally, you can also write it by hand. This allows you to pick exactly the packages needed to build your docs (which also results in faster builds) and overcomes some limitations in the conda exporting capabilities.

For example, using the second method for an existing environment:

$ conda activate rtd38
(rtd38) $ conda env export --from-history | tee environment.yml
name: rtd38
channels:
  - defaults
  - conda-forge
dependencies:
  - rasterio==1.2
  - python=3.8
  - pytorch-cpu=1.7
prefix: /home/docs/.conda/envs/rtd38

Read the Docs will override the name and prefix of the environment when creating it, so they can have any value, or not be present at all.

Tip

Bear in mind that rasterio==1.2 (double ==) will install version 1.2.0, whereas python=3.8 (single =) will fetch the latest 3.8.* version, which is 3.8.8 at the time of writing.

Effective use of channels

Conda packages are usually hosted on https://anaconda.org/, a registration-free artifact archive maintained by Anaconda Inc. Contrary to what happens with the Python Package Index, different users can potentially host the same package in the same repository, each of them using their own channel. Therefore, when installing a conda package, conda also needs to know which channels to use, and which ones take precedence.

If not specified, conda will use defaults, the channel maintained by Anaconda Inc. and subject to Anaconda Terms of Service. It contains well-tested versions of the most widely used packages. However, some packages are not available on the defaults channel, and even if they are, they might not be on their latest versions.

As an alternative, there are channels maintained by the community that have a broader selection of packages and more up-to-date versions of them, the most popular one being conda-forge.

To use the conda-forge channel when specifying your project dependencies, include it in the list of channels in environment.yml, and conda will rank them in order of appearance. To maximize compatibility, we recommend putting conda-forge above defaults:

name: rtd38
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.8
  # Rest of the dependencies

Tip

If you want to opt out the defaults channel completely, replace it by nodefaults in the list of channels. See the relevant conda docs for more information.

Making builds faster with mamba

One important thing to note is that, when enabling the conda-forge channel, the conda dependency solver requires a large amount of RAM and long solve times. This is a known issue due to the sheer amount of packages available in conda-forge.

As an alternative, you can instruct Read the Docs to use mamba, a drop-in replacement for conda that is much faster and reduces the memory consumption of the dependency solving process.

To do that, add a .readthedocs.yaml configuration file with these contents:

.readthedocs.yaml

version: 2

build:
  os: "ubuntu-24.04"
  tools:
    python: "miniconda3-3.12-24.9"

conda:
  environment: environment.yml

You can read more about the build.tools.python configuration in our documentation.

Mixing conda and pip packages

There are valid reasons to use pip inside a conda environment: some dependency might not be available yet as a conda package in any channel, or you might want to avoid precompiled binaries entirely. In either case, it is possible to specify the subset of packages that will be installed with pip in the environment.yml file. For example:

name: rtd38
channels:
  - conda-forge
  - defaults
dependencies:
  - rasterio==1.2
  - python=3.8
  - pytorch-cpu=1.7
  - pip>=20.1  # pip is needed as dependency
  - pip:
    - black==20.8b1

The conda developers recommend in their best practices to install as many requirements as possible with conda, then use pip to minimize possible conflicts and interoperability issues.

Warning

Notice that conda env export --from-history does not include packages installed with pip, see this conda issue for discussion.

Compiling your project sources

If your project contains extension modules written in a compiled language (C, C++, FORTRAN) or server-side JavaScript, you might need special tools to build it from source that are not readily available on our Docker images, such as a suitable compiler, CMake, Node.js, and others.

Luckily, conda is a language-agnostic package manager, and many of these development tools are already packaged on conda-forge or more specialized channels.

For example, this conda environment contains the required dependencies to compile Slycot on Read the Docs:

name: slycot38
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.8
  - cmake
  - numpy
  - compilers

Troubleshooting

If you have problems on the environment creation phase, either because the build runs out of memory or time or because some conflicts are found, you can try some of these mitigations:

Reduce the number of channels in environment.yml, even leaving conda-forge only and opting out of the defaults adding nodefaults.
Constrain the package versions as much as possible to reduce the solution space.
Use mamba, an alternative package manager fully compatible with conda packages.
And, if all else fails, request more resources.

Custom Installs

If you are running a custom installation of Read the Docs, you will need the conda executable installed somewhere on your PATH. Because of the way conda works, we can’t safely install it as a normal dependency into the normal Python virtualenv.

Warning

Installing conda into a virtualenv will override the activate script, making it so you can’t properly activate that virtualenv anymore.

How-to guides: content, themes and SEO

⏩️ Search engine optimization (SEO) for documentation projects: This article explains how documentation can be optimized to appear in search results, ultimately increasing traffic to your docs.
⏩️ Using traffic analytics: In this guide, you can learn to use Read the Docs’ built-in traffic analytics for your documentation project.
⏩️ Managing translations for Sphinx projects: This guide walks through the process needed to manage translations of your documentation. Once this work is done, you can setup your project under Read the Docs to build each language of your documentation by reading Localization and Internationalization.
⏩️ Supporting Unicode in Sphinx PDFs: Sphinx offers different LaTeX engines that have better support for Unicode characters, relevant for instance for Japanese or Chinese.
⏩️ Cross-referencing with Sphinx: When writing documentation you often need to link to other pages of your documentation, other sections of the current page, or sections from other pages.
⏩️ Linking to other projects with Intersphinx: This section shows you how to maintain references to named sections of other external Sphinx projects.
⏩️ Using Jupyter notebooks in Sphinx: There are a few extensions that allow integrating Jupyter and Sphinx, and this document will explain how to achieve some of the most commonly requested features.
⏩️ Migrating from rST to MyST: In this guide, you will find how you can start writing Markdown in your existing reStructuredText project, or migrate it completely.
⏩️ Enabling offline formats: This guide provides step-by-step instructions to enabling offline formats of your documentation.
⏩️ Using search analytics: In this guide, you can learn to use Read the Docs’ built-in search analytics for your documentation project.
⏩️ Adding custom CSS or JavaScript to Sphinx documentation: Adding additional CSS or JavaScript files to your Sphinx documentation can let you customize the look and feel of your docs or add additional functionality.
⏩️ Embedding content from your documentation: Did you know that Read the Docs has a public API that you can use to embed documentation content? There are a number of use cases for embedding content, so we’ve built our integration in a way that enables users to build on top of it.
⏩️ Adding “Edit Source” links on your Sphinx theme: Using your own theme? Add some extra variables in the Sphinx html_context, to add an “edit source” link at the top of all pages.

How to do search engine optimization (SEO) for documentation projects

This article explains how documentation can be optimized to appear in search results, ultimately increasing traffic to your docs.

While you optimize your docs to make them more friendly for search engine spiders/crawlers, it’s important to keep in mind that your ultimate goal is to make your docs more discoverable for your users.

By following our best practices for SEO, you can ensure that when a user types a question into a search engine, they can get the answers from your documentation in the search results.

See also

This guide isn’t meant to be your only resource on SEO, and there’s a lot of SEO topics not covered here. For additional reading, please see the external resources section.

SEO basics

Search engines like Google and Bing crawl through the internet following links in an attempt to understand and build an index of what various pages and sites are about. This is called “crawling” or “indexing”. When a person sends a query to a search engine, the search engine evaluates this index using a number of factors and attempts to return the results most likely to answer that person’s question.

How search engines “rank” sites based on a person’s query is part of their secret sauce. While some search engines publish the basics of their algorithms (see Google’s published details on PageRank), few search engines give all of the details in an attempt to prevent users from gaming the rankings with low value content which happens to rank well.

Both Google and Bing publish a set of guidelines to help make sites easier to understand for search engines and rank better. To summarize some of the most important aspects as they apply to technical documentation, your site should:

Use descriptive and accurate titles in the HTML <title> tag. For Sphinx, the <title> comes from the first heading on the page.
Ensure your URLs are descriptive. They are displayed in search results. Sphinx uses the source filename without the file extension as the URL.
Make sure the words your readers would search for to find your site are actually included on your pages.
Avoid low content pages or pages with minimal original content.
Avoid tactics that attempt to increase your search engine ranking without actually improving content.
Google specifically warns about automatically generated content although this applies primarily to keyword stuffing and low value content. High quality documentation generated from source code (eg. auto generated API documentation) seems OK.

While both Google and Bing discuss site performance as an important factor in search result ranking, this guide is not going to discuss it in detail. Most technical documentation that uses Sphinx or Read the Docs generates static HTML and the performance is typically decent relative to most of the internet.

Best practices for documentation SEO

Once a crawler or spider finds your site, it will follow links and redirects in an attempt to find any and all pages on your site. While there are a few ways to guide the search engine in its crawl for example by using a sitemap or a robots.txt file which we’ll discuss shortly, the most important thing is making sure the spider can follow links on your site and get to all your pages.

Avoid unlinked pages ✅️

When building your documentation, you should ensure that pages aren’t unlinked, meaning that no other pages or navigation have a link to them.

Search engine crawlers will not discover pages that aren’t linked from somewhere else on your site.

Sphinx calls pages that don’t have links to them “orphans” and will throw a warning while building documentation that contains an orphan unless the warning is silenced with the orphan directive.

We recommend failing your builds whenever Sphinx warns you, using the fail_on_warnings option in .readthedocs.yaml.

Here is an example of a warning of an unreferenced page:

$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.8.5
...
checking consistency... /path/to/file.rst: WARNING: document isn't included in any toctree
done
...
build finished with problems, 1 warning.

MkDocs automatically includes all .md files in the main navigation 💯️. This makes sure that all files are discoverable by default, however there are configurations that allow for unlinked files in various ways. If you want to scan your documentation for unreferenced files and images, a plugin like mkdocs-unused-files does the job.

Avoid uncrawlable content ✅️

While typically this isn’t a problem with technical documentation, try to avoid content that is “hidden” from search engines. This includes content hidden in images or videos which the crawler may not understand. For example, if you do have a video in your docs, make sure the rest of that page describes the content of the video.

When using images, make sure to set the image alt text or set a caption on figures.

For Sphinx, the image and figure directives support both alt texts and captions:

.. image:: your-image.png
    :alt: A description of this image

.. figure:: your-image.png

    A caption for this figure

The Markdown syntax defines an alt text for images:

![Image alt text](https://dummyimage.com/600x400/){ width="300" }

Though HTML supports figures and captions, Markdown and MkDocs do not have a built-in feature. Instead, you can use markdown extensions such as md-in-html to allow the necessary HTML structures for including figures:

<figure markdown>
   ![Image alt text](https://dummyimage.com/600x400/){ width="300" }
   <figcaption>Image caption</figcaption>
</figure>

Redirects ✅️

Redirects tell search engines when content has moved. For example, if this guide moved from guides/technical-docs-seo-guide.html to guides/sphinx-seo-guide.html, there will be a time period where search engines will still have the old URL in their index and will still be showing it to users. This is why it is important to update your own links within your docs as well as redirecting. If the hostname moved from docs.readthedocs.io to docs.readthedocs.org, this would be even more important!

Read the Docs supports a few different kinds of user defined redirects that should cover all the different cases such as redirecting a certain page for all project versions, or redirecting one version to another.

Canonical URLs ✅️

Anytime very similar content is hosted at multiple URLs, it is pretty important to set a canonical URL. The canonical URL tells search engines where the original version your documentation is even if you have multiple versions on the internet (for example, incomplete translations or deprecated versions).

Read the Docs supports setting the canonical URL if you are using a custom domain under Admin > Domains in the Read the Docs dashboard.

Use a robots.txt file ✅️

A robots.txt file is readable by crawlers and lives at the root of your site (eg. https://docs.readthedocs.io/robots.txt). It tells search engines which pages to crawl or not to crawl and can allow you to control how a search engine crawls your site. For example, you may want to request that search engines ignore unsupported versions of your documentation while keeping those docs online in case people need them.

By default, Read the Docs serves a robots.txt for you. To customize this file, you can create a robots.txt file that is written to your documentation root on your default branch/version.

See the Google’s documentation on robots.txt for additional details.

Use a sitemap.xml file ✅️

A sitemap is a file readable by crawlers that contains a list of pages and other files on your site and some metadata or relationships about them (eg. https://docs.readthedocs.io/sitemap.xml). A good sitemaps provides information like how frequently a page or file is updated or any alternate language versions of a page.

Read the Docs generates a sitemap for you that contains the last time your documentation was updated as well as links to active versions, subprojects, and translations your project has. We have a small separate guide on sitemaps.

See the Google docs on building a sitemap.

Use meta tags ✅️

Using a meta description allows you to customize how your pages look in search engine result pages.

Typically search engines will use the first few sentences of a page if no meta description is provided. In Sphinx, you can customize your meta description using the following RestructuredText:

.. meta::
    :description lang=en:
        Adding additional CSS or JavaScript files to your Sphinx documentation
        can let you customize the look and feel of your docs or add additional functionality.

_images/google-search-engine-results.png — Google search engine results showing a customized meta description

Moz.com, an authority on search engine optimization, makes the following suggestions for meta descriptions:

Your meta description should have the most relevant content of the page. A searcher should know whether they’ve found the right page from the description.
The meta description should be between 150-300 characters and it may be truncated down to around 150 characters in some situations.
Meta descriptions are used for display but not for ranking.

Search engines don’t always use your customized meta description if they think a snippet from the page is a better description.

Measure, iterate, & improve

Search engines (and soon, Read the Docs itself) can provide useful data that you can use to improve your docs’ ranking on search engines.

Search engine feedback

Google Search Console and Bing Webmaster Tools are tools for webmasters to get feedback about the crawling of their sites (or docs in our case). Some of the most valuable feedback these provide include:

Google and Bing will show pages that were previously indexed that now give a 404 (or more rarely a 500 or other status code). These will remain in the index for some time but will eventually be removed. This is a good opportunity to create a redirect.
These tools will show any crawl issues with your documentation.
Search Console and Webmaster Tools will highlight security issues found or if Google or Bing took action against your site because they believe it is spammy.

Analytics tools

A tool like Google Analytics, along with our integrated Read the Docs analytics, can give you feedback about the search terms people use to find your docs, your most popular pages, and lots of other useful data.

Search term feedback can be used to help you optimize content for certain keywords or for related keywords. For Sphinx documentation, or other technical documentation that has its own search features, analytics tools can also tell you the terms people search for within your site.

Knowing your popular pages can help you prioritize where to spend your SEO efforts. Optimizing your already popular pages can have a significant impact.

External resources

Here are a few additional resources to help you learn more about SEO and rank better with search engines.

How to enable offline formats

This guide provides step-by-step instructions to enabling offline formats of your documentation.

They are automatically built by Read the Docs during our default build process, as long as you have the configuration enabled to turn this on.

Enabling offline formats

Offline formats are enabled by the formats key in our config file. A simple example is here:

# Build PDF & ePub
formats:
  - epub
  - pdf

Verifying offline formats

You can verify that offline formats are building in your Project dashboard > Downloads:

Deleting offline formats

The entries in the Downloads section of your project dashboard reflect the formats specified in your config file for each active version.

This means that if you wish to remove downloadable content for a given version, you can do so by removing the matching formats key from your config file.

Continue learning

See also

Other pages in our documentation are relevant to this feature, and might be a useful next step.

Offline formats (PDF, ePub, HTML) - Overview of this feature.
formats - Configuration file options for offline formats.
Where to put files - Where to put offline format output when using custom build commands.

How to manage translations for Sphinx projects

This guide walks through the process needed to manage translations of your documentation. Once this work is done, you can setup your project under Read the Docs to build each language of your documentation by reading Localization and Internationalization.

Overview

There are many different ways to manage documentation in multiple languages by using different tools or services. All of them have their pros and cons depending on the context of your project or organization.

In this guide we will focus our efforts around two different methods: manual and using Transifex.

In both methods, we need to follow these steps to translate our documentation:

Create translatable files (.pot and .po extensions) from source language
Translate the text on those files from source language to target language
Build the documentation in target language using the translated texts

Besides these steps, once we have published our first translated version of our documentation, we will want to keep it updated from the source language. At that time, the workflow would be:

Update our translatable files from source language
Translate only new and modified texts in source language into target language
Build the documentation using the most up to date translations

Create translatable files

To generate these .pot files it’s needed to run this command from your docs/ directory:

sphinx-build -b gettext . _build/gettext

Tip

We recommend configuring Sphinx to use gettext_uuid as True and also gettext_compact as False to generate .pot files.

This command will leave the generated files under _build/gettext.

Translate text from source language

Manually

We recommend using sphinx-intl tool for this workflow.

First, you need to install it:

pip install sphinx-intl

As a second step, we want to create a directory with each translated file per target language (in this example we are using Spanish/Argentina and Portuguese/Brazil). This can be achieved with the following command:

sphinx-intl update -p _build/gettext -l es_AR -l pt_BR

This command will create a directory structure similar to the following (with one .po file per .rst file in your documentation):

locale
├── es_AR
│   └── LC_MESSAGES
│       └── index.po
└── pt_BR
    └── LC_MESSAGES
        └── index.po

Now, you can just open those .po files with a text editor and translate them taking care of no breaking the reST notation. Example:

# b8f891b8443f4a45994c9c0a6bec14c3
#: ../../index.rst:4
msgid ""
"Read the Docs hosts documentation for the open source community."
"It supports :ref:`Sphinx <sphinx>` docs written with reStructuredText."
msgstr ""
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
"BY TARGET LANGUAGE :ref:`Sphinx <sphinx>` FILL HERE."

Using Transifex

Transifex is a platform that simplifies the manipulation of .po files and offers many useful features to make the translation process as smooth as possible. These features includes a great web based UI, Translation Memory, collaborative translation, etc.

You need to create an account in their service and a new project before start.

After that, you need to install the Transifex CLI tool which will help you in the process to upload source files, update them and also download translated files. To do this, run this command:

curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

After installing it, you need to configure your account. For this, you need to create an API Token for your user to access this service through the command line. This can be done under your User’s Settings.

With the token, you have two options: to export as TX_TOKEN environment variable or to store it in ~/.transifexrc.

You can export the token to an environment variable, using an export command, which activates it in your current command line session:

# ``1/xxxx`` is the API token you generated
export TX_TOKEN=1/xxxx

In order to store the token permanently, you can save it in a ~/.transifexrc file. It should look like this:

[https://www.transifex.com]
rest_hostname = https://rest.api.transifex.com
token         = 1/xxxx

Now, it is time to set the project’s Transifex configuration and to map every .pot file you have created in the previous step to a resource under Transifex. To achieve this, you need to run this command:

sphinx-intl create-txconfig
sphinx-intl update-txconfig-resources \
    --pot-dir _build/gettext \
    --locale-dir locale \
    --transifex-organization-name $TRANSIFEX_ORGANIZATION \
    --transifex-project-name $TRANSIFEX_PROJECT

This command will generate a file at .tx/config with all the information needed by the tx tool to keep your translation synchronized.

Finally, you need to upload these files to Transifex platform so translators can start their work. To do this, you can run this command:

tx push --source

Now, you can go to your Transifex’s project and check that there is one resource per .rst file of your documentation. After the source files are translated using Transifex, you can download all the translations for all the languages by running:

tx pull --all

This command will leave the .po files needed for building the documentation in the target language under locale/<lang>/LC_MESSAGES.

Warning

It’s important to use always the same method to translate the documentation and do not mix them. Otherwise, it’s very easy to end up with inconsistent translations or losing already translated text.

Build the documentation in target language

Finally, to build our documentation in Spanish(Argentina) we need to tell Sphinx builder the target language with the following command:

sphinx-build -b html -D language=es_AR . _build/html/es_AR

Note

There is no need to create a new conf.py to redefine the language for the Spanish version of this documentation, but you need to set locale_dirs to ["locale"] for Sphinx to find the translated content.

After running this command, the Spanish(Argentina) version of your documentation will be under _build/html/es_AR.

Summary

Update sources to be translated

Once you have done changes in your documentation, you may want to make these additions/modifications available for translators so they can update it:

Create the .pot files:

sphinx-build -b gettext . _build/gettext

Push new files to Transifex
```
tx push --source
```

Build documentation from up to date translation

When translators have finished their job, you may want to update the documentation by pulling the changes from Transifex:

Pull up to date translations from Transifex:
```
tx pull --all
```

Commit and push these changes to our repo

git add locale/
git commit -m "Update translations"
git push

The last git push will trigger a build per translation defined as part of your project under Read the Docs and make it immediately available.

How to support Unicode in Sphinx PDFs

Sphinx offers different LaTeX engines that have better support for Unicode characters, relevant for instance for Japanese or Chinese.

To build your documentation in PDF, you need to configure Sphinx properly in your project’s conf.py. Read the Docs will execute the proper commands depending on these settings. There are several settings that can be defined (all the ones starting with latex_), to modify Sphinx and Read the Docs behavior to make your documentation to build properly.

For docs that are not written in Chinese or Japanese, and if your build fails from a Unicode error, then try xelatex as the latex_engine in your conf.py:

latex_engine = "xelatex"

When Read the Docs detects that your documentation is in Chinese or Japanese, it automatically adds some defaults for you.

For Chinese projects, it appends to your conf.py these settings:

latex_engine = "xelatex"
latex_use_xindy = False
latex_elements = {
    "preamble": "\\usepackage[UTF8]{ctex}\n",
}

And for Japanese projects:

latex_engine = "platex"
latex_use_xindy = False

Tip

You can always override these settings if you define them by yourself in your conf.py file.

Note

xindy is currently not supported by Read the Docs, but we plan to support it in the near future.

How to use cross-references with Sphinx

When writing documentation you often need to link to other pages of your documentation, other sections of the current page, or sections from other pages.

An easy way is just to use the raw URL that Sphinx generates for each page/section. This works, but it has some disadvantages:

Links can change, so they are hard to maintain.
Links can be verbose and hard to read, so it is unclear what page/section they are linking to.
There is no easy way to link to specific sections like paragraphs, figures, or code blocks.
URL links only work for the html version of your documentation.

Instead, Sphinx offers a powerful way to linking to the different elements of the document, called cross-references. Some advantages of using them:

Use a human-readable name of your choice, instead of a URL.
Portable between formats: html, PDF, ePub.
Sphinx will warn you of invalid references.
You can cross reference more than just pages and section headers.

This page describes some best-practices for cross-referencing with Sphinx with two markup options: reStructuredText and MyST (Markdown).

If you are not familiar with reStructuredText, check reStructuredText Primer for a quick introduction.
If you want to learn more about the MyST Markdown dialect, check out Syntax tokens.

Getting started

Explicit targets

Cross referencing in Sphinx uses two components, references and targets.

references are pointers in your documentation to other parts of your documentation.
targets are where the references can point to.

You can manually create a target in any location of your documentation, allowing you to reference it from other pages. These are called explicit targets.

For example, one way of creating an explicit target for a section is:

.. _My target:

Explicit targets
~~~~~~~~~~~~~~~~

Reference `My target`_.

(My_target)=
## Explicit targets

Reference [](My_target).

Then the reference will be rendered as My target.

You can also add explicit targets before paragraphs (or any other part of a page).

Another example, add a target to a paragraph:

.. _target to paragraph:

An easy way is just to use the final link of the page/section.
This works, but it has :ref:`some disadvantages <target to paragraph>`:

(target_to_paragraph)=

An easy way is just to use the final link of the page/section.
This works, but it has [some disadvantages](target_to_paragraph):

Then the reference will be rendered as: some disadvantages.

You can also create in-line targets within an element on your page, allowing you to, for example, reference text within a paragraph.

For example, an in-line target inside a paragraph:

You can also create _`in-line targets` within an element on your page,
allowing you to, for example, reference text *within* a paragraph.

Then you can reference it using `in-line targets`_, that will be rendered as: in-line targets.

Implicit targets

You may also reference some objects by name without explicitly giving them one by using implicit targets.

When you create a section, a footnote, or a citation, Sphinx will create a target with the title as the name:

For example, to reference the previous section
you can use `Explicit targets`_.

For example, to reference the previous section
you can use [](#explicit-targets).

Note

This requires setting myst_heading_anchors = 2 in your conf.py, see Auto-generated header anchors.

The reference will be rendered as: Explicit targets.

Cross-referencing using roles

All targets seen so far can be referenced only from the same page. Sphinx provides some roles that allow you to reference any explicit target from any page.

Note

Since Sphinx will make all explicit targets available globally, all targets must be unique.

You can see the complete list of cross-referencing roles at Syntax. Next, you will explore the most common ones.

The ref role

The ref role can be used to reference any explicit targets. For example:

- :ref:`my target`.
- :ref:`Target to paragraph <target to paragraph>`.
- :ref:`Target inside a paragraph <in-line targets>`.

- {ref}`my target`.
- {ref}`Target to paragraph <target_to_paragraph>`.

That will be rendered as:

Explicit targets.
Target to paragraph.
Target inside a paragraph.

The ref role also allow us to reference code blocks:

.. _target to code:

.. code-block:: python

   # Add the extension
   extensions = [
      'sphinx.ext.autosectionlabel',
   ]

   # Make sure the target is unique
   autosectionlabel_prefix_document = True

We can reference it using :ref:`code <target to code>`, that will be rendered as: code.

The doc role

The doc role allows us to link to a page instead of just a section. The target name can be relative to the page where the role exists, or relative to your documentation’s root folder (in both cases, you should omit the extension).

For example, to link to a page in the same directory as this one you can use:

- :doc:`intersphinx`
- :doc:`/guides/intersphinx`
- :doc:`Custom title </guides/intersphinx>`

- {doc}`intersphinx`
- {doc}`/guides/intersphinx`
- {doc}`Custom title </guides/intersphinx>`

That will be rendered as:

How to link to other documentation projects with Intersphinx
How to link to other documentation projects with Intersphinx
Custom title

Tip

Using paths relative to your documentation root is recommended, so you avoid changing the target name if the page is moved.

The numref role

The numref role is used to reference numbered elements of your documentation. For example, tables and images.

To activate numbered references, add this to your conf.py file:

# Enable numref
numfig = True

Next, ensure that an object you would like to reference has an explicit target.

For example, you can create a target for the next image:

Link me!

.. _target to image:

.. figure:: /img/logo.png
   :alt: Logo
   :align: center
   :width: 240px

   Link me!

(target_to_image)=

```{figure} /img/logo.png
:alt: Logo
:align: center
:width: 240px
```

Finally, reference it using :numref:`target to image`, that will be rendered as Fig. N. Sphinx will enumerate the image automatically.

Automatically label sections

Manually adding an explicit target to each section and making sure is unique is a big task! Fortunately, Sphinx includes an extension to help us with that problem, autosectionlabel.

To activate the autosectionlabel extension, add this to your conf.py file:

# Add the extension
extensions = [
    "sphinx.ext.autosectionlabel",
]

# Make sure the target is unique
autosectionlabel_prefix_document = True

Sphinx will create explicit targets for all your sections, the name of target has the form {path/to/page}:{title-of-section}.

For example, you can reference the previous section using:

- :ref:`guides/cross-referencing-with-sphinx:explicit targets`.
- :ref:`Custom title <guides/cross-referencing-with-sphinx:explicit targets>`.

- {ref}`guides/cross-referencing-with-sphinx:explicit targets`.
- {ref}`Custom title <guides/cross-referencing-with-sphinx:explicit targets>`.

That will be rendered as:

Explicit targets.
Custom title.

Invalid targets

If you reference an invalid or undefined target Sphinx will warn us. You can use the -W option when building your docs to fail the build if there are any invalid references. On Read the Docs you can use the sphinx.fail_on_warning option.

Finding the reference name

When you build your documentation, Sphinx will generate an inventory of all explicit and implicit links called objects.inv. You can list all of these targets to explore what is available for you to reference.

List all targets for built documentation with:

python -m sphinx.ext.intersphinx <link>

Where <link> is either a URL or a local path that points to your inventory file (usually in _build/html/objects.inv). For example, to see all targets from the Read the Docs documentation:

python -m sphinx.ext.intersphinx https://docs.readthedocs.io/en/stable/objects.inv

Cross-referencing targets in other documentation sites

You can reference to docs outside your project too! See How to link to other documentation projects with Intersphinx.

How to link to other documentation projects with Intersphinx

This section shows you how to maintain references to named sections of other external Sphinx projects.

You may be familiar with using the :ref: role to link to any location of your docs. It helps you to keep all links within your docs up to date and warns you if a reference target moves or changes so you can ensure that your docs don’t have broken cross-references.

Sometimes you may need to link to a specific section of another project’s documentation. While you could just hyperlink directly, there is a better way. Intersphinx allows you to use all cross-reference roles from Sphinx with objects in other projects. That is, you could use the :ref: role to link to sections of other documentation projects. Sphinx will ensure that your cross-references to the other project exist and will raise a warning if they are deleted or changed so you can keep your docs up to date.

If you are publishing several Sphinx projects together using Read the Docs’ subprojects (see Subprojects), you should use Intersphinx to reference your subprojects from other projects.

Note

You can also use Sphinx’s linkcheck builder to check for broken links. By default it will also check the validity of #anchors in links.

sphinx-build -b linkcheck . _build/linkcheck

See all the options for the linkcheck builder.

Using Intersphinx

To use Intersphinx you need to add it to the list of extensions in your conf.py file.

# conf.py file

extensions = [
    "sphinx.ext.intersphinx",
]

And use the intersphinx_mapping configuration to indicate the name and link of the projects you want to use.

# conf.py file

intersphinx_mapping = {
    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
}

# We recommend adding the following config value.
# Sphinx defaults to automatically resolve *unresolved* labels using all your Intersphinx mappings.
# This behavior has unintended side-effects, namely that documentations local references can
# suddenly resolve to an external location.
# See also:
# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
intersphinx_disabled_reftypes = ["*"]

Note

If you are using Read the Docs’ subprojects, you also need to enable the Intersphinx extension on each of the subprojects. For each subproject, you need to add the main project and all the other subprojects to intersphinx_mapping.

Now you can use the sphinx name with a cross-reference role:

- :ref:`sphinx:ref-role`
- :ref:`:ref: role <sphinx:ref-role>`
- :doc:`sphinx:usage/extensions/intersphinx`
- :doc:`Intersphinx <sphinx:usage/extensions/intersphinx>`

- {ref}`sphinx:ref-role`
- {ref}`:ref: role <sphinx:ref-role>`
- {doc}`sphinx:usage/extensions/intersphinx`
- {doc}`Intersphinx <sphinx:usage/extensions/intersphinx>`

Result:

Note

You can get the targets used in Intersphinx by inspecting the source file of the project or using this utility provided by Intersphinx:

python -m sphinx.ext.intersphinx https://www.sphinx-doc.org/en/master/objects.inv

Intersphinx in Read the Docs

You can use Intersphinx to link to subprojects, translations, another version or any other project hosted in Read the Docs. For example:

# conf.py file

intersphinx_mapping = {
    # Links to "v2" version of the "docs" project.
    "docs-v2": ("https://docs.readthedocs.io/en/v2", None),
    # Links to the French translation of the "docs" project.
    "docs-fr": ("https://docs.readthedocs.io/fr/latest", None),
    # Links to the "apis" subproject of the "docs" project.
    "sub-apis": ("https://docs.readthedocs.io/projects/apis/en/latest", None),
}

Intersphinx with private projects

If you are using Business hosting, Intersphinx will not be able to fetch the inventory file from private docs.

Intersphinx supports URLs with Basic Authorization, which Read the Docs supports using a token. You need to generate a token for each project you want to use with Intersphinx.

Go the project you want to use with Intersphinx
Click Admin > Sharing
Select HTTP Header Token
Set an expiration date long enough to use the token when building your project
Click on Share!.

Now we can add the link to the private project with the token like:

# conf.py file

intersphinx_mapping = {
    # Links to a private project named "docs"
    "docs": (
        "https://<token-for-docs>:@readthedocs-docs.readthedocs-hosted.com/en/latest",
        None,
    ),
    # Links to the private French translation of the "docs" project
    "docs": (
        "https://<token-for-fr-translation>:@readthedocs-docs.readthedocs-hosted.com/fr/latest",
        None,
    ),
    # Links to the private "apis" subproject of the "docs" project
    "docs": (
        "https://<token-for-apis>:@readthedocs-docs.readthedocs-hosted.com/projects/apis/en/latest",
        None,
    ),
}

Note

Sphinx will strip the token from the URLs when generating the links.

You can use your tokens with environment variables, so you don’t have to hard code them in your conf.py file. See Environment variable overview to use environment variables inside Read the Docs.

For example, if you create an environment variable named RTD_TOKEN_DOCS with the token from the “docs” project. You can use it like this:

# conf.py file

import os

RTD_TOKEN_DOCS = os.environ.get("RTD_TOKEN_DOCS")

intersphinx_mapping = {
    # Links to a private project named "docs"
    "docs": (
        f"https://{RTD_TOKEN_DOCS}:@readthedocs-docs.readthedocs-hosted.com/en/latest",
        None,
    ),
}

Note

Another way of using Intersphinx with private projects is to download the inventory file and keep it in sync when the project changes. The inventory file is by default located at objects.inv, for example https://readthedocs-docs.readthedocs-hosted.com/en/latest/objects.inv.

# conf.py file

intersphinx_mapping = {
    # Links to a private project named "docs" using a local inventory file.
    "docs": (
        "https://readthedocs-docs.readthedocs-hosted.com/en/latest",
        "path/to/local/objects.inv",
    ),
}

How to use Jupyter notebooks in Sphinx

Jupyter notebooks are a popular tool to describe computational narratives that mix code, prose, images, interactive components, and more. Embedding them in your Sphinx project allows using these rich documents as documentation, which can provide a great experience for tutorials, examples, and other types of technical content. There are a few extensions that allow integrating Jupyter and Sphinx, and this document will explain how to achieve some of the most commonly requested features.

Including classic `.ipynb` notebooks in Sphinx documentation

There are two main extensions that add support Jupyter notebooks as source files in Sphinx: nbsphinx and MyST-NB. They have similar intent and basic functionality: both can read notebooks in .ipynb and additional formats supported by jupytext, and are configured in a similar way (see Existing relevant extensions for more background on their differences).

First of all, create a Jupyter notebook using the editor of your liking (for example, JupyterLab). For example, source/notebooks/Example 1.ipynb:

Example Jupyter notebook created on JupyterLab

Next, you will need to enable one of the extensions, as follows:

conf.py

extensions = [
    "nbsphinx",
]

conf.py

extensions = [
    "myst_nb",
]

Finally, you can include the notebook in any toctree. For example, add this to your root document:

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   notebooks/Example 1

```{toctree}
---
maxdepth: 2
caption: Contents:
---
notebooks/Example 1
```

The notebook will render as any other HTML page in your documentation after doing make html.

Example Jupyter notebook rendered on HTML by nbsphinx

To further customize the rendering process among other things, refer to the nbsphinx or MyST-NB documentation.

Rendering interactive widgets

Widgets are eventful python objects that have a representation in the browser and that you can use to build interactive GUIs for your notebooks. Basic widgets using ipywidgets include controls like sliders, textboxes, and buttons, and more complex widgets include interactive maps, like the ones provided by ipyleaflet.

You can embed these interactive widgets on HTML Sphinx documentation. For this to work, it’s necessary to save the widget state before generating the HTML documentation, otherwise the widget will appear as empty. Each editor has a different way of doing it:

The classical Jupyter Notebook interface provides a “Save Notebook Widget State” action in the “Widgets” menu, as explained in the ipywidgets documentation. You need to click it before exporting your notebook to HTML.
JupyterLab provides a “Save Widget State Automatically” option in the “Settings” menu. You need to leave it checked so that widget state is automatically saved.
In Visual Studio Code it’s not possible to save the widget state at the time of writing (June 2021).

JupyterLab option to save the interactive widget state automatically

For example, if you create a notebook with a simple IntSlider widget from ipywidgets and save the widget state, the slider will render correctly in Sphinx.

Interactive widget rendered in HTML by Sphinx

To see more elaborate examples:

ipyleaflet provides several widgets for interactive maps, and renders live versions of them in their documentation.
PyVista is used for scientific 3D visualization with several interactive backends and examples in their documentation as well.

Warning

Although widgets themselves can be embedded in HTML, events require a backend (kernel) to execute. Therefore, @interact, .observe, and related functionalities relying on them will not work as expected.

Note

If your widgets need some additional JavaScript libraries, you can add them using add_js_file().

Using notebooks in other formats

For example, this is how a simple notebook looks like in MyST Markdown format:

Example 3.md

---
jupytext:
  text_representation:
    extension: .md
    format_name: myst
    format_version: 0.13
    jupytext_version: 1.10.3
kernelspec:
  display_name: Python 3
  language: python
  name: python3
---

# Plain-text notebook formats

This is a example of a Jupyter notebook stored in MyST Markdown format.

```{code-cell} ipython3
import sys
print(sys.version)
```

```{code-cell} ipython3
from IPython.display import Image
```

```{code-cell} ipython3
Image("http://sipi.usc.edu/database/preview/misc/4.2.03.png")
```

To render this notebook in Sphinx you will need to add this to your conf.py:

conf.py

nbsphinx_custom_formats = {
    ".md": ["jupytext.reads", {"fmt": "mystnb"}],
}

conf.py

nb_custom_formats = {
    ".md": ["jupytext.reads", {"fmt": "mystnb"}],
}

Notice that the Markdown format does not store the outputs of the computation. Sphinx will automatically execute notebooks without outputs, so in your HTML documentation they appear as complete.

Creating galleries of examples using notebooks

nbsphinx has support for creating thumbnail galleries from a list of Jupyter notebooks.

There are two ways to create the gallery:

From a reStructuredText source file, using the .. nbgallery:: directive, as showcased in the documentation.
From a Jupyter notebook, adding a "nbsphinx-gallery" tag to the metadata of a cell. Each editor has a different way of modifying the cell metadata (see figure below).

Panel to modify cell metadata in JupyterLab

For example, this markup would create a thumbnail gallery:

Thumbnails gallery
==================

.. nbgallery::
   notebooks/Example 1
   notebooks/Example 2

# Thumbnails gallery

```{nbgallery}
notebooks/Example 1
notebooks/Example 2
```

Simple thumbnail gallery created using nbsphinx

To see some examples of notebook galleries in the wild:

poliastro offers tools for interactive Astrodynamics in Python, and features several examples and how-to guides using notebooks and displays them in an appealing thumbnail gallery. In addition, poliastro uses unpaired MyST Notebooks to reduce repository size and improve integration with git.

Background

Existing relevant extensions

In the first part of this document we have seen that nbsphinx and MyST-NB are similar. However, there are some differences between them:

nsphinx uses pandoc to convert the Markdown from Jupyter notebooks to reStructuredText and then to docutils AST, whereas MyST-NB uses MyST-Parser to directly convert the Markdown text to docutils AST. Therefore, nbsphinx assumes pandoc flavored Markdown, whereas MyST-NB uses MyST flavored Markdown. Both Markdown flavors are mostly equal, but they have some differences.
nbsphinx executes each notebook during the parsing phase, whereas MyST-NB can execute all notebooks up front and cache them with jupyter-cache. This can result in shorter build times when notebooks are modified if using MyST-NB.
nbsphinx provides functionality to create thumbnail galleries, whereas MyST-NB does not have such functionality at the moment (see Creating galleries of examples using notebooks for more information about galleries).
MyST-NB allows embedding Python objects coming from the notebook in the documentation (read their “glue” documentation for more information) and provides more sophisticated error reporting than the one nbsphinx has.
The visual appearance of code cells and their outputs is slightly different: nbsphinx renders the cell numbers by default, whereas MyST-NB doesn’t.

Deciding which one to use depends on your use case. As general recommendations:

If you want to use other notebook formats or generate a thumbnail gallery from your notebooks, nbsphinx is the right choice.
If you want to leverage a more optimized execution workflow and a more streamlined parsing mechanism, as well as some of the unique MyST-NB functionalities, you should use MyST-NB.

Alternative notebook formats

Jupyter notebooks in .ipynb format (as described in the nbformat documentation) are by far the most widely used for historical reasons.

However, to compensate some of the disadvantages of the .ipynb format (like cumbersome integration with version control systems), jupytext offers other formats based on plain text rather than JSON.

As a result, there are three modes of operation:

Using classic .ipynb notebooks. It’s the most straightforward option, since all the tooling is prepared to work with them, and does not require additional pieces of software. It is therefore simpler to manage, since there are fewer moving parts. However, it requires some care when working with Version Control Systems (like git), by doing one of these things:
- Clear outputs before commit. Minimizes conflicts, but might defeat the purpose of notebooks themselves, since the computation results are not stored.
- Use tools like nbdime (open source) or ReviewNB (proprietary) to improve the review process.
- Use a different collaboration workflow that doesn’t involve notebooks.
Replace .ipynb notebooks with a text-based format. These formats behave better under version control and they can also be edited with normal text editors that do not support cell-based JSON notebooks. However, text-based formats do not store the outputs of the cells, and this might not be what you want.
Pairing .ipynb notebooks with a text-based format, and putting the text-based file in version control, as suggested in the jupytext documentation. This solution has the best of both worlds. In some rare cases you might experience synchronization issues between both files.

These approaches are not mutually exclusive, nor you have to use a single format for all your notebooks. For the examples in this document, we have used the MyST Markdown format.

If you are using alternative formats for Jupyter notebooks, you can include them in your Sphinx documentation using either nbsphinx or MyST-NB (see Existing relevant extensions for more information about the differences between them).

How to migrate from reStructuredText to MyST Markdown

In this guide, you will find how you can start writing Markdown in your existing reStructuredText project, or migrate it completely.

Sphinx is usually associated with reStructuredText, the markup language designed for the CPython project in the early ’00s. However, for quite some time Sphinx has been compatible with Markdown as well, thanks to a number of extensions.

The most powerful of such extensions is MyST-Parser, which implements a CommonMark-compliant, extensible Markdown dialect with support for the Sphinx roles and directives that make it so useful.

If, instead of migrating, you are starting a new project from scratch, have a look at 🚀 Get Started. If you are starting a project for Jupyter, you can start with Jupyter Book, which uses MyST-Parser, see the official Jupyter Book tutorial: Create your first book

How to write your content both in reStructuredText and MyST

It is useful to ask whether a migration is necessary in the first place. Doing bulk migrations of large projects with lots of work in progress will create conflicts for ongoing changes. On the other hand, your writers might prefer to have some files in Markdown and some others in reStructuredText, for whatever reason. Luckily, Sphinx supports reading both types of markup at the same time without problems.

To start using MyST in your existing Sphinx project, first install the myst-parser Python package and then enable it on your configuration:

conf.py

extensions = [
    # Your existing extensions
    ...,
    "myst_parser",
]

Your reStructuredText documents will keep rendering, and you will be able to add MyST documents with the .md extension that will be processed by MyST-Parser.

As an example, this guide is written in MyST while the rest of the Read the Docs documentation is written in reStructuredText.

Note

By default, MyST-Parser registers the .md suffix for MyST source files. If you want to use a different suffix, you can do so by changing your source_suffix configuration value in conf.py.

How to convert existing reStructuredText documentation to MyST

To convert existing reST documents to MyST, you can use the rst2myst CLI script shipped by RST-to-MyST. The script supports converting the documents one by one, or scanning a series of directories to convert them in bulk.

After installing `rst-to-myst`, you can run the script as follows:

$ rst2myst convert docs/source/index.rst  # Converts index.rst to index.md
$ rst2myst convert docs/**/*.rst  # Convert every .rst file under the docs directory

This will create a .md MyST file for every .rst source file converted.

How to modify the behaviour of `rst2myst`

The rst2myst accepts several flags to modify its behavior. All of them have sensible defaults, so you don’t have to specify them unless you want to.

These are a few options you might find useful:

-d, --dry-run: Only verify that the script would work correctly, without actually writing any files.
-R, --replace-files: Replace the .rst files by their .md equivalent, rather than writing a new .md file next to the old .rst one.

You can read the full list of options in the `rst2myst` documentation.

How to enable optional syntax

Some reStructuredText syntax will require you to enable certain MyST plugins. For example, to write reST definition lists, you need to add a myst_enable_extensions variable to your Sphinx configuration, as follows:

conf.py

myst_enable_extensions = [
    "deflist",
]

You can learn more about other MyST-Parser plugins in their documentation.

How to write reStructuredText syntax within MyST

There is a small chance that rst2myst does not properly understand a piece of reST syntax, either because there is a bug in the tool or because that syntax does not have a MyST equivalent yet. For example, as explained in the documentation, the sphinx.ext.autodoc extension is incompatible with MyST.

Fortunately, MyST supports an eval-rst directive that will parse the content as reStructuredText, rather than MyST. For example:

```{eval-rst}
.. note::

   Complete MyST migration.

```

will produce the following result:

Note

Complete MyST migration.

As a result, this allows you to conduct a gradual migration, at the expense of having heterogeneous syntax in your source files. In any case, the HTML output will be the same.

How to add custom CSS or JavaScript to Sphinx documentation

Adding additional CSS or JavaScript files to your Sphinx documentation can let you customize the look and feel of your docs or add additional functionality. For example, with a small snippet of CSS, your documentation could use a custom font or have a different background color.

If your custom stylesheet is _static/css/custom.css, you can add that CSS file to the documentation using the Sphinx option html_css_files:

## conf.py

# These folders are copied to the documentation's HTML output
html_static_path = ['_static']

# These paths are either relative to html_static_path
# or fully qualified paths (eg. https://...)
html_css_files = [
    'css/custom.css',
]

A similar approach can be used to add JavaScript files:

html_js_files = [
    'js/custom.js',
]

Note

The Sphinx HTML options html_css_files and html_js_files were added in Sphinx 1.8. Unless you have a good reason to use an older version, you are strongly encouraged to upgrade. Sphinx is almost entirely backwards compatible.

Overriding or replacing a theme’s stylesheet

The above approach is preferred for adding additional stylesheets or JavaScript, but it is also possible to completely replace a Sphinx theme’s stylesheet with your own stylesheet.

If your replacement stylesheet exists at _static/css/yourtheme.css, you can replace your theme’s CSS file by setting html_style in your conf.py:

## conf.py

html_style = 'css/yourtheme.css'

If you only need to override a few styles on the theme, you can include the theme’s normal CSS using the CSS @import rule .

/** css/yourtheme.css **/

/* This line is theme specific - it includes the base theme CSS */
@import '../alabaster.css';  /* for Alabaster */
/*@import 'theme.css';       /* for the Read the Docs theme */

body {
    /* ... */
}

See also

You can also add custom classes to your html elements. See Docutils Class and this related Sphinx footnote… for more information.

Adding “Edit Source” links on your Sphinx theme

You can use define some Sphinx variables in the html_context to tell Read the Docs Sphinx theme to display “Edit Source” links on each page.

More information can be found on Sphinx documentation.

GitHub

If you want to integrate GitHub, these are the required variables to put into your conf.py:

html_context = {
    "display_github": True, # Integrate GitHub
    "github_user": "MyUserName", # Username
    "github_repo": "MyDoc", # Repo name
    "github_version": "master", # Version
    "conf_py_path": "/source/", # Path in the checkout to the docs root
}

They can be used like this:

{% if display_github %}
    <li><a href="https://github.com/{{ github_user }}/{{ github_repo }}
    /blob/{{ github_version }}{{ conf_py_path }}{{ pagename }}.rst">
    Show on GitHub</a></li>
{% endif %}

Bitbucket

If you want to integrate Bitbucket, these are the required variables to put into your conf.py:

html_context = {
    "display_bitbucket": True, # Integrate Bitbucket
    "bitbucket_user": "MyUserName", # Username
    "bitbucket_repo": "MyDoc", # Repo name
    "bitbucket_version": "master", # Version
    "conf_py_path": "/source/", # Path in the checkout to the docs root
}

They can be used like this:

{% if display_bitbucket %}
    <a href="https://bitbucket.org/{{ bitbucket_user }}/{{ bitbucket_repo }}
    /src/{{ bitbucket_version}}{{ conf_py_path }}{{ pagename }}.rst'"
    class="icon icon-bitbucket"> Edit on Bitbucket</a>
{% endif %}

Gitlab

If you want to integrate Gitlab, these are the required variables to put into your conf.py:

html_context = {
    "display_gitlab": True, # Integrate Gitlab
    "gitlab_user": "MyUserName", # Username
    "gitlab_repo": "MyDoc", # Repo name
    "gitlab_version": "master", # Version
    "conf_py_path": "/source/", # Path in the checkout to the docs root
}

They can be used like this:

{% if display_gitlab %}
    <a href="https://{{ gitlab_host|default("gitlab.com") }}/
    {{ gitlab_user }}/{{ gitlab_repo }}/blob/{{ gitlab_version }}
    {{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-gitlab">
    Edit on GitLab</a>
{% endif %}

Additional variables

'pagename' - Sphinx variable representing the name of the page you’re on.

How-to guides: security and access

⏩️ Single sign-on (SSO) with GitHub, GitLab, or Bitbucket: When using an organization on Read the Docs for Business, you can configure SSO for your users to authenticate to Read the Docs.
⏩️ Single sign-on (SSO) with Google Workspace: When using an organization on Read the Docs for Business, you can configure SSO for your users to authenticate to Read the Docs. This guide is written for Google Workspace.
⏩️ Managing Read the Docs teams: When using an organization on Read the Docs for Business, it’s possible to create different teams with custom access levels.
⏩️ Creating a project from a private repository: How to create and configure a project using a private repository on Read the Docs for Business.
⏩️ Using private Git submodules: If you are using private Git repositories and they also contain private Git submodules, you need to follow a few special steps.
⏩️ Installing private python packages: If you have private dependencies, you can install them from a private Git repository or a private repository manager.
⏩️ Manage Maintainers: Learn how to manage maintainers for your projects on Read the Docs Community.

How to setup single sign-on (SSO) with GitHub, GitLab, or Bitbucket

Note

This feature is only available on Read the Docs for Business.

This how-to guide will provide instructions on how to enable SSO with GitHub, GitLab, or Bitbucket. If you want more information on this feature, please read Single sign-on (SSO)

Prerequisites

Organization permissions

To change your Organization’s settings, you need to be an owner of that organization.

You can validate your ownership of the Organization with these steps:

Navigate to the organization management page.
Look at the Owners section on the right menu.

If you’d like to modify this setting and are not an owner, you can ask an existing organization owner to take the actions listed.

User setup

Users in your organization must have their GitHub, Bitbucket, or GitLab account connected, otherwise they won’t have access to any project on Read the Docs after performing this change. You can read more about granting permissions on GitHub in their documentation.

Enabling SSO

You can enable this feature in your organization by:

Navigate to the authorization setting page.
Select GitHub, GitLab or Bitbucket on the Provider dropdown.
Select Save

Warning

Once you enable this option, your existing Read the Docs teams will not be used. While testing you can enable SSO and then disable it without any data loss.

Grant access to read private documentation

By granting read permissions to a user in your git repository, you are giving the user access to read the documentation of the associated project on Read the Docs. By default, private git repositories are built as private documentation websites. Having read permissions to the git repository translates to having view permissions to a private documentation website.

Grant access to administer a project

By granting admin permission to a user in the git repository, you are giving the user access to read the documentation and to be an administrator of the associated project on Read the Docs.

Grant access to import a project

When SSO with a Git provider is enabled, only owners of the Read the Docs organization can import projects.

To be able to import a project, a user must have:

admin permissions in the associated Git repository.
Ownership rights to the Read the Docs organization

Revoke access to a project

If a user should not have access to a project, you can revoke access to the git repository, and this will be automatically reflected in Read the Docs.

The same process is followed in case you need to remove admin access, but still want that user to have access to read the documentation. Instead of revoking access completely, downgrade their permissions to read only.

See also

To learn more about choosing a single sign-on approach, please read Single sign-on (SSO).

How to setup single sign-on (SSO) with Google Workspace

Note

This feature is only available on Read the Docs for Business.

This how-to guide will provide instructions on how to enable SSO with Google Workspace. If you want more information on this feature, please read Single sign-on (SSO)

Prerequisites

Organization permissions

To change your Organization’s settings, you need to be an owner of that organization.

You can validate your ownership of the Organization with these steps:

Navigate to the organization management page.
Look at the Owners section on the right menu.

If you’d like to modify this setting and are not an owner, you can ask an existing organization owner to take the actions listed.

Connect your Google account to Read the Docs

In order to enable the Google Workspace integration, you need to connect your Google account to Read the Docs.

The domain attached to your Google account will be used to match users that sign up with a Google account to your organization.

User setup

Using this setup, all users who have access to the configured Google Workspace will automatically join to your organization when they sign up with their Google account. Existing users will not be automatically joined to the organization.

You can still add outside collaborators and manage their access. There are two ways to manage this access:

Using teams to provide access for ongoing contribution.
Using sharing to provide short-term access requiring a login.

Enabling SSO

By default, users that sign up with a Google account do not have any permissions over any project. However, you can define which teams users matching your company’s domain email address will auto-join when they sign up.

Navigate to the authorization setting page.
Select Google in the Provider drop-down.
Press Save.

After enabling SSO with Google Workspace, all users with email addresses from your configured Google Workspace domain will be required to signup using their Google account.

Warning

Existing users with email addresses from your configured Google Workspace domain will not be required to link their Google account, but they won’t be automatically joined to your organization.

Configure team for all users to join

You can mark one or many teams that users are automatically joined when they sign up with a matching email address. Configure this option by:

Navigate to the teams management page.
Click the <team name>.
Click Edit team
Enable Auto join users with an organization’s email address to this team.
Click Save

With this enabled, all users that sign up with their employee@company.com email will automatically join this team. These teams can have either read-only or admin permissions over a set of projects.

Revoke user’s access to all the projects

By disabling the Google Workspace account with email employee@company.com, you revoke access to all the projects the linked Read the Docs user had access to, and disable login on Read the Docs completely for that user.

Warning

If the user signed up to Read the Docs previously to enabling SSO with Google Workspace on your organization, they may still have access to their account and projects if they were manually added to a team.

To completely revoke access to a user, remove them from all the teams they are part of.

Warning

If the user was already signed in to Read the Docs when their access was revoked, they may still have access to documentation pages until their session expires. This is three days for the dashboard and documentation pages.

To completely revoke access to a user, remove them from all the teams they are part of.

See also

How to manage organization owners and teams: Additional user management options
Single sign-on (SSO): Information about choosing a single sign-on approach

How to set up single sign-on (SSO) with SAML

Note

This feature is only available on Read the Docs for Business.

Note

This feature is in beta, and will be available for Enterprise plans only. Contact support to enable this feature for your organization.

At the moment only Okta is supported as a SAML identity provider.

This how-to guide will provide instructions on how to enable SSO using Okta as a SAML identity provider. If you want more information on this feature, please read Single sign-on (SSO)

Prerequisites

Organization permissions

To change your Organization’s settings, you need to be an owner of that organization.

You can validate your ownership of the Organization with these steps:

Navigate to the organization management page.
Look at the Owners section on the right menu.

If you’d like to modify this setting and are not an owner, you can ask an existing organization owner to take the actions listed.

Create a SAML application in Okta

In order to enable SSO with Okta, you need to create a new SAML application in your Okta account.

Log in to your Okta account.
Click on Applications.
Click on Create App Integration.
Choose SAML 2.0, and click Next.
Fill the following fields:
- App name: Read the Docs (or any name you want)
- App logo: Optionally you can use the Read the Docs logo.
- App visibility: (optional)
Click Next.
Fill in the following fields with the information from your SAML integration:
- Single Sign On URL: https://app.readthedocs.com/accounts/saml/<organization-slug>/acs/ (replace <organization-slug> with your organization slug)
- Audience URI (SP Entity ID): https://app.readthedocs.com/accounts/saml/<organization-slug>/metadata/ (replace <organization-slug> with your organization slug)
- Name ID format: EmailAddress
- Application username: Email
- Leave the rest of the fields as default.
Select This is an internal app that we have created.
Click Finish.
After creating the application, go to the “Attribute statements” section, and add the following statements:

Name

Expression

user.id

user.id

user.firstName

user.profile.firstName

user.lastName

user.profile.lastName

Enable SAML on your Read the Docs organization

Once you have created the SAML application in Okta, you need to enable SAML on Read the Docs.

Copy the Metadata URL from the Okta application you just created.
- On Okta, click on the Applications.
- Click on the Read the Docs application.
- Click on the Sign On tab.
- Copy the Metadata URL.
Go you your organization’s SAML settings page.
Paste the Metadata URL in the Metadata URL field.
Leave the domain field empty.
Click Save.

Attaching the email domain your organization uses to enforce SAML is currently done by the Read the Docs team, contact support using an account that’s an owner of the organization.

Configure a team for users to join automatically

After you have enabled SAML on your organization, a team named “SAML Users” will be created automatically, and all users that sign up with SAML will be automatically joined to this team. You can delete this team, or configure a different team or teams for users to join automatically.

To configure a team for users to join automatically:

Navigate to the teams management page.
Click the <team name>.
Click Edit team
Enable Auto join users with an organization’s email address to this team.
Click Save

User management

Signing in with SAML

Once SAML is enabled for your organization, users can sign in using SAML by following these steps:

Go to https://app.readthedocs.com/.
Click on the Single sign-on tab.
Enter your company email address.
Click Continue to be redirected to your organization’s identity provider to complete the sign-in process.

New users

After enabling the SAML integration, all users with an email domain matching the one in your SAML integration will be required to sign up using SAML. After they sign up, they will be automatically joined to your organization within the teams you have configured to auto-join users.

Existing users

Existing users with email addresses from your configured domain will not be required to sign in using SAML, but they won’t be automatically joined to your organization.

If you want to enforce SAML for existing users, you have the following options:

Users can delete their accounts, and sign up again using SAML.
Users can link their existing accounts to their SAML identity by following this link while logged in their Read the Docs account: https://app.readthedocs.com/accounts/saml/<organization-slug>/login/?process=connect (replace <organization-slug> with your organization slug). You can find this link in your organization’s SAML settings page.

Outside collaborators

You can still add outside collaborators that don’t use SAML and manage their access. There are two ways to manage this access:

Using teams to provide access for ongoing contribution.
Using sharing to provide short-term access requiring a login.

Revoke user’s access to all the projects

By disabling access to the SAML integration to a user, you revoke access to all the projects their linked Read the Docs user had access to, and disable login on Read the Docs completely for that user.

Warning

If the user signed up to Read the Docs previously to enabling SAML on your organization, they may still have access to their account and projects if they were manually added to a team.

To completely revoke access to a user, remove them from all the teams they are part of.

Warning

If the user was already signed in to Read the Docs when their access was revoked, they may still have access to documentation pages until their session expires. This is three days for the dashboard and documentation pages.

To completely revoke access to a user, remove them from all the teams they are part of.

See also

How to manage organization owners and teams: Additional user management options
Single sign-on (SSO): Information about choosing a single sign-on approach

How to manage organization owners and teams

Note

This feature is only available on Read the Docs for Business.

Read the Docs uses teams within an organization to group users and provide permissions to projects. This guide will cover how to manage both organization owners and team members. You can read more about organizations and teams in our Organizations documentation.

Managing organization owners

Organization owners have full administrative access to the organization and all its projects. They can manage settings, teams, members, and other owners.

Adding an owner to an organization

To grant someone full administrative access to your organization, add them as an owner.

Note

You must be an owner of the organization to add another owner.

Follow these steps:

Navigate to the organization management page.
Select your organization from the list.
Click on Settings.
In the sidebar, click on Owners.
Click Invite owner.
Enter the user’s Read the Docs username or email address.
Click Invite owner.

The user will receive an invitation and must accept it to become an owner.

Removing an owner from an organization

To revoke administrative access from an organization owner:

Follow these steps:

Navigate to the organization management page.
Select your organization from the list.
Click on Settings.
In the sidebar, click on Owners.
Click Remove next to the owner you want to remove.

Note

You cannot remove the last owner from an organization. There must always be at least one owner.

Managing team members

Adding a user to a team

Adding a user to a team gives them all the permissions available to that team, whether it’s read-only or admin.

Follow these steps:

Navigate to the teams management page.
Click on a <team name>.
Click Invite Member.
Input the user’s Read the Docs username or email address.
Click Add member.

Removing a user from a team

Removing a user from a team removes all permissions that team gave them.

Follow these steps:

Navigate to the teams management page.
Click on <team name>.
Click Remove next to the user.

Granting access to import a project

Make the user a member of any team with admin permissions, they will be granted access to import a project on that team.

Automating team management

You can manage teams more easily using our single sign-on features.

See also

Organizations: General information about the organizations feature.

Creating a project from a private repository

Note

This feature is only available on Read the Docs for Business.

On Read the Docs for Business, projects can be connected to both private and public repositories. There are two methods you can use to create a project from a private repository:

Automatically create a project from a connected repository

If you have a GitHub, Bitbucket, or GitLab service connected to your account, projects can be created automatically from a connected private repository. We will handle the configuration of your repository to allow cloning and pushing status updates to trigger new builds for your project.

We recommend this method for most projects.

Manually create a project from a repository

If your Git provider is unsupported or if your Read the Docs account is not connected to your provider, you can still manually create a project against a private repository. You will have to manually configure your Git provider and repository after project creation.

Automatically create a project from a connected repository

If your Read the Docs account has a connected GitHub, Bitbucket, or GitLab account, you should be able to automatically create a project from your repository. Your account will need sufficient permissions to the repository to automatically configure it.

We recommend most users follow our directions on automatically creating projects from a connected repository.

Manually create a project from a repository

In the case that automatic project creation isn’t supported or doesn’t work for your repository, projects may be able to be manually created and configured. You can still clone the repository with SSH but you will have to manually configure the repository SSH keys and webhooks.

See also

How to manually configure a Git repository integration: An overview of all of the steps required to manually add a project. This guide is useful for both projects using public and private repositories.

Creating a project manually

Select an organization team to create the project in.

Select Add project from the main dashboard.
Select Configure manually and then Continue.
Select the organization team you’d like to create the project for. You must be on a team with admin permission to do this.

In the next form page you will manually configure your project’s repository details.

Specify your project and repository configuration.

In the Repository URL field, provide the repository’s SSH or Git URL. This URL usually starts with git@..., for example git@github.com:readthedocs/readthedocs.org.git.
In the Default branch field, provide the name of the default remote branch. This is usually main or master.
The project’s first build should fail to clone your repository. This is expected, your repository is not configured to allow access yet.

Configuring your repository

Each project is configured with an SSH key pair consisting of a public and private key. Your repository will need to be configured with the public SSH key in order to allow builds to clone your repository.

Go to the Settings ‣ SSH keys page for your project.
Click on the fingerprint of the SSH key.
Copy the text from the Public SSH key field
Next, configure your repository with this key, we’ve provided instructions for common Git providers:

For GitHub, you can use deploy keys with read only access.

Go to your project on GitHub
Click on Settings
Click on Deploy Keys
Click on Add deploy key
Put a descriptive title and paste the public key you copied above.
Click on Add key

Configuring repository webhooks

Your repository will also need to be configured to push updates via webhooks to Read the Docs on repository events. Webhook updates are used to automatically trigger new builds for your project and synchronize your repository’s branches and tags.

This step is the same for public repositories, follow the directions for manually configuring a Git repository integration.

How to use private Git submodules

Warning

This guide is for Business hosting.

If you are using private Git repositories and they also contain private Git submodules, you need to follow a few special steps.

When a project is created, a SSH key is automatically generated. You can use this SSH key to give Read the Docs access to clone your private submodules.

Note

You can manage which submodules Read the Docs should clone using a configuration file. See submodules.
Make sure you are using SSH URLs for your submodules (git@github.com:readthedocs/readthedocs.org.git for example) in your .gitmodules file, not http URLs.

GitHub

Since GitHub doesn’t allow you to reuse a deploy key across different repositories, you’ll need to use machine users to give read access to several repositories using only one SSH key.

Remove the SSH deploy key that was added to the main repository on GitHub

Note

If you are using our GitHub App to connect your repository to Read the Docs, you can skip this step, because access to your repository is controlled through the App instead of a deploy key.
1. Go to your project on GitHub
2. Click on Settings
3. Click on Deploy Keys
4. Delete the key added by Read the Docs Commercial (readthedocs.com)
Create a GitHub user and give it read only permissions to all the necessary repositories. You can do this by adding the account as:
- A collaborator
- An outside collaborator
- A team in an organization
Attach the public SSH key from your project on Read the Docs to the GitHub user you just created
1. Go to the user’s settings
2. Click on SSH and GPG keys
3. Click on New SSH key
4. Put a descriptive title and paste the public SSH key from your Read the Docs project
5. Click on Add SSH key

Azure DevOps

Azure DevOps does not have per-repository SSH keys, but keys can be added to a user instead. As long as this user has access to your main repository and all its submodules, Read the Docs can clone all the repositories with the same key.

Others

GitLab and Bitbucket allow you to reuse the same SSH key across different repositories. Since Read the Docs already added the public SSH key on your main repository, you only need to add it to each submodule repository.

How to install private python packages

Warning

This guide is for Business hosting.

Read the Docs uses pip to install your Python packages. If you have private dependencies, you can install them from a private Git repository or a private repository manager.

From a Git repository

Pip supports installing packages from a Git repository using the URI form:

git+https://gitprovider.com/user/project.git@{version} (public repository)
git+https://{token}@gitprovider.com/user/project.git@{version} (private repository)

Where version can be a tag, a branch, or a commit, and token is a personal access token with read only permissions from your provider.

To install a private package from a Git repositories, add the URI to your requirements file. Make sure to use an environment variable for the token, so you don’t have to hard code it in the URI.

Pip automatically expands environment variables in POSIX format: using only uppercase letters and _, and including a dollar sign and curly brackets around the name, like ${API_TOKEN}.

See using environment variables in Read the Docs for more information.

GitHub 

You need to create a fine-grained personal access token with the Contents repository permission set to Read-only. Follow the GitHub documentation on how to create a fine-grained personal access token.

URI example:

git+https://${GITHUB_USER}:${GITHUB_TOKEN}@github.com/user/project.git@{version}

GitLab 

You need to create a deploy token with the read_repository scope for the repository you want to install the package from. Follow the GitLab documentation on how to create a deploy token.

URI example, where GITLAB_TOKEN_USER is the user from the deploy token you created, not your GitLab user:

git+https://${GITLAB_TOKEN_USER}:${GITLAB_TOKEN}@gitlab.com/user/project.git@{version}

Bitbucket 

You need to create an app password with Read repositories permissions. Follow the Bitbucket documentation on how to create an app password.

URI example:

git+https://${BITBUCKET_USER}:${BITBUCKET_APP_PASSWORD}@bitbucket.org/user/project.git@{version}'

Here BITBUCKET_USER is your Bitbucket user.

Warning

Bitbucket doesn’t support app passwords per repository. An app password will grant read access to all repositories the user has access to. You can create a machine user to give read access only to the repositories you need.

From a repository manager other than PyPI

By default Pip installs your packages from PyPI. If you are using a different repository manager like pypiserver, or Nexus Repository, you need to get the index URL from your repository manager and set the --index-url option in one of the following ways:

Set the PIP_INDEX_URL environment variable in Read the Docs with the index URL. See the Requirements File environment variables reference.
Put --index-url=https://my-index-url.com/ at the top of your requirements file. See Requirements File Format.

How to manage maintainers for your project

Read the Docs Community allows you to manage maintainers for your projects. Every project is configured with its own list of maintainers who will all have admin privileges to the project, so be careful when adding new maintainers.

When you add a maintainer to your project, they will be invited to join the project as a maintainer. They will receive an email notification with a link to accept the invitation, and won’t have access to the project until they accept the invitation.

Adding a maintainer

Adding a maintainer gives them admin access to your project.

Follow these steps:

Navigate to the Settings tab of your project.
Under Setup, click on the Maintainers tab.
Click the Add maintainer button.
Fill out the form with the new maintainer’s username or email address.
Click Invite.

Removing a maintainer

Removing a maintainer revokes their admin access to your project.

Follow these steps:

Navigate to the Settings tab of your project.
Under Setup, click on the Maintainers tab.
Find the maintainer you want to remove in the list.
Click the Remove button next to their name.
Confirm the removal in the dialog that appears.

See also

How to manage organization owners and teams: Learn how to manage teams within an organization on Read the Docs for Business.

How-to guides: account management

⏩️ Managing your Read the Docs for Business subscription: Solving the most common tasks for managing Read the Docs subscriptions.
🔒 Configuring two-factor authentication: Secure your account with two-factor authentication.

Configuring two-factor authentication

Two-factor authentication (2FA) adds an extra layer of security to your Read the Docs account. When you enable 2FA, you need to provide two pieces of information to log in: your password and a verification code.

Enabling two-factor authentication

To enable 2FA:

Go to your account settings.
Click on Two-factor authentication.
Click on Activate.
Scan the QR code with your authenticator app.
Enter the verification code from your authenticator app.
Click on Activate.
Save your recovery codes in a safe place.

Warning

If you lose access to your authenticator app, you can use the recovery codes to log in. Keep them in a safe place, as they are the only way to access your account if you lose your device.

Disabling two-factor authentication

To disable 2FA:

Go to your account settings.
Click on Two-factor authentication.
Click on Deactivate.

Managing recovery codes

To manage your recovery codes:

Go to your account settings.
Click on Two-factor authentication.
Click on Manage recovery codes.

From there you can download your recovery codes or generate new ones.

How-to guides: best practices

Over the years, we have become familiar with a number of methods that work well and which we consider best practice.

⏩️ Best practices for linking to your documentation: Documentation changes over time, and links and cross-references can become challenging manage for various reasons. Here is a set of best practices explaining and addressing these challenges.
⏩️ Deprecating content: Best practice for removing or deprecating documentation content.
⏩️ Creating reproducible builds: Every documentation project has dependencies that are required to build it. Using an unspecified versions of these dependencies means that your project can start breaking. In this guide, learn how to protect your project against breaking randomly. This is one of our most popular guides!
⏩️ Search engine optimization (SEO) for documentation projects: This article explains how documentation can be optimized to appear in search results, increasing traffic to your docs.
⏩️ Hiding a version: Learn how you can keep your entire version history online without overwhelming the reader with version choices.

How to deprecate content

When you deprecate a feature from your project, you may want to deprecate its docs as well, and stop your users from reading that content.

Deprecating content may sound as easy as delete it, but doing that will break existing links, and you don’t necessary want to make the content inaccessible. Here you’ll find some tips on how to use Read the Docs to deprecate your content progressively and in non harmful ways.

See also

Best practices for linking to your documentation: More information about handling URL structures, renaming and removing content.

Deprecating versions

If you have multiple versions of your project, it makes sense to have its documentation versioned as well. For example, if you have the following versions and want to deprecate v1.

https://project.readthedocs.io/en/v1/
https://project.readthedocs.io/en/v2/
https://project.readthedocs.io/en/v3/

For cases like this you can hide a version. Hidden versions won’t be listed in the versions menu of your docs, and they will be listed in a robots.txt file to stop search engines of showing results for that version.

Users can still see all versions in the dashboard of your project. To hide a version go to your project and click on Versions > Edit, and mark the Hidden option. Check Version states for more information.

Note

If the versions of your project follow the semver convention, you can activate the Version warning notifications option for your project. A banner with a warning and linking to the stable version will be shown on all versions that are lower than the stable one.

Deprecating pages

You may not always want to deprecate a version, but deprecate some pages. For example, if you have documentation about two APIs and you want to deprecate v1:

https://project.readthedocs.io/en/latest/api/v1.html
https://project.readthedocs.io/en/latest/api/v2.html

A simple way is just adding a warning at the top of the page, this will warn users visiting that page, but it won’t stop users from being redirected to that page from search results. You can add an entry of that page in a custom robots.txt file to avoid search engines of showing those results. For example:

# robots.txt

User-agent: *

Disallow: /en/latest/api/v1.html # Deprecated API

However, your users will still see search results from that page if they use the search from your docs. With Read the Docs you can set a custom rank per pages. For example:

# .readthedocs.yaml

version: 2
search:
   ranking:
      api/v1.html: -1

This won’t hide results from that page, but it will give priority to results from other pages.

Tip

You can make use of Sphinx directives (like warning, deprecated, versionchanged) or MkDocs admonitions to warn your users about deprecated content.

Moving and deleting pages

After you have deprecated a feature for a while, you may want to get rid of its documentation, that’s OK, you don’t have to maintain that content forever. However, be aware that users may have links of that page saved, and it will be frustrating and confusing for them to get a 404.

To solve that problem you can create a redirect to a page with a similar feature/content, like redirecting to the docs of the v2 of your API when your users visit the deleted docs from v1, this is a page redirect from /api/v1.html to /api/v2.html. See Redirects.

How-to guides: troubleshooting problems

In the following guides, you can learn how to fix common problems using Read the Docs.

⏩️ Troubleshooting build errors: A list of common errors and resolutions encountered in the build process.
⏩️ Troubleshooting slow builds: A list of the most common issues that are slowing down builds. Even if you are not facing any immediate performance issues, it’s always good to be familiar with the most common ones.

Troubleshooting build errors

Tip

Please help us keep this section updated and contribute your own error resolutions, performance improvements, etc. Send in your helpful comments or ideas 💡 to support@readthedocs.org or contribute directly by clicking Edit on GitHub in the top right corner of this page.

This guide provides some common errors and resolutions encountered in the build process.

Git errors

In the examples below, we use github.com, however error messages are similar for GitLab, Bitbucket etc.

terminal prompts disabled

fatal: could not read Username for 'https://github.com': terminal prompts disabled

Resolution: This error can be quite misleading. It usually occurs when a repository could not be found because of a typo in the repository name or because the repository has been deleted. Verify your repository URL in Admin > Settings.

This error also occurs if you have changed a public repository to private and you are using https:// in your git repository URL.

Note

To use private repositories, you need a plan on Read the Docs for Business.

error: pathspec

error: pathspec 'main' did not match any file(s) known to git

Resolution: A specified branch does not exist in the git repository. This might be because the git repository was recently created (and has no commits nor branches) or because the default branch has changed name. If for instance, the default branch on GitHub changed from master to main, you need to visit Admin > Settings to change the name of the default branch that Read the Docs expects to find when cloning the repository.

Permission denied (publickey)

git@github.com: Permission denied (publickey).

fatal: Could not read from remote repository.

Resolution: The git repository URL points to a repository, user account or organization that Read the Docs does not have credentials for. Verify that the public SSH key from your Read the Docs project is installed as a deploy key on your VCS (GitHub/GitLab/Bitbucket etc):

Navigate to Admin > SSH Keys
Copy the contents of the public key.
Ensure that the key exists as a deploy key at your Git provider. Here are direct links to access settings for verifying and changing deploy keys - customize the URLs for your Git provider and repository details:
- https://github.com/<username>/<repo>/settings/keys
- https://gitlab.com/<username>/<repo>/-/settings/repository
- https://bitbucket.org/<username>/<repo>/admin/access-keys/

ERROR: Repository not found.

ERROR: Repository not found.
fatal: Could not read from remote repository.

Resolution: This error usually occurs on private git repositories that no longer have the public SSH key from their Read the Docs project installed as a deploy key.

Navigate to Admin > SSH Keys
Copy the contents of the public key.
Ensure that the key exists as a deploy key at your Git provider. Here are direct links to access settings for verifying and changing deploy keys - customize the URLs for your VCS host and repository details:
- https://github.com/<username>/<repo>/settings/keys
- https://gitlab.com/<username>/<repo>/-/settings/repository
- https://bitbucket.org/<username>/<repo>/admin/access-keys/

This error is rare for public repositories. If your repository is public and you see this error, it may be because you have specified a wrong domain or forgotten a component in the path.

Troubleshooting slow builds

This page contains a list of the most common issues that are slowing down builds.

In case you are waiting a long time for your builds to finish or your builds are terminated by exceeding general resource limits, this troubleshooting guide will help you resolve some of the most common issues causing slow builds. Even if you are not facing any immediate performance issues, it’s always good to be familiar with the most common ones.

Build resources on Read the Docs are limited to make sure that users don’t overwhelm our build systems. The current build limits can be found on our Build resources reference.

Tip

Please help us keep this section updated and contribute your own error resolutions, performance improvements, etc. Send in your helpful comments or ideas 💡 to support@readthedocs.org or contribute directly by clicking Edit on GitHub in the top right corner of this page.

Reduce formats you’re building

You can change the formats of docs that you’re building with our Configuration file overview, see formats.

In particular, the htmlzip takes up a decent amount of memory and time, so disabling that format might solve your problem.

Reduce documentation build dependencies

A lot of projects reuse their requirements file for their documentation builds. If there are extra packages that you don’t need for building docs, you can create a custom requirements file just for documentation. This should speed up your documentation builds, as well as reduce your memory footprint.

Use mamba instead of conda

If you need conda packages to build your documentation, you can use mamba as a drop-in replacement to conda, which requires less memory and is noticeably faster.

Document Python modules API statically

If you are installing a lot of Python dependencies just to document your Python modules API using sphinx.ext.autodoc, you can give a try to sphinx-autoapi Sphinx’s extension instead which should produce the exact same output but running statically. This could drastically reduce the memory and bandwidth required to build your docs.

Requests more resources

If you still have problems building your documentation, we can increase build limits on a per-project basis, sending an email to support@readthedocs.org providing a good reason why your documentation needs more resources.

Public REST API

This section of the documentation details the public REST API. Useful to get details of projects, builds, versions, and other resources.

API v3

The Read the Docs API uses REST. JSON is returned by all API responses including errors and HTTP response status codes are to designate success and failure.

Authentication and authorization

Requests to the Read the Docs public API are for public and private information. Endpoints that return public information do not require authentication.

Token

The Authorization HTTP header can be specified with Token <your-access-token> to authenticate as a user and have the same permissions that the user itself.

Note

On Read the Docs Community, you will find your access Token under your profile settings.

Session

Session authentication is allowed, so the API can be used by our dashboard and other internal services.

Rate limiting

The API limits unauthenticated requests to 5 per minute and authenticated requests to 60 per minute.

Note

Authenticating your API requests with a token also bypasses most other rate limiting, including network-level blocks that may affect automated scripts accessing Read the Docs from cloud providers or CI environments. If your script is getting 403 Forbidden responses, adding an Authorization: Token <your-access-token> header is the recommended solution.

Pagination

All endpoints that return a list of objects are paginated. By default, 10 objects are returned per page, but you can change this using the limit query parameter. The response includes a count, next, and previous attributes to navigate between pages.

Resources

This section shows all the resources that are currently available in APIv3. There are some URL attributes that applies to all of these resources:

?fields=:: Specify which fields are going to be returned in the response.
?omit=:: Specify which fields are going to be omitted from the response.
?expand=:: Some resources allow to expand/add extra fields on their responses (see Project details for example).

Tip

You can browse the full API by accessing its root URL: https://app.readthedocs.org/api/v3/

Note

If you are using Read the Docs for Business take into account that you will need to replace https://app.readthedocs.org/ by https://app.readthedocs.com/ in all the URLs used in the following examples.

Projects

Projects list

GET /api/v3/projects/

Retrieve a list of all the projects for the current logged in user.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "count": 25,
    "next": "/api/v3/projects/?limit=10&offset=10",
    "previous": null,
    "results": [{
        "id": 12345,
        "name": "Pip",
        "slug": "pip",
        "created": "2010-10-23T18:12:31+00:00",
        "modified": "2018-12-11T07:21:11+00:00",
        "language": {
            "code": "en",
            "name": "English"
        },
        "programming_language": {
            "code": "py",
            "name": "Python"
        },
        "repository": {
            "url": "https://github.com/pypa/pip",
            "type": "git"
        },
        "default_version": "stable",
        "default_branch": "master",
        "subproject_of": null,
        "translation_of": null,
        "urls": {
            "documentation": "http://pip.pypa.io/en/stable/",
            "home": "https://pip.pypa.io/"
        },
        "tags": [
            "distutils",
            "easy_install",
            "egg",
            "setuptools",
            "virtualenv"
        ],
        "users": [
            {
                "username": "dstufft"
            }
        ],
        "active_versions": {
            "stable": "{VERSION}",
            "latest": "{VERSION}",
            "19.0.2": "{VERSION}"
        },
        "_links": {
            "_self": "/api/v3/projects/pip/",
            "versions": "/api/v3/projects/pip/versions/",
            "builds": "/api/v3/projects/pip/builds/",
            "subprojects": "/api/v3/projects/pip/subprojects/",
            "superproject": "/api/v3/projects/pip/superproject/",
            "redirects": "/api/v3/projects/pip/redirects/",
            "translations": "/api/v3/projects/pip/translations/"
        }
    }]
}

Query Parameters:

name (string) – return projects with matching name
slug (string) – return projects with matching slug
language (string) – language code as en, es, ru, etc.
programming_language (string) – programming language code as py, js, etc.

The results in response is an array of project data, which is same as GET /api/v3/projects/(string:project_slug)/.

Note

Read the Docs for Business, also accepts

Query Parameters:

expand (string) – Add additional fields in the response. Allowed values are: organization.

Project details

GET /api/v3/projects/(string: project_slug)/

Retrieve details of a single project.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "id": 12345,
    "name": "Pip",
    "slug": "pip",
    "created": "2010-10-23T18:12:31+00:00",
    "modified": "2018-12-11T07:21:11+00:00",
    "language": {
        "code": "en",
        "name": "English"
    },
    "programming_language": {
        "code": "py",
        "name": "Python"
    },
    "repository": {
        "url": "https://github.com/pypa/pip",
        "type": "git"
    },
    "default_version": "stable",
    "default_branch": "master",
    "subproject_of": null,
    "translation_of": null,
    "urls": {
        "documentation": "http://pip.pypa.io/en/stable/",
        "home": "https://app.readthedocs.org/projects/pip/",
        "downloads": null,
        "builds": "https://app.readthedocs.org/projects/pip/builds/",
        "versions": "https://app.readthedocs.org/projects/pip/versions/",
    },
    "tags": [
        "distutils",
        "easy_install",
        "egg",
        "setuptools",
        "virtualenv"
    ],
    "users": [
        {
            "username": "dstufft"
        }
    ],
    "active_versions": {
        "stable": "{VERSION}",
        "latest": "{VERSION}",
        "19.0.2": "{VERSION}"
    },
    "privacy_level": "public",
    "external_builds_privacy_level": "public",
    "versioning_scheme": "multiple_versions_with_translations",
    "readthedocs_yaml_path": null,
    "_links": {
        "_self": "/api/v3/projects/pip/",
        "versions": "/api/v3/projects/pip/versions/",
        "builds": "/api/v3/projects/pip/builds/",
        "subprojects": "/api/v3/projects/pip/subprojects/",
        "superproject": "/api/v3/projects/pip/superproject/",
        "redirects": "/api/v3/projects/pip/redirects/",
        "translations": "/api/v3/projects/pip/translations/"
    }
}

Query Parameters:

expand (string) – Add additional fields in the response. Allowed values are: active_versions. Multiple fields can be passed separated by commas.

Note

versioning_scheme can be one of the following values:

multiple_versions_with_translations
multiple_versions_without_translations
single_version_without_translations

Note

Read the Docs for Business, also accepts

Query Parameters:

expand (string) – Add additional fields in the response. Allowed values are: organization. We used to return a full organization object in the response, due to privacy concerns, now we return only the slug of the organization. If you need to get the full organization object, you can use the organization endpoint with the slug.

Note

The single_version attribute is deprecated, use versioning_scheme instead.

Note

Previously, translation_of and subproject_of returned a full project object, due to privacy concerns, now they return only the slug of the project. If you need to get the full project object, you can use the project endpoint with the slug.

Project create

POST /api/v3/projects/

Import a project under authenticated user.

Example request:

$ curl \
  -X POST \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/ \
  -H "Content-Type: application/json" \
  -d @body.json

import requests
import json
URL = 'https://app.readthedocs.org/api/v3/projects/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
data = json.load(open('body.json', 'rb'))
response = requests.post(
    URL,
    json=data,
    headers=HEADERS,
)
print(response.json())

The content of body.json is like,

{
    "name": "Test Project",
    "repository": {
        "url": "https://github.com/readthedocs/template",
        "type": "git"
    },
    "homepage": "http://template.readthedocs.io/",
    "programming_language": "py",
    "language": "es",
    "privacy_level": "public",
    "external_builds_privacy_level": "public",
    "readthedocs_yaml_path": "docs/.readthedocs.yaml",
    "tags": [
        "automation",
        "sphinx"
    ]
}

Example response:

See Project details

Note

Read the Docs for Business, also accepts

Request JSON Object:

organization (string) – required organization’s slug under the project will be imported.
teams (string) – optional teams’ slugs the project will belong to.

Note

Privacy levels are only available in Read the Docs for Business.

Project update

PATCH /api/v3/projects/(string: project_slug)/

Update an existing project.

Example request:

$ curl \
  -X PATCH \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/ \
  -H "Content-Type: application/json" \
  -d @body.json

import requests
import json
URL = 'https://app.readthedocs.org/api/v3/projects/pip/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
data = json.load(open('body.json', 'rb'))
response = requests.patch(
    URL,
    json=data,
    headers=HEADERS,
)
print(response.json())

The content of body.json is like,

{
    "name": "New name for the project",
    "repository": {
        "url": "https://github.com/readthedocs/readthedocs.org",
        "type": "git"
    },
    "language": "ja",
    "programming_language": "py",
    "homepage": "https://app.readthedocs.org/",
    "tags" : [
        "extension",
        "mkdocs"
    ]
    "default_version": "v0.27.0",
    "default_branch": "develop",
    "analytics_code": "UA000000",
    "analytics_disabled": false,
    "versioning_scheme": "multiple_versions_with_translations",
    "readthedocs_yaml_path": "docs/.readthedocs.yaml",
    "external_builds_enabled": true,
    "privacy_level": "public",
    "external_builds_privacy_level": "public"
}

Note

Adding tags will replace existing tags with the new list, and if omitted won’t change the tags.

Note

Privacy levels are only available in Read the Docs for Business.

Status Codes:

204 No Content – Updated successfully

Project versions sync

POST /api/v3/projects/(string: project_slug)/sync-versions/

Trigger a background task to sync the versions of the project.

Example request:

$ curl \
  -X POST \
  -H "Authorization: Token <token>" \
  https://app.readthedocs.org/api/v3/projects/pip/sync-versions/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/sync-versions/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.post(
    URL,
    headers=HEADERS,
)
print(response.json())

Status Codes:

202 Accepted – Task created successfully
400 Bad Request – Bad request, task not created

Versions

Versions are different versions of the same project documentation.

The versions for a given project can be viewed in a project’s version page. For example, here is the Pip project’s version page. See Versions for more information.

Versions listing

GET /api/v3/projects/(string: project_slug)/versions/

Retrieve a list of all versions for a project.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/versions/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/versions/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "count": 25,
    "next": "/api/v3/projects/pip/versions/?limit=10&offset=10",
    "previous": null,
    "results": ["VERSION"]
}

Query Parameters:

active (boolean) – return only active versions
built (boolean) – return only built versions
privacy_level (string) – return versions with specific privacy level (public or private)
slug (string) – return versions with matching slug
type (string) – return versions with specific type (branch or tag)
verbose_name (string) – return versions with matching version name

Version detail

GET /api/v3/projects/(string: project_slug)/versions/(string: version_slug)/

Retrieve details of a single version.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/versions/stable/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/versions/stable/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "id": 71652437,
    "slug": "stable",
    "verbose_name": "stable",
    "identifier": "3a6b3995c141c0888af6591a59240ba5db7d9914",
    "ref": "19.0.2",
    "built": true,
    "active": true,
    "aliases": ["VERSION"],
    "hidden": false,
    "type": "tag",
    "privacy_level": "public",
    "downloads": {
        "pdf": "https://pip.readthedocs.io/_/downloads/pdf/pip/stable/",
        "htmlzip": "https://pip.readthedocs.io/_/downloads/htmlzip/pip/stable/",
        "epub": "https://pip.readthedocs.io/_/downloads/epub/pip/stable/"
    },
    "urls": {
        "dashboard": {
            "edit": "https://app.readthedocs.org/dashboard/pip/version/stable/edit/"
        },
        "documentation": "https://pip.pypa.io/en/stable/",
        "vcs": "https://github.com/pypa/pip/tree/19.0.2"
    },
    "_links": {
        "_self": "/api/v3/projects/pip/versions/stable/",
        "builds": "/api/v3/projects/pip/versions/stable/builds/",
        "project": "/api/v3/projects/pip/"
    }
}

Response JSON Object:

ref (string) – the version slug where the stable version points to. null when it’s not the stable version.
built (boolean) – the version has at least one successful build.

Version update

PATCH /api/v3/projects/(string: project_slug)/versions/(string: version_slug)/

Update a version.

When a version is deactivated, its documentation is removed, and when it’s activated, a new build is triggered.

Updates to a version also invalidates its CDN cache.

Example request:

$ curl \
  -X PATCH \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/versions/0.23/ \
  -H "Content-Type: application/json" \
  -d @body.json

import requests
import json
URL = 'https://app.readthedocs.org/api/v3/projects/pip/versions/0.23/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
data = json.load(open('body.json', 'rb'))
response = requests.patch(
    URL,
    json=data,
    headers=HEADERS,
)
print(response.json())

The content of body.json is like,

{
    "active": true,
    "hidden": false,
    "privacy_level": "public"
}

Status Codes:

204 No Content – Updated successfully

Note

Privacy levels are only available in Read the Docs for Business.

Builds

Builds are created by Read the Docs whenever a Project has its documentation built. Frequently this happens automatically via a web hook but can be triggered manually.

Builds can be viewed in the build page for a project. For example, here is Pip’s build page. See Build process overview for more information.

Build details

GET /api/v3/projects/(str: project_slug)/builds/(int: build_id)/

Retrieve details of a single build for a project.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/builds/8592686/?expand=config

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/builds/8592686/?expand=config'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "id": 8592686,
    "version": "latest",
    "project": "pip",
    "created": "2018-06-19T15:15:59+00:00",
    "finished": "2018-06-19T15:16:58+00:00",
    "duration": 59,
    "state": {
        "code": "finished",
        "name": "Finished"
    },
    "success": true,
    "error": null,
    "commit": "6f808d743fd6f6907ad3e2e969c88a549e76db30",
    "config": {
        "version": "1",
        "formats": [
            "htmlzip",
            "epub",
            "pdf"
        ],
        "python": {
            "version": 3,
            "install": [
                {
                    "requirements": ".../stable/tools/docs-requirements.txt"
                }
            ],
        },
        "conda": null,
        "build": {
            "image": "readthedocs/build:latest"
        },
        "doctype": "sphinx_htmldir",
        "sphinx": {
            "builder": "sphinx_htmldir",
            "configuration": ".../stable/docs/html/conf.py",
            "fail_on_warning": false
        },
        "mkdocs": {
            "configuration": null,
            "fail_on_warning": false
        },
        "submodules": {
            "include": "all",
            "exclude": [],
            "recursive": true
        }
    },
    "_links": {
        "_self": "/api/v3/projects/pip/builds/8592686/",
        "project": "/api/v3/projects/pip/",
        "version": "/api/v3/projects/pip/versions/latest/"
    }
}

Response JSON Object:

created (string) – The ISO-8601 datetime when the build was created.
finished (string) – The ISO-8601 datetime when the build has finished.
duration (integer) – The length of the build in seconds.
state (string) – The state of the build (one of triggered, building, installing, cloning, finished or cancelled)
error (string) – An error message if the build was unsuccessful

Query Parameters:

expand (string) – Add additional fields in the response. Allowed value is config.

Builds listing

GET /api/v3/projects/(str: project_slug)/builds/

Retrieve list of all the builds on this project.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/builds/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/builds/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "count": 15,
    "next": "/api/v3/projects/pip/builds?limit=10&offset=10",
    "previous": null,
    "results": ["BUILD"]
}

Query Parameters:

commit (string) – commit hash to filter the builds returned by commit
running (boolean) – filter the builds that are currently building/running

Build triggering

POST /api/v3/projects/(string: project_slug)/versions/(string: version_slug)/builds/

Trigger a new build for the version_slug version of this project.

Example request:

$ curl \
  -X POST \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/versions/latest/builds/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/versions/latest/builds/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.post(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "build": "{BUILD}",
    "project": "{PROJECT}",
    "version": "{VERSION}"
}

Status Codes:

202 Accepted – the build was triggered

Subprojects

Projects can be configured in a nested manner, by configuring a project as a subproject of another project. This allows for documentation projects to share a search index and a namespace or custom domain, but still be maintained independently. See Subprojects for more information.

Subproject details

GET /api/v3/projects/(str: project_slug)/subprojects/(str: alias_slug)/

Retrieve details of a subproject relationship.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/subprojects/subproject-alias/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/subprojects/subproject-alias/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "alias": "subproject-alias",
    "child": ["PROJECT"],
    "_links": {
        "parent": "/api/v3/projects/pip/"
    }
}

Subprojects listing

GET /api/v3/projects/(str: project_slug)/subprojects/

Retrieve a list of all sub-projects for a project.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/subprojects/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/subprojects/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "count": 25,
    "next": "/api/v3/projects/pip/subprojects/?limit=10&offset=10",
    "previous": null,
    "results": ["SUBPROJECT RELATIONSHIP"]
}

Subproject create

POST /api/v3/projects/(str: project_slug)/subprojects/

Create a subproject relationship between two projects.

Example request:

$ curl \
  -X POST \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/subprojects/ \
  -H "Content-Type: application/json" \
  -d @body.json

import requests
import json
URL = 'https://app.readthedocs.org/api/v3/projects/pip/subprojects/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
data = json.load(open('body.json', 'rb'))
response = requests.post(
    URL,
    json=data,
    headers=HEADERS,
)
print(response.json())

The content of body.json is like,

{
    "child": "subproject-child-slug",
    "alias": "subproject-alias"
}

Note

child must be a project that you have access to. Or if you are using Business hosting, additionally the project must be under the same organization as the parent project.

Example response:

See Subproject details

Response JSON Object:

child (string) – slug of the child project in the relationship.
alias (string) – optional slug alias to be used in the URL (e.g /projects/<alias>/en/latest/). If not provided, child project’s slug is used as alias.

Status Codes:

201 Created – Subproject created successfully

Subproject delete

DELETE /api/v3/projects/(str: project_slug)/subprojects/(str: alias_slug)/

Delete a subproject relationship.

Example request:

$ curl \
  -X DELETE \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/subprojects/subproject-alias/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/subprojects/subproject-alias/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.delete(URL, headers=HEADERS)
print(response.json())

Status Codes:

204 No Content – Subproject deleted successfully

Translations

Translations are the same version of a Project in a different language. See Localization and Internationalization for more information.

Translations listing

GET /api/v3/projects/(str: project_slug)/translations/

Retrieve a list of all translations for a project.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/translations/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/translations/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "count": 25,
    "next": "/api/v3/projects/pip/translations/?limit=10&offset=10",
    "previous": null,
    "results": [{
        "id": 12345,
        "name": "Pip",
        "slug": "pip",
        "created": "2010-10-23T18:12:31+00:00",
        "modified": "2018-12-11T07:21:11+00:00",
        "language": {
            "code": "en",
            "name": "English"
        },
        "programming_language": {
            "code": "py",
            "name": "Python"
        },
        "repository": {
            "url": "https://github.com/pypa/pip",
            "type": "git"
        },
        "default_version": "stable",
        "default_branch": "master",
        "subproject_of": null,
        "translation_of": null,
        "urls": {
            "documentation": "http://pip.pypa.io/en/stable/",
            "home": "https://pip.pypa.io/"
        },
        "tags": [
            "distutils",
            "easy_install",
            "egg",
            "setuptools",
            "virtualenv"
        ],
        "users": [
            {
                "username": "dstufft"
            }
        ],
        "active_versions": {
            "stable": "{VERSION}",
            "latest": "{VERSION}",
            "19.0.2": "{VERSION}"
        },
        "_links": {
            "_self": "/api/v3/projects/pip/",
            "versions": "/api/v3/projects/pip/versions/",
            "builds": "/api/v3/projects/pip/builds/",
            "subprojects": "/api/v3/projects/pip/subprojects/",
            "superproject": "/api/v3/projects/pip/superproject/",
            "redirects": "/api/v3/projects/pip/redirects/",
            "translations": "/api/v3/projects/pip/translations/"
        }
    }]
}

The results in response is an array of project data, which is same as GET /api/v3/projects/(string:project_slug)/.

Redirects

Redirects allow the author to redirect an old URL of the documentation to a new one. This is useful when pages are moved around in the structure of the documentation set. See Redirects for more information.

Redirect details

GET /api/v3/projects/(str: project_slug)/redirects/(int: redirect_id)/

Retrieve details of a single redirect for a project.

Example request

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/redirects/1/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/redirects/1/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response

{
    "pk": 1,
    "created": "2019-04-29T10:00:00Z",
    "modified": "2019-04-29T12:00:00Z",
    "project": "pip",
    "from_url": "/docs/",
    "to_url": "/documentation/",
    "type": "page",
    "http_status": 302,
    "description": "",
    "enabled": true,
    "force": false,
    "position": 0,
    "_links": {
        "_self": "/api/v3/projects/pip/redirects/1/",
        "project": "/api/v3/projects/pip/"
    }
}

Redirects listing

GET /api/v3/projects/(str: project_slug)/redirects/

Retrieve list of all the redirects for this project.

Example request

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/redirects/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/redirects/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response

{
    "count": 25,
    "next": "/api/v3/projects/pip/redirects/?limit=10&offset=10",
    "previous": null,
    "results": ["REDIRECT"]
}

Redirect create

POST /api/v3/projects/(str: project_slug)/redirects/

Create a redirect for this project.

Example request:

$ curl \
  -X POST \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/redirects/ \
  -H "Content-Type: application/json" \
  -d @body.json

import requests
import json
URL = 'https://app.readthedocs.org/api/v3/projects/pip/redirects/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
data = json.load(open('body.json', 'rb'))
response = requests.post(
    URL,
    json=data,
    headers=HEADERS,
)
print(response.json())

The content of body.json is like,

{
    "from_url": "/docs/",
    "to_url": "/documentation/",
    "type": "page",
    "position": 0,
    "force": false,
    "enabled": true,
    "description": "Redirect old docs to new location",
    "http_status": 302
}

Note

type (required) can be one of page, exact, clean_url_to_html and html_to_clean_url.
Depending on the type of the redirect, some fields may not be needed:
- page and exact types require from_url and to_url.
- clean_url_to_html and html_to_clean_url types do not require from_url and to_url.
position (optional, default: 0) - Order of execution. Position starts at 0 and is used to order redirects.
force (optional, default: false) - Apply the redirect even if the page exists.
enabled (optional, default: true) - Enable or disable the redirect.
description (optional) - A description for the redirect.
http_status (optional, default: 302) - HTTP status code, can be 301 (permanent) or 302 (temporary).

Example response:

See Redirect details

Status Codes:

201 Created – redirect created successfully

Redirect update

PUT /api/v3/projects/(str: project_slug)/redirects/(int: redirect_id)/

Update a redirect for this project.

Example request:

$ curl \
  -X PUT \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/redirects/1/ \
  -H "Content-Type: application/json" \
  -d @body.json

import requests
import json
URL = 'https://app.readthedocs.org/api/v3/projects/pip/redirects/1/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
data = json.load(open('body.json', 'rb'))
response = requests.put(
    URL,
    json=data,
    headers=HEADERS,
)
print(response.json())

The content of body.json is like,

{
    "from_url": "/docs/",
    "to_url": "/documentation.html",
    "type": "page"
}

Note

If the position of the redirect is changed, it will be inserted in the new position and the other redirects will be reordered.

Example response:

See Redirect details

Redirect delete

DELETE /api/v3/projects/(str: project_slug)/redirects/(int: redirect_id)/

Delete a redirect for this project.

Example request:

$ curl \
  -X DELETE \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/redirects/1/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/redirects/1/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.delete(URL, headers=HEADERS)
print(response.json())

Status Codes:

204 No Content – Redirect deleted successfully

Environment variables

Environment variables are variables that you can define for your project. These variables are used in the build process when building your documentation. They are for example useful to define secrets in a safe way that can be used by your documentation to build properly. Environment variables can also be made public, allowing for them to be used in PR builds. See Environment variable overview.

Environment variable details

GET /api/v3/projects/(str: project_slug)/environmentvariables/(int: environmentvariable_id)/

Retrieve details of a single environment variable for a project.

Example request

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/environmentvariables/1/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/environmentvariables/1/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response

{
    "_links": {
        "_self": "https://app.readthedocs.org/api/v3/projects/project/environmentvariables/1/",
        "project": "https://app.readthedocs.org/api/v3/projects/project/"
    },
"created": "2019-04-29T10:00:00Z",
"modified": "2019-04-29T12:00:00Z",
"pk": 1,
"project": "project",
"public": false,
"name": "ENVVAR"
}

Environment variables listing

GET /api/v3/projects/(str: project_slug)/environmentvariables/

Retrieve list of all the environment variables for this project.

Example request

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/environmentvariables/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/environmentvariables/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response

{
    "count": 15,
    "next": "/api/v3/projects/pip/environmentvariables/?limit=10&offset=10",
    "previous": null,
    "results": ["ENVIRONMENTVARIABLE"]
}

Environment variable create

POST /api/v3/projects/(str: project_slug)/environmentvariables/

Create an environment variable for this project.

Example request:

$ curl \
  -X POST \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/environmentvariables/ \
  -H "Content-Type: application/json" \
  -d @body.json

import requests
import json
URL = 'https://app.readthedocs.org/api/v3/projects/pip/environmentvariables/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
data = json.load(open('body.json', 'rb'))
response = requests.post(
    URL,
    json=data,
    headers=HEADERS,
)
print(response.json())

The content of body.json is like,

{
    "name": "MYVAR",
    "value": "My secret value",
    "public": true
}

Example response:

See Environment Variable details

Status Codes:

201 Created – Environment variable created successfully

Note

The public field is optional. If set to true, the environment variable will be exposed in PR builds. Defaults to false.

Environment variable delete

DELETE /api/v3/projects/(str: project_slug)/environmentvariables/(int: environmentvariable_id)/

Delete an environment variable for this project.

Example request:

$ curl \
  -X DELETE \
  -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/projects/pip/environmentvariables/1/

import requests
URL = 'https://app.readthedocs.org/api/v3/projects/pip/environmentvariables/1/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.delete(URL, headers=HEADERS)
print(response.json())

Request Headers:

Authorization – token to authenticate.

Status Codes:

204 No Content – Environment variable deleted successfully

Organizations

Note

The /api/v3/organizations/ endpoint is only available in Read the Docs for Business currently. We plan to have organizations on Read the Docs Community in a near future and we will add support for this endpoint at the same time.

Organizations list

GET /api/v3/organizations/

Retrieve a list of all the organizations for the current logged in user.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.com/api/v3/organizations/

import requests
URL = 'https://app.readthedocs.com/api/v3/organizations/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "_links": {
                "_self": "https://app.readthedocs.com/api/v3/organizations/pypa/",
                "projects": "https://app.readthedocs.com/api/v3/organizations/pypa/projects/"
            },
            "created": "2019-02-22T21:54:52.768630Z",
            "description": "",
            "disabled": false,
            "email": "pypa@psf.org",
            "modified": "2020-07-02T12:35:32.418423Z",
            "name": "Python Package Authority",
            "owners": [
                {
                    "username": "dstufft"
                }
            ],
            "slug": "pypa",
            "url": "https://github.com/pypa/"
        }
}

Organization details

GET /api/v3/organizations/(string: organization_slug)/

Retrieve details of a single organization.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.com/api/v3/organizations/pypa/

import requests
URL = 'https://app.readthedocs.com/api/v3/organizations/pypa/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "_links": {
        "_self": "https://app.readthedocs.com/api/v3/organizations/pypa/",
        "projects": "https://app.readthedocs.com/api/v3/organizations/pypa/projects/"
    },
    "created": "2019-02-22T21:54:52.768630Z",
    "description": "",
    "disabled": false,
    "email": "pypa@psf.com",
    "modified": "2020-07-02T12:35:32.418423Z",
    "name": "Python Package Authority",
    "owners": [
        {
            "username": "dstufft"
        }
    ],
    "slug": "pypa",
    "url": "https://github.com/pypa/"
}

Organization projects list

GET /api/v3/organizations/(string: organization_slug)/projects/

Retrieve list of projects under an organization.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.com/api/v3/organizations/pypa/projects/

import requests
URL = 'https://app.readthedocs.com/api/v3/organizations/pypa/projects/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "_links": {
                "_self": "https://app.readthedocs.com/api/v3/projects/pypa-pip/",
                "builds": "https://app.readthedocs.com/api/v3/projects/pypa-pip/builds/",
                "environmentvariables": "https://app.readthedocs.com/api/v3/projects/pypa-pip/environmentvariables/",
                "redirects": "https://app.readthedocs.com/api/v3/projects/pypa-pip/redirects/",
                "subprojects": "https://app.readthedocs.com/api/v3/projects/pypa-pip/subprojects/",
                "superproject": "https://app.readthedocs.com/api/v3/projects/pypa-pip/superproject/",
                "translations": "https://app.readthedocs.com/api/v3/projects/pypa-pip/translations/",
                "versions": "https://app.readthedocs.com/api/v3/projects/pypa-pip/versions/"
            },
            "created": "2019-02-22T21:59:13.333614Z",
            "default_branch": "master",
            "default_version": "latest",
            "homepage": null,
            "id": 2797,
            "language": {
                "code": "en",
                "name": "English"
            },
            "modified": "2019-08-08T16:27:25.939531Z",
            "name": "pip",
            "programming_language": {
                "code": "py",
                "name": "Python"
            },
            "repository": {
                "type": "git",
                "url": "https://github.com/pypa/pip"
            },
            "slug": "pypa-pip",
            "subproject_of": null,
            "tags": [],
            "translation_of": null,
            "urls": {
                "builds": "https://app.readthedocs.com/projects/pypa-pip/builds/",
                "documentation": "https://pypa-pip.readthedocs-hosted.com/en/latest/",
                "home": "https://app.readthedocs.com/projects/pypa-pip/",
                "versions": "https://app.readthedocs.com/projects/pypa-pip/versions/"
            }
        }
    ]
}

Organization teams list

GET /api/v3/organizations/(string: organization_slug)/teams/

Retrieve list of teams under an organization.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.com/api/v3/organizations/pypa/teams/

import requests
URL = 'https://app.readthedocs.com/api/v3/organizations/pypa/teams/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
   "count": 2,
   "next": null,
   "previous": null,
   "results": [
      {
            "access": "admin",
            "created": "2024-07-01T21:19:55.573819Z",
            "modified": "2024-07-01T21:19:55.573837Z",
            "name": "Admins",
            "slug": "admins"
      },
      {
            "access": "readonly",
            "created": "2024-07-01T21:19:55.593815Z",
            "modified": "2024-07-01T21:19:55.593829Z",
            "name": "Read Only",
            "slug": "read-only"
      }
   ]
}

Query Parameters:

expand (string) – Add additional fields in the response. Allowed values are: members.

Remote organizations

Remote organizations are the VCS organizations connected via GitHub, GitLab and Bitbucket.

Remote organization listing

GET /api/v3/remote/organizations/

Retrieve a list of all Remote Organizations for the authenticated user.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/remote/organizations/

import requests
URL = 'https://app.readthedocs.org/api/v3/remote/organizations/'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "count": 20,
    "next": "api/v3/remote/organizations/?limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "avatar_url": "https://avatars.githubusercontent.com/u/12345?v=4",
            "created": "2019-04-29T10:00:00Z",
            "modified": "2019-04-29T12:00:00Z",
            "name": "Organization Name",
            "pk": 1,
            "slug": "organization",
            "url": "https://github.com/organization",
            "vcs_provider": "github"
        }
    ]
}

The results in response is an array of remote organizations data.

Query Parameters:

name (string) – return remote organizations with containing the name
vcs_provider (string) – return remote organizations for specific vcs provider (github, gitlab or bitbucket)

Request Headers:

Authorization – token to authenticate.

Remote repositories

Remote repositories are the importable repositories connected via GitHub, GitLab and Bitbucket.

Remote repository listing

GET /api/v3/remote/repositories/

Retrieve a list of all Remote Repositories for the authenticated user.

Example request:

$ curl -H "Authorization: Token <token>" https://app.readthedocs.org/api/v3/remote/repositories/?expand=remote_organization

import requests
URL = 'https://app.readthedocs.org/api/v3/remote/repositories/?expand=remote_organization'
TOKEN = '<token>'
HEADERS = {'Authorization': f'token {TOKEN}'}
response = requests.get(URL, headers=HEADERS)
print(response.json())

Example response:

{
    "count": 20,
    "next": "api/v3/remote/repositories/?expand=remote_organization&limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "remote_organization": {
                "avatar_url": "https://avatars.githubusercontent.com/u/12345?v=4",
                "created": "2019-04-29T10:00:00Z",
                "modified": "2019-04-29T12:00:00Z",
                "name": "Organization Name",
                "pk": 1,
                "slug": "organization",
                "url": "https://github.com/organization",
                "vcs_provider": "github"
            },
            "projects": [{
                "id": 12345,
                "name": "project",
                "slug": "project",
                "created": "2010-10-23T18:12:31+00:00",
                "modified": "2018-12-11T07:21:11+00:00",
                "language": {
                    "code": "en",
                    "name": "English"
                },
                "programming_language": {
                    "code": "py",
                    "name": "Python"
                },
                "repository": {
                    "url": "https://github.com/organization/project",
                    "type": "git"
                },
                "default_version": "stable",
                "default_branch": "master",
                "subproject_of": null,
                "translation_of": null,
                "urls": {
                    "documentation": "http://project.readthedocs.io/en/stable/",
                    "home": "https://app.readthedocs.org/projects/project/"
                },
                "tags": [
                    "test"
                ],
                "users": [
                    {
                        "username": "dstufft"
                    }
                ],
                "_links": {
                    "_self": "/api/v3/projects/project/",
                    "versions": "/api/v3/projects/project/versions/",
                    "builds": "/api/v3/projects/project/builds/",
                    "subprojects": "/api/v3/projects/project/subprojects/",
                    "superproject": "/api/v3/projects/project/superproject/",
                    "redirects": "/api/v3/projects/project/redirects/",
                    "translations": "/api/v3/projects/project/translations/"
                }
            }],
            "avatar_url": "https://avatars3.githubusercontent.com/u/test-organization?v=4",
            "clone_url": "https://github.com/organization/project.git",
            "created": "2019-04-29T10:00:00Z",
            "description": "This is a test project.",
            "full_name": "organization/project",
            "html_url": "https://github.com/organization/project",
            "modified": "2019-04-29T12:00:00Z",
            "name": "project",
            "pk": 1,
            "ssh_url": "git@github.com:organization/project.git",
            "vcs": "git",
            "vcs_provider": "github",
            "default_branch": "master",
            "private": false,
            "admin": true
        }
    ]
}

The results in response is an array of remote repositories data.

Query Parameters:

name (string) – return remote repositories containing the name
full_name (string) – return remote repositories containing the full name (it includes the username/organization the project belongs to)
vcs_provider (string) – return remote repositories for specific vcs provider (github, gitlab or bitbucket)
organization (string) – return remote repositories for specific remote organization (using remote organization slug)
expand (string) – Add additional fields in the response. Allowed values are: remote_organization. Multiple fields can be passed separated by commas.

Request Headers:

Authorization – token to authenticate.

Embed

GET /api/v3/embed/

Retrieve HTML-formatted content from documentation page or section. Read How to embed content from your documentation to know more about how to use this endpoint.

Warning

The content will be returned as is, without any sanitization or escaping. You should not include content from arbitrary projects, or projects you do not trust.

Example request:

curl https://app.readthedocs.org/api/v3/embed/?url=https://docs.readthedocs.com/platform/stable/reference/features.html%23feature-reference

Example response:

{
    "url": "https://docs.readthedocs.com/platform/stable/reference/features.html#feature-reference",
    "fragment": "feature-reference",
    "content": "<section id=\"feature-reference\">\n<h1>Feature reference ...",
    "external": false
}

Response JSON Object:

url (string) – URL of the document.
fragment (string) – fragmet part of the URL used to query the page.
content (string) – HTML content of the section.
external (string) – whether or not the page is hosted on Read the Docs or externally.

Query Parameters:

url (string) – full URL of the document (with optional fragment) to fetch content from.
doctool (string) – optional documentation tool key name used to generate the target documentation (currently, only sphinx is accepted)
doctoolversion (string) – optional documentation tool version used to generate the target documentation (e.g. 4.2.0).
maincontent (string) – optional CSS selector for the main content of the page (e.g. div#main).

Note

Passing ?doctool=, ?doctoolversion= and ?maincontent= may improve the response since the endpoint will know more about the exact structure of the HTML and can make better decisions.

Additional APIs

Server side search API.

API v2

The Read the Docs API uses REST. JSON is returned by all API responses including errors and HTTP response status codes are to designate success and failure.

Warning

API v2 is planned to be deprecated soon, though we have not yet set a time frame for deprecation yet. We will alert users with our plans when we do.

For now, API v2 is still used by some legacy application operations still, but we highly recommend Read the Docs users use API v3 instead.

Some improvements in API v3 are:

Token based authentication
Easier to use URLs which no longer use numerical ids
More common user actions are exposed through the API
Improved error reporting

See its full documentation at API v3.

Authentication and authorization

Requests to the Read the Docs public API are for public information only and do not require any authentication.

Resources

Projects

Projects are the main building block of Read the Docs. Projects are built when there are changes to the code and the resulting documentation is hosted and served by Read the Docs.

As an example, this documentation is part of the Docs project which has documentation at https://docs.readthedocs.io.

You can always view your Read the Docs projects in your project dashboard.

Project list

GET /api/v2/project/

Retrieve a list of all Read the Docs projects.

Example request:

curl https://app.readthedocs.org/api/v2/project/?slug=pip

Example response:

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [PROJECTS]
}

Response JSON Object:

next (string) – URI for next set of Projects.
previous (string) – URI for previous set of Projects.
count (integer) – Total number of Projects.
results (array) – Array of Project objects.

Query Parameters:

slug (string) – Narrow the results by matching the exact project slug

Project details

GET /api/v2/project/(int: id)/

Retrieve details of a single project.

{
    "id": 6,
    "name": "Pip",
    "slug": "pip",
    "programming_language": "py",
    "default_version": "stable",
    "default_branch": "master",
    "repo_type": "git",
    "repo": "https://github.com/pypa/pip",
    "description": "Pip Installs Packages.",
    "language": "en",
    "documentation_type": "sphinx_htmldir",
    "canonical_url": "http://pip.pypa.io/en/stable/",
    "users": [USERS]
}

Response JSON Object:

id (integer) – The ID of the project
name (string) – The name of the project.
slug (string) – The project slug (used in the URL).
programming_language (string) – The programming language of the project (eg. “py”, “js”)
default_version (string) – The default version of the project (eg. “latest”, “stable”, “v3”)
default_branch (string) – The default version control branch
repo_type (string) – Version control repository of the project
repo (string) – The repository URL for the project
description (string) – An RST description of the project
language (string) – The language code of this project
documentation_type (string) – An RST description of the project
canonical_url (string) – The canonical URL of the default docs
users (array) – Array of User IDs who are maintainers of the project.

Status Codes:

200 OK – no error
404 Not Found – There is no Project with this ID

Project versions

GET /api/v2/project/(int: id)/active_versions/

Retrieve a list of active versions (eg. “latest”, “stable”, “v1.x”) for a single project.

{
    "versions": [VERSION, VERSION, ...]
}

Response JSON Object:

versions (array) – Version objects for the given Project

See the Version detail call for the format of the Version object.

Versions

Versions are different versions of the same project documentation

The versions for a given project can be viewed in a project’s version screen. For example, here is the Pip project’s version screen.

Version list

GET /api/v2/version/

Retrieve a list of all Versions for all projects

{
    "count": 1000,
    "previous": null,
    "results": [VERSIONS],
    "next": "https://app.readthedocs.org/api/v2/version/?limit=10&offset=10"
}

Response JSON Object:

next (string) – URI for next set of Versions.
previous (string) – URI for previous set of Versions.
count (integer) – Total number of Versions.
results (array) – Array of Version objects.

Query Parameters:

project__slug (string) – Narrow to the versions for a specific Project
active (boolean) – Pass true or false to show only active or inactive versions. By default, the API returns all versions.

Version detail

GET /api/v2/version/(int: id)/

Retrieve details of a single version.

{
    "id": 1437428,
    "slug": "stable",
    "verbose_name": "stable",
    "built": true,
    "active": true,
    "type": "tag",
    "identifier": "3a6b3995c141c0888af6591a59240ba5db7d9914",
    "privacy_level": "public",
    "downloads": {
        "pdf": "//readthedocs.org/projects/pip/downloads/pdf/stable/",
        "htmlzip": "//readthedocs.org/projects/pip/downloads/htmlzip/stable/",
        "epub": "//readthedocs.org/projects/pip/downloads/epub/stable/"
    },
    "project": {PROJECT},
}

Response JSON Object:

id (integer) – The ID of the version
verbose_name (string) – The name of the version.
slug (string) – The version slug.
built (string) – Whether this version has been built
active (string) – Whether this version is still active
type (string) – The type of this version (typically “tag” or “branch”)
identifier (string) – A version control identifier for this version (eg. the commit hash of the tag)
downloads (array) – URLs to downloads of this version’s documentation
project (object) – Details of the Project for this version.

Status Codes:

200 OK – no error
404 Not Found – There is no Version with this ID

Builds

Builds are created by Read the Docs whenever a Project has its documentation built. Frequently this happens automatically via a web hook but can be triggered manually.

Builds can be viewed in the build screen for a project. For example, here is Pip’s build screen.

Build list

GET /api/v2/build/

Retrieve details of builds ordered by most recent first

Example request:

curl https://app.readthedocs.org/api/v2/build/?project__slug=pip

Example response:

{
    "count": 100,
    "next": null,
    "previous": null,
    "results": [BUILDS]
}

Response JSON Object:

next (string) – URI for next set of Builds.
previous (string) – URI for previous set of Builds.
count (integer) – Total number of Builds.
results (array) – Array of Build objects.

Query Parameters:

project__slug (string) – Narrow to builds for a specific Project
commit (string) – Narrow to builds for a specific commit

Build detail

GET /api/v2/build/(int: id)/

Retrieve details of a single build.

{
    "id": 7367364,
    "date": "2018-06-19T15:15:59.135894",
    "length": 59,
    "type": "html",
    "state": "finished",
    "success": true,
    "error": "",
    "commit": "6f808d743fd6f6907ad3e2e969c88a549e76db30",
    "docs_url": "http://pip.pypa.io/en/latest/",
    "project": 13,
    "project_slug": "pip",
    "version": 3681,
    "version_slug": "latest",
    "commands": [
        {
            "description": "",
            "start_time": "2018-06-19T20:16:00.951959",
            "exit_code": 0,
            "build": 7367364,
            "command": "git remote set-url origin git://github.com/pypa/pip.git",
            "run_time": 0,
            "output": "",
            "id": 42852216,
            "end_time": "2018-06-19T20:16:00.969170"
        },
        ...
    ],
    ...
}

Response JSON Object:

id (integer) – The ID of the build
date (string) – The ISO-8601 datetime of the build.
length (integer) – The length of the build in seconds.
type (string) – The type of the build (one of “html”, “pdf”, “epub”)
state (string) – The state of the build (one of “triggered”, “building”, “installing”, “cloning”, or “finished”)
success (boolean) – Whether the build was successful
error (string) – An error message if the build was unsuccessful
commit (string) – A version control identifier for this build (eg. the commit hash)
docs_url (string) – The canonical URL of the build docs
project (integer) – The ID of the project being built
project_slug (string) – The slug for the project being built
version (integer) – The ID of the version of the project being built
version_slug (string) – The slug for the version of the project being built
commands (array) – Array of commands for the build with details including output.

Status Codes:

200 OK – no error
404 Not Found – There is no Build with this ID

Some fields primarily used for UI elements in Read the Docs are omitted.

Embed

GET /api/v2/embed/

Deprecated since version 2024-11: The embed API v2 has been deprecated and is no longer available. Use embed API v3 instead.

Retrieve HTML-formatted content from documentation page or section.

Warning

The content will be returned as is, without any sanitization or escaping. You should not include content from arbitrary projects, or projects you do not trust.

Example request:

curl https://app.readthedocs.org/api/v2/embed/?url=https://docs.readthedocs.com/platform/stable/reference/features.html

Response JSON Object:

content (string) – HTML content of the section.
headers (object) – section’s headers in the document.
url (string) – URL of the document.
meta (object) – meta data of the requested section.

Query Parameters:

project (string) – Read the Docs project’s slug.
doc (string) – document to fetch content from.
version (string) – optional Read the Docs version’s slug (default: latest).
section (string) – optional section within the document to fetch.
path (string) – optional full path to the document including extension.
url (string) – full URL of the document (and section) to fetch content from.

Note

You can call this endpoint by sending at least project and doc or url attribute.

Undocumented resources and endpoints

There are some undocumented endpoints in the API. These should not be used and could change at any time. These include:

Endpoints for returning footer and version data to be injected into docs. (/api/v2/footer_html)
Endpoints used for advertising (/api/v2/sustainability/)
Any other endpoints not detailed above.

Server side search API

You can integrate our server side search in your documentation by using our API.

If you are using Business hosting you will need to replace https://app.readthedocs.org/ with https://app.readthedocs.com/ in all the URLs used in the following examples. Check Authentication and authorization if you are using private versions.

API v3

GET /api/v3/search/

Return a list of search results for a project or subset of projects. Results are divided into sections with highlights of the matching term.

Query Parameters:

q – Search query (see Search query syntax)
page – Jump to a specific page
page_size – Limits the results per page, default is 50

Response JSON Object:

type (string) – The type of the result, currently page is the only type.
project (string) – The project object
version (string) – The version object
title (string) – The title of the page
domain (string) – Canonical domain of the resulting page
path (string) – Path to the resulting page
highlights (object) – An object containing a list of substrings with matching terms. Note that the text is HTML escaped with the matching terms inside a <span> tag.
blocks (object) –
A list of block objects containing search results from the page. Currently, there is one type of block:
- section: A page section with a linkable anchor (id attribute).

Warning

Except for highlights, any other content is not HTML escaped, you shouldn’t include it in your page without escaping it first.

Example request:

$ curl "https://app.readthedocs.org/api/v3/search/?q=project:docs%20server%20side%20search"

import requests
URL = 'https://app.readthedocs.org/api/v3/search/'
params = {
   'q': 'project:docs server side search',
}
response = requests.get(URL, params=params)
print(response.json())

Example response:

{
    "count": 41,
    "next": "https://app.readthedocs.org/api/v3/search/?page=2&q=project:docs%20server+side+search",
    "previous": null,
    "projects": [
       {
         "slug": "docs",
         "versions": [
           {"slug": "latest"}
         ]
       }
    ],
    "query": "server side search",
    "results": [
        {
            "type": "page",
            "project": {
               "slug": "docs",
               "alias": null
            },
            "version": {
               "slug": "latest"
            },
            "title": "Server Side Search",
            "domain": "https://docs.readthedocs.io",
            "path": "/en/latest/server-side-search.html",
            "highlights": {
                "title": [
                    "<span>Server</span> <span>Side</span> <span>Search</span>"
                ]
            },
            "blocks": [
               {
                  "type": "section",
                  "id": "server-side-search",
                  "title": "Server Side Search",
                  "content": "Read the Docs provides full-text search across all of the pages of all projects, this is powered by Elasticsearch.",
                  "highlights": {
                     "title": [
                        "<span>Server</span> <span>Side</span> <span>Search</span>"
                     ],
                     "content": [
                        "You can <span>search</span> all projects at https:&#x2F;&#x2F;readthedocs.org&#x2F;<span>search</span>&#x2F"
                     ]
                  }
               },
               {
                  "type": "domain",
                  "role": "http:get",
                  "name": "/_/api/v2/search/",
                  "id": "get--_-api-v2-search-",
                  "content": "Retrieve search results for docs",
                  "highlights": {
                     "name": [""],
                     "content": ["Retrieve <span>search</span> results for docs"]
                  }
               }
            ]
        },
    ]
}

Migrating from API v2

Instead of using query arguments to specify the project and version to search, you need to do it from the query itself, this is if you had the following parameters:

project: docs
version: latest
q: test

Now you need to use:

q: project:docs/latest test

The response of the API is very similar to V2, with the following changes:

project is an object, not a string.
version is an object, not a string.
project_alias isn’t present, it is contained in the project object.

When searching on a parent project, results from their subprojects won’t be included automatically, to include results from subprojects use the subprojects parameter.

Authentication and authorization

If you are using private versions, users will only be allowed to search projects they have permissions over. Authentication and authorization is done using the current session, or any of the valid sharing methods.

See also

API v3: You can create and revoke sharing methods programmatically from /api/v3/projects/<project_slug>/sharing/.

To be able to use the user’s current session you need to use the API from the domain where your docs are being served (<you-docs-domain>/_/api/v3/search/). This is https://docs.readthedocs-hosted.com/_/api/v3/search/ for the https://docs.readthedocs-hosted.com/ project, for example.

API v2 (deprecated)

Note

Please use our API v3 instead, see Migrating from API v2.

GET /api/v2/search/

Return a list of search results for a project, including results from its Subprojects. Results are divided into sections with highlights of the matching term.

Query Parameters:

q – Search query
project – Project slug
version – Version slug
page – Jump to a specific page
page_size – Limits the results per page, default is 50

Response JSON Object:

type (string) – The type of the result, currently page is the only type.
project (string) – The project slug
project_alias (string) – Alias of the project if it’s a subproject.
version (string) – The version slug
title (string) – The title of the page
domain (string) – Canonical domain of the resulting page
path (string) – Path to the resulting page
highlights (object) – An object containing a list of substrings with matching terms. Note that the text is HTML escaped with the matching terms inside a <span> tag.
blocks (object) –
A list of block objects containing search results from the page. Currently, there is one type of block:
- section: A page section with a linkable anchor (id attribute).

Warning

Except for highlights, any other content is not HTML escaped, you shouldn’t include it in your page without escaping it first.

Example request:

$ curl "https://app.readthedocs.org/api/v2/search/?project=docs&version=latest&q=server%20side%20search"

import requests
URL = 'https://app.readthedocs.org/api/v2/search/'
params = {
   'q': 'server side search',
   'project': 'docs',
   'version': 'latest',
}
response = requests.get(URL, params=params)
print(response.json())

Example response:

{
    "count": 41,
    "next": "https://app.readthedocs.org/api/v2/search/?page=2&project=read-the-docs&q=server+side+search&version=latest",
    "previous": null,
    "results": [
        {
            "type": "page",
            "project": "docs",
            "project_alias": null,
            "version": "latest",
            "title": "Server Side Search",
            "domain": "https://docs.readthedocs.io",
            "path": "/en/latest/server-side-search.html",
            "highlights": {
                "title": [
                    "<span>Server</span> <span>Side</span> <span>Search</span>"
                ]
            },
            "blocks": [
               {
                  "type": "section",
                  "id": "server-side-search",
                  "title": "Server Side Search",
                  "content": "Read the Docs provides full-text search across all of the pages of all projects, this is powered by Elasticsearch.",
                  "highlights": {
                     "title": [
                        "<span>Server</span> <span>Side</span> <span>Search</span>"
                     ],
                     "content": [
                        "You can <span>search</span> all projects at https:&#x2F;&#x2F;readthedocs.org&#x2F;<span>search</span>&#x2F"
                     ]
                  }
               }
            ]
        },
    ]
}

Cross-site requests

Cross site requests are allowed for the following endpoints:

/api/v2/footer_html/
/api/v2/search/
/api/v2/embed/
/api/v2/sustainability/
/api/v3/embed/

Except for the sustainability API, all of the above endpoints don’t allow you to pass credentials in cross-site requests. In other words, these API endpoints allow you to access public information only.

On a technical level, this is achieved by implementing the CORS standard, which is supported by all major browsers. We implement it such way that it strictly match the intention of the API endpoint.

Cookies

On Read the Docs Community, our session cookies have the SameSite attribute set to Lax, This means that browsers will not include them in cross site requests. All resources in Read the Docs Community are public, you don’t need to pass cookies to make use of our allowed APIs from other sites.

On Read the Docs for Business, our session cookies have the SameSite attribute set to Lax, this means that browsers will not include them in cross site requests. If you need to have access to versions that the current user has permissions over, you can make use of our proxied APIs, they can be accessed from docs domains with the /_/ prefix. For example, you can make use of our search API from <your-docs-domain>/_/api/v2/search/.

Frequently asked questions

Building and publishing your project 

Why does my project have status “failing”?

Projects have the status “failing” because something in the build process has failed. This can be because the project is not correctly configured, because the contents of the Git repository cannot be built, or in the most rare cases because a system that Read the Docs connects to is not working.

First, you should check out the Builds tab of your project. By clicking on the failing step, you will be able to see details that can lead to resolutions to your build error.

If the solution is not self-evident, you can use an important word or message from the error to search for a solution.

See also

Troubleshooting build errors

Common errors and solutions for build failures.

Other FAQ entries

How do I add additional software dependencies for my documentation?
Why do I get import errors from libraries depending on C modules?

Why do I get import errors from libraries depending on C modules?

Note

Another use case for this is when you have a module with a C extension.

This happens because the build system does not have the dependencies for building your project, such as C libraries needed by some Python packages (e.g. libevent or mysql). For libraries that cannot be installed via apt in the builder there is another way to successfully build the documentation despite missing dependencies.

With Sphinx you can use the built-in autodoc_mock_imports for mocking. If such libraries are installed via setup.py, you also will need to remove all the C-dependent libraries from your install_requires in the Read the Docs environment.

Where do I need to put my docs for Read the Docs to find it?

You can put your docs wherever your want on your repository. However, you will need to tell Read the Docs where your Sphinx’s (i.e. conf.py) or MkDocs’ (i.e. mkdocs.yml) configuration file lives in order to build your documentation.

This is done by using sphinx.configuration or mkdocs.configuration config key in your Read the Docs configuration file. Read Configuration file overview to know more about this.

How can I avoid search results having a deprecated version of my docs?

If readers search something related to your docs in Google, it will probably return the most relevant version of your documentation. It may happen that this version is already deprecated and you want to stop Google indexing it as a result, and start suggesting the latest (or newer) one.

To accomplish this, you can add a robots.txt file to your documentation’s root so it ends up served at the root URL of your project (for example, https://yourproject.readthedocs.io/robots.txt). We have documented how to set this up in robots.txt support.

How do I change the version slug of my project?

You can change the slug of your versions from the versions tab of your project, see Version URL identifier (slug) for more information.

What commit of Read the Docs is in production?

We deploy readthedocs.org from the rel branch in our GitHub repository. You can see the latest commits that have been deployed by looking on GitHub: https://github.com/readthedocs/readthedocs.org/commits/rel

We also keep an up-to-date changelog.

Additional features and configuration 

How do I add additional software dependencies for my documentation?

For most Python dependencies, you can specify a requirements file which details your dependencies. You can also set your project documentation to install your Python project itself as a dependency.

See also

Build process overview

An overview of the build process.

How to create reproducible builds

General information about adding dependencies and best-practices for maintaining them.

Build process customization

How to customize your builds, for example if you need to build with different tools from Sphinx or if you need to add additional packages for the Ubuntu-based builder.

Configuration file reference

Reference for the main configuration file, readthedocs.yaml

build.apt_packages

Reference for adding Debian packages with apt for the Ubuntu-based builders

Other FAQ entries

How do I add additional software dependencies for my documentation?
Why do I get import errors from libraries depending on C modules?

How do I change behavior when building with Read the Docs?

When Read the Docs builds your project, it sets the READTHEDOCS environment variable to the string 'True'. So within your Sphinx conf.py file, you can vary the behavior based on this. For example:

import os

on_rtd = os.environ.get("READTHEDOCS") == "True"
if on_rtd:
    html_theme = "default"
else:
    html_theme = "nature"

The READTHEDOCS variable is also available in the Sphinx build environment, and will be set to True when building on Read the Docs:

{% if READTHEDOCS %}
Woo
{% endif %}

I want comments in my docs 

Read the Docs doesn’t have explicit support for this. That said, a tool like Disqus (and the sphinxcontrib-disqus plugin) can be used for this purpose on Read the Docs.

Can I remove advertising from my documentation?

Yes. See Opting out of advertising.

How do I change my project slug (the URL your docs are served at)?

We don’t support allowing folks to change the slug for their project. You can update the name which is shown on the site, but not the actual URL that documentation is served.

The main reason for this is that all existing URLs to the content will break. You can delete and re-create the project with the proper name to get a new slug, but you really shouldn’t do this if you have existing inbound links, as it breaks the internet.

Instead, you can consider migrating your documentation to another domain with Redirects.

If that isn’t enough, you can request the change sending an email to support@readthedocs.org.

Big projects 

How do I host multiple projects on one custom domain?

We support the concept of subprojects, which allows multiple projects to share a single domain. If you add a subproject to a project, that documentation will be served under the parent project’s subdomain or custom domain.

For example, Kombu is a subproject of Celery, so you can access it on the celery.readthedocs.io domain:

https://celery.readthedocs.io/projects/kombu/en/latest/

This also works the same for custom domains:

http://docs.celeryq.dev/projects/kombu/en/latest/

You can add subprojects in the project admin dashboard.

For details on custom domains, see our documentation on Custom domains.

How do I support multiple languages of documentation?

Read the Docs supports multiple languages. See the section on Localization and Internationalization.

Sphinx 

I want to use the Read the Docs theme 

To use the Read the Docs theme, you have to specify that in your Sphinx’s conf.py file.

Read the sphinx-rtd-theme documentation for instructions to enable it in your Sphinx project.

Image scaling doesn’t work in my documentation 

Image scaling in docutils depends on Pillow. If you notice that image scaling is not working properly on your Sphinx project, you may need to add Pillow to your requirements to fix this issue. Read more about How to create reproducible builds to define your dependencies in a requirements.txt file.

Python 

Can I document a Python package that is not at the root of my repository?

Yes. The most convenient way to access a Python package for example via Sphinx’s autoapi in your documentation is to use the python.install.method: pip (python.install) configuration key.

This configuration will tell Read the Docs to install your package in the virtual environment used to build your documentation so your documentation tool can access to it.

Does Read the Docs work well with “legible” docstrings?

Yes. One criticism of Sphinx is that its annotated docstrings are too dense and difficult for humans to read. In response, many projects have adopted customized docstring styles that are simultaneously informative and legible. The NumPy and Google styles are two popular docstring formats. Fortunately, the default Read the Docs theme handles both formats just fine, provided your conf.py specifies an appropriate Sphinx extension that knows how to convert your customized docstrings. Two such extensions are numpydoc and napoleon. Only napoleon is able to handle both docstring formats. Its default output more closely matches the format of standard Sphinx annotations, and as a result, it tends to look a bit better with the default theme.

Note

To use these extensions you need to specify the dependencies on your project by following this guide.

I need to install a package in a environment with pinned versions 

If you’d like to pin your dependencies outside the package, you can add this line to your requirements or environment file (if you are using Conda).

In your requirements.txt file:

# path to the directory containing setup.py relative to the project root
-e .

In your Conda environment file (environment.yml):

# path to the directory containing setup.py relative to the environment file
-e ..

Changelog

Note

Starting on June 30, 2025, the changelog is published as a GitHub release and listed in the repository itself.

Version 14.0.0

Date:: June 24, 2025

Trying out the GitHub auto-generated Changelog.

New dashboard: delete legacy HTML templates (part 4) by @humitos in https://github.com/readthedocs/readthedocs.org/pull/12201
feat(viz-diff-doc): update viz diff doc by @joleecl in https://github.com/readthedocs/readthedocs.org/pull/12185
Clarification on PR build webhooks and GitHub Action by @k4kfh in https://github.com/readthedocs/readthedocs.org/pull/11998
Build: show the command that’s currently being executed by @stsewd in https://github.com/readthedocs/readthedocs.org/pull/12243
Update doc URLs from readthedocs.org/com to app.readthedocs.org/com by @agjohnson in https://github.com/readthedocs/readthedocs.org/pull/12251
Add pixi example by @pavelzw in https://github.com/readthedocs/readthedocs.org/pull/12155
Normalize usage of “single sign-on” by @agjohnson in https://github.com/readthedocs/readthedocs.org/pull/12256
Add vale and fix issues detected by @ericholscher in https://github.com/readthedocs/readthedocs.org/pull/12257
Update import private repository UI shots and directions by @agjohnson in https://github.com/readthedocs/readthedocs.org/pull/12255
GitHub App: open beta by @stsewd in https://github.com/readthedocs/readthedocs.org/pull/12217
Dependencies: all packages updated via pip-tools by @github-actions in https://github.com/readthedocs/readthedocs.org/pull/12263
Add TheEconomist and proselist rules from WTD by @ericholscher in https://github.com/readthedocs/readthedocs.org/pull/12258
Update UI screenshots and directions on outgoing webhooks by @agjohnson in https://github.com/readthedocs/readthedocs.org/pull/12261
Update subproject guide screenshots and directions by @agjohnson in https://github.com/readthedocs/readthedocs.org/pull/12262
Try some more vale fixes by @agjohnson in https://github.com/readthedocs/readthedocs.org/pull/12260
Use Allauth settings for app name and hiding on login/connect forms by @agjohnson in https://github.com/readthedocs/readthedocs.org/pull/12242
doc: Document build.commands working directory by @LecrisUT in https://github.com/readthedocs/readthedocs.org/pull/11218
Fix bumpver because we removed package.json by @ericholscher in https://github.com/readthedocs/readthedocs.org/pull/12266
Release 14.0.0 by @ericholscher in https://github.com/readthedocs/readthedocs.org/pull/12267

New Contributors

@joleecl made their first contribution in https://github.com/readthedocs/readthedocs.org/pull/12185
@k4kfh made their first contribution in https://github.com/readthedocs/readthedocs.org/pull/11998
@pavelzw made their first contribution in https://github.com/readthedocs/readthedocs.org/pull/12155
@LecrisUT made their first contribution in https://github.com/readthedocs/readthedocs.org/pull/11218

Full Changelog: https://github.com/readthedocs/readthedocs.org/compare/13.5.0…14.0.0

Version 13.5.0

Date:: June 17, 2025

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12250)
@humitos: Delete /projects/<slug>/downloads/ URL (#12247)
@humitos: Delete old URLs (#12246)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12240)
@stsewd: Redirect: fix infinite redirect in 404 view (#12237)
@stsewd: GitLab: Use full path for GitLab groups/organizations (#12236)
@stsewd: OAuth: return an iterator for pagination (#12235)
@stsewd: GitLab: handle when a repository is moved to another group (#12233)
@ericholscher: Release 13.4.0 (#12229)
@humitos: Publish canceled subscriptions into #rtd-notifications channel (#12228)
@stsewd: GitHub App: handle webhook events in task (#12223)
@humitos: New dashboard: delete legacy HTML templates (part 3) (#12200)

Version 13.4.0

Date:: June 03, 2025

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12226)
@agjohnson: Add Project queryset prefetch_latest_build() to project filter (#12225)
@stsewd: Subscriptions: fix canceling subscription (#12224)
@henryiii: fix(schema): require tools or commands (#12222)
@humitos: Upload staticfiles to S3 (#12220)
@ericholscher: Fix sitemap by moving comment. (#12216)
@humitos: Gold: subscription is the subscription id as string (#12212)
@humitos: Release 13.3.0 (#12209)
@humitos: Tests: call super().setUp() (#12208)
@humitos: New dashboard: delete legacy HTML templates (part 2) (#12197)
@stsewd: GitHub App: faster migration page (#12186)

Version 13.3.0

Date:: May 27, 2025

@humitos: Tests: call super().setUp() (#12208)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12204)
@humitos: Remove allauth warning (#12198)
@stsewd: Docs: update AWS temporary credentials documentation (#12196)
@agjohnson: Release 13.2.0 (#12195)
@barseghyanartur: Add info on generating docs in txt format (#12194)
@stsewd: Project: add is_github_app_project helper method (#12193)
@pjfan: Delete how to change url versioning page (#12192)
@humitos: New dashboard: delete legacy HTML templates (part 1) (#12183)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12176)
@stsewd: GitHub App: block GH app users to re-connect to old OAuth app (#12175)
@humitos: Djstripe cleanup (#12160)
@coroa: More concise uv example with docs (#12064)

Version 13.2.0

Date:: May 20, 2025

@barseghyanartur: Add info on generating docs in txt format (#12194)
@stsewd: Project: add is_github_app_project helper method (#12193)
@pjfan: Delete how to change url versioning page (#12192)
@pavithraes: Add note about contributing to other RTD projects (#12191)
@pavithraes: Update dev site build step (#12190)
@sirosen: Add an example of pip install --group (#12189)
@pavithraes: Remove mention of Gitter from contributor docs (#12188)
@pjfan: Link previews docs update (#12187)
@pavithraes: Update faq about changing project slugs (#12184)
@humitos: Development: always use webpack on development (#12182)
@verisimilidude2: Update ‘built in’ info (#12180)
@MilaZhou22: Add doc tools to frontpage (#12179)
@stsewd: GitHub App: block GH app users to re-connect to old OAuth app (#12175)
@stsewd: Downgrade redis (#12173)
@agjohnson: Downgrade Redis back to 5.2.1 (#12172)
@agjohnson: Release 13.1.1 (#12170)
@ericholscher: Document ability to set public on EnvironmentVariable API v3 (#12169)
@stsewd: Build: escape all whitespaces (#12152)
@humitos: Build: update build tools (#12143)
@stsewd: Build: support cloning private repos with token (#12115)
@stsewd: Build: use scoped credentials for interacting with S3 (#12078)
@coroa: More concise uv example with docs (#12064)

Version 13.1.1

Date:: May 13, 2025

@ericholscher: Document ability to set public on EnvironmentVariable API v3 (#12169)
@humitos: Downgrade lxml to avoid mismatch versions (#12167)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12166)
@ericholscher: Add comment to Sitemap explaining how to customize it (#12164)
@humitos: Redirect for / and /welcome URLs (#12163)
@humitos: Do not run djstripe checks on builders (#12159)
@humitos: Release 13.1.0 (#12157)
@humitos: Update djstripe handlers (webhook.handler was deleted) (#12156)
@stsewd: Domains: don’t check for limit on existing domains (#12154)
@stsewd: Build: escape all whitespaces (#12152)
@humitos: Upgrade Django to 5.2 (#12149)
@humitos: Upgrade djstripe (#12148)
@humitos: Condiontally homepage redirect based on domain and logged in status (#12147)
@humitos: Build: update build tools (#12143)

Version 13.1.0

Date:: May 06, 2025

@humitos: Update djstripe handlers (webhook.handler was deleted) (#12156)
@stsewd: Domains: don’t check for limit on existing domains (#12154)
@humitos: Upgrade djstripe (#12148)
@humitos: Condiontally homepage redirect based on domain and logged in status (#12147)
@stsewd: Search: truncate contents before indexing (#12146)
@humitos: Downgrade to Django 4.2.x due to djstripe (#12145)
@humitos: Docs: handle versions when “instant loading” feature enabled (#12142)
@humitos: Release 13.0.0 (#12141)
@stsewd: Add migration page for GitHub App (#12112)
@humitos: New dashboard: remove legacy dashboard (#12091)

Version 13.0.0

Date:: April 29, 2025

@stsewd: Revert “Dependencies: all packages updated via pip-tools” (#12136)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12135)
@stsewd: Fix tests on .com (#12131)
@stsewd: GitHub App: fix PR builds and import (#12126)
@humitos: Release 12.0.5 (#12125)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12123)
@stsewd: Versions: always keep latest in sync with default branch/tag (#12121)
@stsewd: Add migration page for GitHub App (#12112)
@humitos: Upgrade to Django 5.x (#12104)
@humitos: New dashboard: remove legacy dashboard (#12091)

Version 12.0.5

Date:: April 22, 2025

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12123)
@stsewd: Versions: always keep latest in sync with default branch/tag (#12121)
@stsewd: Update log (#12120)
@stsewd: Remove dead code (#12118)
@stsewd: GitHub: show repos from old or new GH integration only (#12113)
@stsewd: Add migration page for GitHub App (#12112)
@stsewd: Update common (#12111)
@agjohnson: Release 12.0.4 (#12110)
@stsewd: Add GitHub App service (#12072)

Version 12.0.4

Date:: April 15, 2025

@TheMathix: Update README.rst (#12107)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12103)
@stsewd: VCS: pass a version object to git provider (#12101)
@stsewd: Version: document how to change the version slug and expose it to everyone (#12096)
@stsewd: Don’t set secret key on builders (#12095)
@humitos: Requirements: pin newrelic (#12092)
@humitos: Release 12.0.3 (#12089)

Version 12.0.3

Date:: April 08, 2025

@stsewd: Remove cacheops (#12087)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12083)
@stsewd: Storage: remove build environment storage (#12077)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12075)
@stsewd: Docs: mention fine-grained personal access token for GitHub (#12074)
@stsewd: Revert “Requirements: use xmlsec with --no-binary option” (#12071)
@stsewd: Add models for GitHub App (#12070)
@ericholscher: Release 12.0.2 (#12068)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12065)
@stsewd: Remove dead code (#12060)
@humitos: Requirements: use xmlsec with --no-binary option (#12056)
@stsewd: Webhooks: refactor branch/tag building (#12014)

Version 12.0.2

Date:: March 25, 2025

@stsewd: API v3: document rate limit and pagination (#12063)
@stsewd: Social accounts: sync remote repositories when a new connection is added (#12062)
@stsewd: Small improvements on PR previews handling (#12061)
@stsewd: Allauth: update deprecated settings (#12058)
@humitos: pip tools: use Python 3.12 (#12055)
@humitos: Requirements: pin and downgrade xmlsec (#12054)
@humitos: Release 12.0.1 (#12053)
@stsewd: Subscriptions: improve subscription detection and respect never_disable (#12046)
@stsewd: Remote repositories: filter by vcs provider when deleting (#12015)

Version 12.0.1

Date:: March 18, 2025

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12048)
@stsewd: Remote repository: don’t stop at first error while syncing (#12045)
@ericholscher: Add ignore revs for the major linting commits (#12043)
@stsewd: Explicitly define virtual environment used in Docker (#12040)
@davidfischer: Use Ruff for linting (#12037)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12034)
@agjohnson: Update URLs for SAML to point to new dashboard (#12031)
@ericholscher: update pr links (#12028)
@humitos: Release 12.0.0 (#12023)
@stsewd: Add GitHub App OAuth provider (#12020)
@ericholscher: Fix mkdocs link (#12019)
@stsewd: SAML: add flag to allow SAML with old dashboard (#12013)
@stsewd: Projects: require users to have admin permissions to link repositories to projects (#12005)

Version 12.0.0

Date:: February 25, 2025

@ericholscher: Fix mkdocs link (#12019)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#12017)
@stsewd: Git service: add method to sync user access to remote repositories (#12016)
@stsewd: SAML: add flag to allow SAML with old dashboard (#12013)
@humitos: File Tree Diff: small documentation to mention the file selector (#12011)
@humitos: File Tree Diff: enabled by default (#12010)
@stsewd: Project: don’t depend on the brand name (#12008)
@stsewd: Service: kwargs only when sending build statuses (#12007)
@stsewd: CSP: add helper middleware (#12004)
@ericholscher: Increase docker memory limit (#12003)
@humitos: Upgrade to Ubuntu 24.04 for our application (#12002)
@humitos: Release 11.21.1 (#12001)
@stsewd: Git service: attach each service to an allauth provider (#11995)
@ericholscher: Hosting: Don’t check for superprojects on subprojects (#11683)
@ericholscher: Remove indexes that aren’t used and that are large (#11623)

Version 11.21.1

Date:: February 18, 2025

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11999)
@stsewd: Import: fix session (#11997)
@stsewd: Git service: attach each service to an allauth provider (#11995)
@humitos: Requirements: unpin requests and docker (#11992)
@humitos: Settings: avoid having app.app.readthedocs.org (#11991)
@humitos: Release 11.21.0 (#11989)
@humitos: File Tree Diff: normalize ignore files (#11987)
@stsewd: Git service: depend on the project instead of users (#11983)

Version 11.21.0

Date:: February 11, 2025

@humitos: File Tree Diff: normalize ignore files (#11987)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11985)
@ericholscher: Add a doc for how to integrate search without other customization (#11984)
@humitos: Update common to its latest version (#11982)
@ericholscher: Revert “Show slug on AddonsConfigAdmin (#11974)” (#11981)
@humitos: Run spam check after a sucessful build (#11980)
@humitos: File Tree Diff: allow users to ignore files (#11977)
@humitos: Build: don’t trigger build if the project is spam (#11976)
@ericholscher: Show slug on AddonsConfigAdmin (#11974)
@ericholscher: Be defensive with build_complete signal (#11973)
@ericholscher: Release 11.20.0 (#11972)
@ericholscher: Add a warning about VCS SSO to import guide (#11966)
@ericholscher: Always run sync_versions on the default queue (#11965)
@ericholscher: Copy updates for intro pages (#11948)
@stsewd: Allow users to change version slug (#11930)

Version 11.20.0

Date:: February 04, 2025

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11968)
@ericholscher: Add a warning about VCS SSO to import guide (#11966)
@ericholscher: Always run sync_versions on the default queue (#11965)
@stsewd: Fix migration (#11964)
@humitos: Addons API: return FTD enabled/disabled based on addons config (#11963)
@humitos: Admin: allow blank field from admin (#11962)
@humitos: Release 11.19.2 (#11959)
@stsewd: Version: use field validator instead of custom field for slug (#11957)
@humitos: Docs: explains flyout position (#11954)
@ericholscher: Copy updates for intro pages (#11948)
@stsewd: Remove embed API v2 code (#11945)
@humitos: Addons: expose readthedocs.resolver.filename in the API response (#11940)
@stsewd: Allow users to change version slug (#11930)
@stsewd: ImportedFile: use BigAutoField for primary key (#9669)

Version 11.19.2

Date:: January 28, 2025

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11953)
@ericholscher: Add Antora docs page (#11947)
@ericholscher: Add vitepress doc page (#11944)
@ericholscher: Note that there’s a soft disk limit for doc builds (#11943)
@stsewd: Version sync: restore verbose_name for stable version (#11941)
@humitos: Addons: expose readthedocs.resolver.filename in the API response (#11940)
@ericholscher: Release 11.19.1 (#11938)
@stsewd: Docs: update build customization docs (#11927)
@ericholscher: Run FileTreeDiff indexer on all versions in dev (#11873)
@stsewd: Project: use clone URL from connected repository if available (#11826)

Version 11.19.1

Date:: January 21, 2025

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11934)
@stsewd: Docs: fix markdoc example (#11932)
@stsewd: Docs: update markdoc example to use build.jobs (#11929)
@humitos: Release 11.19.0 (#11926)
@stsewd: Document new build jobs (#11900)
@humitos: Addons: allow to set a “Default” or a explicit position for flyout (#11891)
@stsewd: Project: use clone URL from connected repository if available (#11826)
@stsewd: API: use restricted serializer for related projects (#11820)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11771)

Version 11.19.0

Date:: January 14, 2025

@stsewd: Don’t require sphinx/mkdocs keys when using build.commands (#11913)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11909)
@stsewd: Document new build jobs (#11900)
@humitos: Docs: remove CSS variables override for font-size (#11897)
@stsewd: Add django-impersonate when admin is enabled (#11894)
@stsewd: Environment variables: document special case for PR preview builds (#11893)
@stsewd: Social accounts: link Bitbucket to new dashboard (#11892)
@humitos: Addons: allow to set a “Default” or a explicit position for flyout (#11891)
@ericholscher: Add Addons customization docs (#11888)
@stsewd: Don’t reflect user input in raw response (#11887)
@ericholscher: Lower logging for user build errors (#11886)
@ericholscher: Release 11.18.0 (#11884)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11881)
@stsewd: Build: use actual git identifier for READTHEDOCS_GIT_IDENTIFIER (#11875)
@ericholscher: Update MkDocs page to be generic and note MkDocs for Material integration (#11871)
@stsewd: Config: inherit all pydantic models from a common base class (#11857)
@stsewd: API: use restricted serializer for related projects (#11820)
@stsewd: API: separate querysets from API V2 and V3 (#11586)
@stsewd: Email: use first recipient from email object (#11581)
@humitos: Cleanup: delete yaml_load_safely (#11285)

Version 11.18.0

Date:: January 07, 2025

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11881)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11877)
@stsewd: Build: use actual git identifier for READTHEDOCS_GIT_IDENTIFIER (#11875)
@stsewd: Fix ext-theme tests (#11872)
@humitos: Skip running default commands when GENRIC doctool (#11863)
@humitos: Release 11.17.1 (#11862)
@agjohnson: Match User method in TeamMember (#11861)
@humitos: Docs: use “Visual diff” for marketing “Doc Diff” (#11860)
@stsewd: Config: inherit all pydantic models from a common base class (#11857)
@stsewd: Remove dead code from old footer (#11854)
@stsewd: Config file: make sphinx or mkdocs configuration required for projects using Sphinx or MkDocs (#11852)
@ericholscher: Add mdbook docs page (#11849)
@stsewd: Build: remove conda_append_core_requirements feature flag (#11847)
@stsewd: Remove disable_sphinx_manipulation feature flag (#11841)
@stsewd: Version: better support for manual created latest and stable versions (#11823)

Version 11.17.1

Date:: December 17, 2024

@agjohnson: Match User method in TeamMember (#11861)
@humitos: Docs: use “Visual diff” for marketing “Doc Diff” (#11860)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11858)
@stsewd: Remove yamale (#11855)
@stsewd: Remove dead code from old footer (#11854)
@ericholscher: docs: Reframe Supported Tools (#11853)
@ericholscher: Add mdbook docs page (#11849)
@ericholscher: Add Rust reshim (#11848)
@stsewd: Build: remove usage of addons field (#11846)
@humitos: Remove EthicalAd URLs (#11843)
@stsewd: Fix import wizard (#11842)
@stsewd: Remove disable_sphinx_manipulation feature flag (#11841)
@humitos: Use “Visual diff” instead of doc diff (#11838)
@ericholscher: Release 11.17.0 (#11837)
@humitos: Remove old footer code (#11836)
@ericholscher: Add authentication documentation (#11834)
@ericholscher: Cleanup doctool toctree listing (#11833)

Version 11.17.0

Date:: December 10, 2024

@stsewd: API v2: disallow empty strings as filters (#11832)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11830)
@humitos: Docs: minimal docs for links preview addons (#11828)
@agjohnson: Fix bug with notification HTML (#11827)
@ericholscher: Fix AddonsConfig admin base_version. (#11825)
@stsewd: Domains: check for urlparse errors (#11824)
@humitos: Requirements: update django-formtools (#11822)
@stsewd: Tests: mock dns queries to avoid flaky tests (#11821)
@humitos: Release 11.16.0 (#11817)
@humitos: Development: use uv to install everything (#11815)
@humitos: EmbedAPI: main content based on documentation tool (#11812)
@humitos: EmbedAPI: support “pretty URLs” (#11811)
@agjohnson: Add email for business projects and new dashboard change (#11809)
@stsewd: Dependencies: update django-simple-history (#11808)
@stsewd: Config file: use pydantic for all config models (#11798)
@stsewd: Build: better error message when rclone fails (#11796)
@humitos: Add project: use an instance variable to avoid 500 (#11795)

Version 11.16.0

Date:: December 03, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11813)
@agjohnson: Add email for business projects and new dashboard change (#11809)
@humitos: Development: try uv on Docker images (#11807)
@agjohnson: Fix Sphinx tutorial seealso links (#11806)
@stsewd: Requirements: install unicode-slugify from pypi (#11805)
@humitos: Django Debug Toolbar: disable slow panels (#11804)
@ericholscher: Upgrade NR to fix issue (#11802)
@humitos: Release 11.15.0 (#11800)
@humitos: Addons: create AddonsConfig on Project.post_save (#11799)
@stsewd: Allauth: disable account enumeration protection (#11797)
@humitos: Addons: base version to compare against (DocDiff and File Tree Diff) (#11794)
@humitos: File tree diff: migrate feature flag to model field (#11793)
@plaindocs: Docusaurus basics (#11752)

Version 11.15.0

Date:: November 26, 2024

@stsewd: Allauth: disable account enumeration protection (#11797)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11792)
@ericholscher: Support RTD_USE_PROMOS for setting USE_PROMOS in dev (#11790)
@ericholscher: Increase default docker limits (#11788)
@stsewd: Set brownouts for deprecated embed API v2 (#11786)
@humitos: Use addons JavaScript file from Docker container (#11785)
@ericholscher: Add Markdoc to the doc tools (#11782)
@humitos: Migrations: re-order them for deploy (#11779)
@humitos: Release 11.14.0 (#11778)
@stsewd: Docs: update connected accounts steps to use env vars (#11777)
@humitos: Addons: make default root CSS selector a shared option (#11767)
@humitos: Addons: load_when_embedded config (#11765)
@stsewd: Custom domain: check CNAME when adding domains (#11747)
@stsewd: Docs: update custom domains docs (#11734)
@stsewd: Build: allow partial override of build steps (#11710)
@humitos: Dependencies: use GitHub Action + pip-tools (#9479)
@humitos: GitHub Action: add link to Pull Request preview (#9450)

Version 11.14.0

Date:: November 19, 2024

@stsewd: Docs: update connected accounts steps to use env vars (#11777)
@stsewd: Fix ext-theme test (#11776)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11771)
@humitos: Addons: load_when_embedded config (#11765)
@humitos: Addons: rename fields on API response (#11764)
@humitos: Docs: disable sphinx-hoverxref in our docs (#11762)
@ericholscher: Update migration to not conflict (#11761)
@ericholscher: Release 11.13.0 (#11760)
@humitos: Adddons: allow injecting an “always live” JavaScript file (#11758)
@humitos: Pin pip for pip-tools for now (#11756)
@humitos: Addons: resolve URLs for file tree diff API response (#11749)
@humitos: Addons: API response for tooltips (#11746)
@laymonage: Build tools: update latest versions (#11742)
@humitos: Addons: remove old X-RTD-Hosting-Integrations HTTP header (#11653)
@humitos: Build: remove “addons enabled by default” notification (#11651)
@agjohnson: Fix site-wide new dashboard notification (#11543)

Version 11.13.0

Date:: November 12, 2024

@humitos: Pin pip for pip-tools for now (#11756)
@plaindocs: Clarify flyout options (#11750)
@humitos: Addons: resolve URLs for file tree diff API response (#11749)
@stsewd: Env variables: increase size limit (#11748)
@humitos: Addons: API response for tooltips (#11746)
@stsewd: API v3: don’t inherit from flex fields when no needed (#11745)
@humitos: Addons: split model and data migrations (#11744)
@humitos: Release 11.12.0 (#11743)
@stsewd: Update allauth (#11719)
@humitos: Addons: allow users to show/hide notifications on latest/non-stable (#11718)
@ericholscher: Admin: Make large inlines collapse by default (#11717)
@humitos: Addons: remove old X-RTD-Hosting-Integrations HTTP header (#11653)
@stsewd: Notifications: remove unused notification (#11573)
@agjohnson: Fix site-wide new dashboard notification (#11543)
@humitos: Build: use new Docker images from design document (#8453)
@humitos: Embed APIv3: initial implementation (#8319)

Version 11.12.0

Date:: November 05, 2024

@cclauss: Do not automatically create pip-tools pull requests on forks of this repo (#11738)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11737)
@agjohnson: Update common (#11736)
@stsewd: API V3: use a restricted serializer for when showing org info from a project (#11732)
@stsewd: API v3: always return projects when listing remote repositories (#11731)
@stsewd: API v3: remove last_build expandable field (#11730)
@humitos: Addons: return all active versions on single version project (#11727)
@stsewd: Tests: fix slow test (#11725)
@ericholscher: Fix docs warnings and broken links (#11723)
@stsewd: Remove unused middlewares (#11722)
@stsewd: Set session cookie SameSite attribute to Lax for main site (#11721)
@humitos: Addons: allow users to show/hide notifications on latest/non-stable (#11718)
@ericholscher: Admin: Make large inlines collapse by default (#11717)
@stsewd: Docs: document 2fa (#11716)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11714)
@laymonage: Clarify support for an optional v-prefix in branch and tag names (#11712)
@stsewd: Docs: update sphinx (#11711)
@stsewd: File indexers: correctly get page content from PR previews (#11709)
@ericholscher: Release 11.11.0 (#11708)
@ericholscher: Clean up Addons & Flyout menu docs (#11706)
@ericholscher: Clean up front page copy (#11705)
@stsewd: Docs: update Sphinx instructions to override search (#11702)
@stsewd: Addons: always sort versions in descending order (#11691)
@ericholscher: Fix analytics links (#11661)
@browniebroke: Simplify instructions for installing dependencies with uv (#11655)
@stsewd: Unresolver: allow a full URL when un-resolving a domain (#11632)
@stsewd: Notifications: remove unused notification (#11573)
@plaindocs: Add list of supported tools (#11547)

Version 11.11.0

Date:: October 23, 2024

@stsewd: Remove unrelated change (#11704)
@stsewd: Addons: always sort versions in descending order (#11691)
@stsewd: Addons: default to semver for sorting versions (#11686)
@ericholscher: Release 11.10.0 (#11685)
@ericholscher: Fix second Content Type header (#11684)
@humitos: Docs: recover “Edit on GitHub” links (#11681)
@ericholscher: fix proxito header (#11680)
@agjohnson: Accidentally a word (#11679)
@stsewd: Subscription: better feature description (#11676)
@ericholscher: Enable subproject filters for projects with subprojects (#11674)
@stsewd: Remove session fallback cookie (#11673)
@stsewd: File tree diff (#11646)
@stsewd: Build: refactor search indexing process (#11643)
@plaindocs: Add list of supported tools (#11547)

Version 11.10.0

Date:: October 15, 2024

@humitos: Docs: recover “Edit on GitHub” links (#11681)
@ericholscher: fix proxito header (#11680)
@agjohnson: Accidentally a word (#11679)
@ericholscher: Link to new dashboard Addons page in old dashboard settings. (#11678)
@stsewd: Subscription: better feature description (#11676)
@stsewd: Sitemap: don’t include hidden versions (#11675)
@ericholscher: Enable subproject filters for projects with subprojects (#11674)
@stsewd: Remove session fallback cookie (#11673)
@humitos: Notification: make “pending configuration” dismissable (#11670)
@cclauss: codespell the docs directory (#11664)
@ericholscher: Fix analytics links (#11661)
@humitos: Release 11.9.0 (#11659)
@stsewd: Search: respect spacing from block elements when indexing (#11658)
@humitos: Notification: update copy since it’s a past date (#11657)
@browniebroke: Simplify instructions for installing dependencies with uv (#11655)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11650)
@stsewd: Build: refactor search indexing process (#11643)
@humitos: Addons: disable search filters for now (#11638)
@stsewd: Version file tree diff: design doc (#11507)
@stsewd: Move parser tests from rtd-build repo (#4225)

Version 11.9.0

Date:: October 08, 2024

@humitos: Notification: update copy since it’s a past date (#11657)
@humitos: Proxito: remove X-RTD-Hosting-Integrations HTTP header (#11656)
@humitos: Metrics: don’t rely on Embed APIv2 (#11652)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11650)
@stsewd: ES: fix another flaky test (#11647)
@simonbowly: Specify that hidden versions in RTD are blocked from indexing (#11644)
@ericholscher: Large docs refactor (#11641)
@stsewd: ES: fix flaky test (#11640)
@stsewd: Allauth: add 429 handler (#11639)
@humitos: Addons: disable search filters for now (#11638)
@humitos: Docs: use the latest Sphinx theme (#11637)
@ericholscher: Update Analytics pages in the docs (#11636)
@ericholscher: Update Business docs (#11635)
@ericholscher: Release 11.8.1 (#11634)
@humitos: Build: don’t show listing or detail view if project is spam (#11633)
@humitos: Domains: put a limit of 2 custom domains per project (#11629)
@stsewd: Addons: small improvements and privacy considerations (#11561)
@humitos: Addons: prepare Proxito and dashboard to enable them by default (#11513)

Version 11.8.1

Date:: October 01, 2024

@humitos: Addons: disable the field instead of remove it (#11628)
@humitos: Notifications: unsupported VCS (#11627)
@agjohnson: Only use django-filters filtering on project dashboard (#11622)
@agjohnson: Try reverting prefetch changes for project/version listing views (#11621)
@humitos: Release 11.8.0 (#11619)
@agjohnson: Prefetch build and project on version list (#11616)
@agjohnson: Add support for successful build prefetch (#11613)
@agjohnson: Drop unnecessary CSP directives for gold view (#11605)
@ericholscher: Add exit_code to build errors (#11597)
@duboism: Docs: update reproducible builds guide (#10939)

Version 11.8.0

Date:: September 25, 2024

@agjohnson: Prefetch build and project on version list (#11616)
@ericholscher: Add speed up indexes (#11614)
@agjohnson: Add support for successful build prefetch (#11613)
@ericholscher: Add date version index on build (#11612)
@humitos: Use theme 3.0.0rc2 (version/language selector) (#11611)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11609)
@agjohnson: Make terminology and paths consistent for onboarding announcements (#11608)
@humitos: Add project: check YAML file for specific branch (#11607)
@agjohnson: Drop unnecessary CSP directives for gold view (#11605)
@pllim: Fix minor typo in “Version states” (#11603)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11602)
@dbaston: Docs: Handle long commit messages in [skip ci] example (#11601)
@ericholscher: Add exit_code to build errors (#11597)
@agjohnson: Conditionally disabled custom 404 pages on dev docs (#11596)
@humitos: Release 11.7.2 (#11595)
@humitos: Docs: simplify “Add project” page (#11559)
@humitos: Docs: make translation section more generic (#11549)
@plaindocs: Add list of supported tools (#11547)
@humitos: Addons: prepare Proxito and dashboard to enable them by default (#11513)
@ericholscher: Add success messages for Organization views (#11480)

Version 11.7.2

Date:: September 10, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11590)
@agjohnson: Update common (#11589)
@humitos: Docs: final date for addons and link to blog post (#11588)
@humitos: Docs: small updates to sitemaps page (#11585)
@stsewd: SAML: update docs (#11583)
@stsewd: Email: use first recipient from email object (#11581)
@humitos: Release 11.7.1 (#11580)
@stsewd: Admin: set raw field for SSOIntegration (#11572)
@humitos: Add project: skip config step if YAML file is present (#11540)
@agjohnson: Standardize error template paths (#11494)

Version 11.7.1

Date:: September 03, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11575)
@stsewd: SAML: update Okta setup steps (#11569)
@humitos: Notifications: small typo (#11568)
@humitos: Release 11.7.0 (#11567)
@humitos: Add project: skip config step if YAML file is present (#11540)
@stsewd: Allauth: don’t completely override the send_email method (#11526)

Version 11.7.0

Date:: August 27, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11566)
@kurtmckee: Fix a minor typo (#11565)
@agjohnson: Use clone_url for remote repository field (#11564)
@stsewd: Tasks: delete closed PRs every 30 minutes (#11563)
@stsewd: Settings: define threshold setting for removing projects from ES (#11560)
@humitos: Add project: improve way to get the basics form (#11558)
@stsewd: Search: add function to re-index a project (#11555)
@humitos: Release 11.6.0 (#11554)
@humitos: Docs: make URLs not linkable (#11553)
@stsewd: Update common (#11552)
@humitos: Docs: make translation section more generic (#11549)
@mgeier: Update instructions for Jupyter notebook galleries (#11545)
@stsewd: Allauth: 2FA (#11524)
@ericholscher: Release 10.21.0 (#11185)
@humitos: Build: show the YAML config file before validating it (#11175)
@humitos: Release 10.18.0 (#11096)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11090)
@stsewd: Build: use version slug for get_version_slug (#11085)
@stsewd: Integrations: Don’t allow webhooks without a secret (#11083)
@humitos: Addons: sorting algorithm for versions customizable on flyout (#11069)

Version 11.6.0

Date:: August 20, 2024

@stsewd: Update common (#11552)
@humitos: Docs: make translation section more generic (#11549)
@webknjaz: Fix a typo in “invited” in email notification subjects (#11546)
@mgeier: Update instructions for Jupyter notebook galleries (#11545)
@agjohnson: Drop “Unknown message” notification (#11542)
@stsewd: Login: add link to SAML login (#11541)
@robredpath: Update i18n docs for Sphinx (#11538)
@humitos: Release 11.5.0 (#11537)
@humitos: Slack: use json= to send a message using webhooks (#11536)
@humitos: Addons: add a notification on each Sphinx build (#11514)
@stsewd: Ask for confirmation when adding a user to a project/organization/team (#9440)

Version 11.5.0

Date:: August 13, 2024

@humitos: Docs: simplify repdroducible guide (#11535)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11534)
@humitos: Analytics: remove GA (#11532)
@plaindocs: Post merge fixes (#11530)
@stsewd: Settings: explicitly set password hashers (#11523)
@humitos: Notifications: render the URL for account using Django template tag (#11521)
@stsewd: Remote repository: fix slow query (#11518)
@stsewd: Docs: update API V3 docs about authentication (#11517)
@humitos: Docs: remove “Canonical URLs” guide (#11516)
@humitos: Release 11.4.0 (#11515)
@humitos: Addons: add a notification on each Sphinx build (#11514)
@plaindocs: Explore an alternative way of explaining states (#11512)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11511)
@humitos: Notifications: render the URL using Django url template tag (#11465)
@humitos: APIv3: return permissions expandable field on projects (#10978)

Version 11.4.0

Date:: August 06, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11511)
@humitos: Release 11.3.0 (#11506)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11502)
@stsewd: Project: allow connecting a project to a remote repository after it has been created (#11498)
@stsewd: API V3: change permissions to allow anonymous access to public resources (#11485)
@stsewd: API V3: Don’t allow leaking teams through expandable fields (#11471)
@stsewd: Telemetry: skip listing conda packages on non-conda envs (#9390)

Version 11.3.0

Date:: July 30, 2024

@stsewd: Templates: remove unused filter (#11504)
@stsewd: Social accounts: Add filter to check if a social account can be disconnected (#11503)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11502)
@humitos: Build: do not use custom builder when DISABLE_SPHINX_MANIPULATION (#11499)
@ericholscher: Release 11.2.1 (#11497)
@humitos: Logs: slightly improve on subscription cancelled logs (#11496)
@humitos: Docs: use the latest rc1 release of the theme (#11495)
@humitos: Addons: remove “beta” framing around addons (#11493)
@humitos: Docs: remove beta framing from pull request (#11492)
@humitos: Proxito: remove outdated URL (#11491)
@ericholscher: Add an initial resync_versions API to v3 (#11484)

Version 11.2.1

Date:: July 23, 2024

@humitos: Logs: slightly improve on subscription cancelled logs (#11496)
@humitos: Addons: remove “beta” framing around addons (#11493)
@humitos: Docs: remove beta framing from pull request (#11492)
@humitos: Proxito: remove outdated URL (#11491)
@ericholscher: Update organization help text (#11481)
@humitos: Build: do not install our extension when building with Conda (#11479)
@humitos: Docs: update build limits on community (#11475)
@humitos: Release 11.2.0 (#11473)
@humitos: Pin the theme to a commit (#11472)
@ericholscher: Reorder and cleanup project settings page (#11470)
@humitos: Docs: remove our Sphinx search extension (#11469)
@humitos: Dos: update them based on addons updates (#11468)
@humitos: Docs: kill “Choosing a site” (#11464)
@ericholscher: Refactor admin views to use the SuccessMessageMixin (#11463)

Version 11.2.0

Date:: July 16, 2024

@humitos: Pin the theme to a commit (#11472)
@humitos: Dos: update them based on addons updates (#11468)
@stsewd: CSP: apply extra CSP rules only when ext-theme is enabled (#11466)
@ericholscher: Refactor admin views to use the SuccessMessageMixin (#11463)
@stsewd: Tests: use a faster password hasher (#11462)
@stsewd: Fix slack notifications for stripe events (#11460)
@ericholscher: Remove old flyout image (#11459)
@stsewd: API V3: Filter build notifications by current project (#11458)
@humitos: Docs: remove past sponsors and old blog post link (#11457)
@humitos: Docs: tell users to set the canonical URL manually (#11455)
@ericholscher: Release 11.1.3 (#11454)
@stsewd: API V3: Allow other users to see build notifications from public projects (#11449)
@plaindocs: Add minimal viable docs for addons (#11444)
@humitos: Proxito: remove redirect for README.html files (#11443)
@stsewd: CSP: remove obsolete block-all-mixed-content directive (#11436)
@stsewd: API V3: avoid leaking information through expandable fields (#11381)
@janbrasna: chore: Update guidelines links (#11261)
@nakamura-to: Correcte the tx push command (#11204)
@humitos: Build: rename PDF/ePUB filename to valid one automatically (#11198)

Version 11.1.3

Date:: July 09, 2024

@humitos: Gold: update max_length to accept Stripe price id (#11452)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11451)
@stsewd: CSP: Allow inline scripts in gold subscription view (#11448)
@stsewd: Fix tests on .com (#11447)
@humitos: Release 11.1.2 (#11446)
@plaindocs: Mention linting (#11445)
@plaindocs: Add minimal viable docs for addons (#11444)
@humitos: Build: disable Sphinx manipulation (#11441)
@stsewd: CSP: remove obsolete block-all-mixed-content directive (#11436)
@humitos: Build: remove append_conf _magic_ from MkDocs (#11206)

Version 11.1.2

Date:: July 02, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11442)
@ericholscher: Run iri_to_uri on header values (#11439)
@ericholscher: Release 11.1.1 (#11438)
@humitos: Sales: send a Slack message to be able to contact the customer (#11437)
@humitos: Organization: disable organization on non-active subscription (#11430)
@humitos: Notification: update copy for “No HTML content found” (#11410)
@agjohnson: API: support rebuilding external version builds with build create endpoint (#11407)
@plaindocs: Minor refactor of Private Python packages page (#11395)
@stsewd: Tests: run tests with the ext-theme (#11383)
@ericholscher: Add Pull Request builds page to settings (#10656)

Version 11.1.1

Date:: June 25, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11433)
@humitos: Requirements: upgrade psycopg to v3 (#11432)
@humitos: Proxito: allow serving zh (deprecated) language code (#11429)
@ericholscher: Be more defensive in redirect code (#11427)
@ericholscher: Link website from docs sidebar (#11426)
@stsewd: Use literal None in session cookie samesite setting (#11424)
@humitos: Release 11.1.0 (#11423)
@humitos: Build: add support for Ubuntu 24.04 LTS (#11421)
@humitos: Builds: don’t call git clean anymore (#11420)
@humitos: Ops: delete triggering a time-test build on build-large queue (#11379)

Version 11.1.0

Date:: June 18, 2024

@olgaigig: Update docs.rst (#11422)
@humitos: Build: add support for Ubuntu 24.04 LTS (#11421)
@humitos: Builds: don’t call git clean anymore (#11420)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11415)
@humitos: New dashboard: use app. instead of beta. (#11412)
@humitos: Build: remove “beta” from build.commands (#11411)
@humitos: Docs: update “Example projects” a little (#11404)
@stsewd: Oauth: Fix GitLab access token URL (#11402)
@humitos: Build: update asdf and its plugins so we can build latest versions (#11401)
@humitos: Settings: revert USE_PROMOS setting (#11400)
@ericholscher: Add Unknown for missing VCS class (#11398)
@ericholscher: Release 11.0.0 (#11397)
@rffontenelle: GitHub with uppercase H in onboard_import.html (#11396)
@humitos: Templates: pass ADMIN_URL into context (#11394)
@rffontenelle: Uppercase G for Gold membership in subscription_detail.html (#11388)
@humitos: Build: update all build.tools and add latest versions (#11386)
@humitos: Translations: disable zh code (#11385)
@humitos: VCS: remove code for old VCS support (#11377)

Version 11.0.0

This release removes support for VCS systems other than Git. See more in our blog here: https://about.readthedocs.com/blog/2024/02/drop-support-for-subversion-mercurial-bazaar/

Date:: June 11, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11392)
@rffontenelle: Unbreak strings to proper extraction for translation (#11389)
@stsewd: Update common (#11382)
@stsewd: Update docker compose files (#11380)
@humitos: Release 10.27.0 (#11378)
@humitos: VCS: remove code for old VCS support (#11377)

Version 10.27.0

Date:: June 04, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11376)
@stsewd: Tests: set privacy level to public explicitly (#11375)
@stsewd: Update security policy (#11374)
@Viicos: Fix typo: requiremens to requirements (#11369)
@agjohnson: Add invitation template filter (#11368)
@stsewd: Requirements: unpin allauth (#11366)
@stsewd: Pin requests to a version compatible with docker (#11364)
@humitos: Addons: update projects.translations API response (#11361)
@humitos: Release 10.26.0 (#11360)
@humitos: Django admin: search and filter notifications (#11359)
@agjohnson: Set better success URL for version form views (#11355)
@agjohnson: Fix version visibility filter method (#11354)
@humitos: Proxito: browndate for redirecting / to README.html (#11348)

Version 10.26.0

Date:: May 28, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11357)
@stsewd: Beta: fix dashboard when user doesn’t have projects (#11352)
@humitos: Dashboard: use app. domain instead of beta. (#11349)
@agjohnson: Fix small docs display issue on tutorial (#11347)
@stsewd: allauth: login after email confirmation (#11346)
@stsewd: Tests: set provider explicitly (#11342)
@stsewd: Docs: fix external resources link on support page (#11340)
@humitos: Celery: user builder instead of instance as argument (#11337)
@humitos: Docs: PO only allowed on annual Pro/Enterprise plans (#11335)
@humitos: Release 10.25.0 (#11334)
@agjohnson: Move dashboard API filter fields to model queryset filter fields (#11330)
@humitos: Adapt __str__ and __repr__ methods for DB (#11329)
@stsewd: Update allauth (#11327)
@humitos: Docs: use EthicalAd implementation from addons (#11318)
@plaindocs: Tighten up and refactor the tutorial WIP (#11316)
@stsewd: Organizations: take into account the user when listing members (#11212)
@agjohnson: Allow setting Allauth provider secrets from host system (#11194)
@stsewd: Allow override SOCIALACCOUNT_PROVIDERS from ops (#11165)
@humitos: Lint: run black against all our Python files (#11145)
@taylorhummon: fix highlighting of “fail_on_warning: true” in tutorial (#11144)
@ericholscher: Refactor documentation navigation (#11139)
@humitos: Notifications: fix rendering (#11133)
@humitos: Addons: add model history on AddonsConfig (#11127)
@humitos: Docs: update bullet/item list display (#11123)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11122)
@humitos: Settings: remove unused (#11116)
@stsewd: Notifications: add admin (#11114)
@humitos: Docs: build documentation with social cards (#11109)
@agjohnson: Some fixes for notifications (#11094)

Version 10.25.0

Date:: May 21, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11331)
@agjohnson: Move dashboard API filter fields to model queryset filter fields (#11330)
@humitos: Adapt __str__ and __repr__ methods for DB (#11329)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11323)
@henryiii: docs: update uv instructions (#11322)
@humitos: Docs: use EthicalAd implementation from addons (#11318)
@rffontenelle: Languages code are now normalized (#11315)
@stsewd: Addons: mark project as raw ID in admin (#11311)
@humitos: Wrangler: NGINX and redirects (#11305)
@humitos: Dashboard: promote “security logs” only if organization owner (#11304)
@humitos: Docs: use addons search (#11303)
@humitos: Addons: return 404 when the project does not exist in the DB (#11302)
@jeffwidman: Replace non-existant python.install.package with python.install.path (#11301)
@agjohnson: Use initial value for default dashboard template name (#11298)
@ericholscher: Revert “Cleanup: delete yaml_load_safely (#11285)” (#11297)
@ericholscher: Release 10.24.1 (#11296)
@stsewd: Docs: basic docs for SAML SSO (#11288)
@humitos: Dashboard: promote features in the right bar (#11287)
@humitos: Cleanup: delete yaml_load_safely (#11285)
@stsewd: Notifications: allow usernames with dots (#11283)
@humitos: Addons: refactor sorting versions for flyout (#11278)
@stsewd: Allauth: add SAML integration (#11262)

Version 10.24.1

Date:: April 23, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11294)
@humitos: Docs: explain how to use uv to install dependencies (#11290)
@humitos: Dashboard: promote features in the right bar (#11287)
@humitos: Cleanup: delete yaml_load_safely (#11285)
@stsewd: Notifications: allow usernames with dots (#11283)
@humitos: Release 10.24.0 (#11281)
@humitos: Docs: use the sphinx-rtd-theme with support for addons integration (#11279)
@humitos: Addons: refactor sorting versions for flyout (#11278)
@humitos: Build: remove append_conf _magic_ from MkDocs (#11206)
@humitos: APIv3: add more generic fields (#11205)
@ewdurbin: implement multiple .readthedocs.yml files per repo (#10001)

Version 10.24.0

Date:: April 16, 2024

@hoyes: Dev: Allow Minio to be used without debug mode (#11272)
@ericholscher: Release 10.23.2 (#11269)
@humitos: Notification: typo in message (#11268)
@agjohnson: Add error view for error handling and error view testing (#11263)
@humitos: Build: remove append_conf _magic_ from MkDocs (#11206)
@humitos: APIv3: add more generic fields (#11205)

Version 10.23.2

Date:: April 09, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11267)
@stsewd: Redirects: fix root redirect (/ -> <anything>) (#11265)
@stsewd: Don’t enforce brownouts on tests (#11259)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11251)
@stsewd: Add create views (#11246)
@humitos: Release 10.23.1 (#11244)
@humitos: HTTPheader: add another option (#11241)
@humitos: Build: mark build as CANCELLED when command exits with 183 (#11240)
@stsewd: Organizations: take into account the user when listing members (#11212)

Version 10.23.1

Date:: March 26, 2024

@humitos: HTTPheader: add another option (#11241)
@humitos: Build: mark build as CANCELLED when command exits with 183 (#11240)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11237)
@humitos: APIv3: add state__in filter for Notifications (#11234)
@ericholscher: Fully roll out stickybox (#11230)
@ericholscher: Release 10.23.0 (#11229)
@stsewd: API: don’t allow expanding recursively (#11228)
@humitos: Proxito: define dummy dashboard URLs for addons serializers (#11227)
@stsewd: Organizations: take into account the user when listing members (#11212)
@humitos: Projects: remove requirements_file (#11132)

Version 10.23.0

Date:: March 19, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11224)
@agjohnson: Fix bugs with support form (#11222)
@zliang-akamai: Fix Read the Docs config file name in notifications (#11221)
@humitos: Build: always reset the build before building (#11213)
@humitos: Release 10.22.0 (#11211)
@agjohnson: Add build detail view beta notification (#11208)
@humitos: Addons: allow users to define root_selector from the WebUI (#11181)
@humitos: Addons: sorting algorithm for versions customizable on flyout (#11069)

Version 10.22.0

Date:: March 12, 2024

@agjohnson: Add build detail view beta notification (#11208)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11203)
@humitos: Revert “Notifications: show “Maxium concurrency limit reached” as WARNING” (#11202)
@humitos: Notifications: de-duplicate them when using APIv2 from builders (#11197)
@humitos: Notifications: show “Maxium concurrency limit reached” as WARNING (#11196)
@agjohnson: Allow setting Allauth provider secrets from host system (#11194)
@humitos: Support: create a form to render it nicely in ext-theme (#11193)
@stsewd: Docs: Update Google SSO docs (#11191)
@humitos: Notification: fix choices rendering for INVALID_CHOICE (#11190)
@ericholscher: Release 10.21.0 (#11185)
@stsewd: Project: force PR previews to match repo only if the repo is public (#11184)
@humitos: Addons: allow users to define root_selector from the WebUI (#11181)
@ericholscher: Init path to ensure it exists (#11178)
@stsewd: Project: build both default and latest version when saving the project form (#11177)
@humitos: Build: show the YAML config file before validating it (#11175)
@stsewd: Allow override SOCIALACCOUNT_PROVIDERS from ops (#11165)
@humitos: Lint: run black against all our Python files (#11145)
@humitos: Addons: sorting algorithm for versions customizable on flyout (#11069)

Version 10.21.0

Date:: March 04, 2024

@stsewd: Project: force PR previews to match repo only if the repo is public (#11184)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11180)
@ericholscher: Init path to ensure it exists (#11178)
@stsewd: Project: build both default and latest version when saving the project form (#11177)
@humitos: Build: show the YAML config file before validating it (#11175)
@humitos: Notification: make the OAuth one dismissable (#11172)
@humitos: Build: set CANCELLED state when the build is cancelled (#11171)
@stsewd: Project: merge basic and advanced forms (#11169)
@humitos: Admin: remove temporal opt-out email settings (#11164)
@humitos: New dashboard: notification to point users there (#11161)
@stsewd: Allauth: Include Bitbucket in the list of social accounts (#11160)
@humitos: Release 10.20.0 (#11158)
@stsewd: Allauth: define secrets in settings (#11156)
@hoyes: Dev: Default RTD_DJANGO_DEBUG to False if not set (#11154)
@humitos: Build: bugfix to show build notifications (#11153)
@ewjoachim: Fix Poetry instructions (#11152)
@humitos: VCS: deprecation dates at application level (#11147)
@humitos: Notifications: allow dismiss user’s notifications (#11130)
@humitos: Projects: remove old/non-used fields (#11124)
@stsewd: Match login template with changes from .com (#11101)
@humitos: Addons + Proxito: return X-RTD-Resolver-Filename and inject via CF (#11100)

Version 10.20.0

Date:: February 27, 2024

@stsewd: Allauth: define secrets in settings (#11156)
@humitos: APIv3: add _links.notifications to Project resource (#11155)
@hoyes: Dev: Default RTD_DJANGO_DEBUG to False if not set (#11154)
@humitos: Build: bugfix to show build notifications (#11153)
@ewjoachim: Fix Poetry instructions (#11152)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11148)
@humitos: VCS: deprecation dates at application level (#11147)
@taylorhummon: fix highlighting of “fail_on_warning: true” in tutorial (#11144)
@ericholscher: Refactor the index page to match the sidebar (#11141)
@ericholscher: Refactor documentation navigation (#11139)
@humitos: Lint: more files (#11137)
@agjohnson: Add missing context variable (#11135)
@stsewd: Update Django allauth to 0.57.0 (#11134)
@humitos: Notifications: fix rendering (#11133)
@humitos: Notifications: allow dismiss user’s notifications (#11130)
@humitos: Release 10.19.0 (#11128)
@humitos: Addons: add model history on AddonsConfig (#11127)
@humitos: Projects: remove old/non-used fields (#11124)
@humitos: Addons + Proxito: return X-RTD-Resolver-Filename and inject via CF (#11100)
@arti-bol: Added a troubleshooting section for webhook (#11099)

Version 10.19.0

Date:: February 20, 2024

@humitos: Addons: add model history on AddonsConfig (#11127)
@humitos: wrangler: move script to common/ (#11126)
@humitos: Docs: update bullet/item list display (#11123)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11122)
@humitos: Notifications: show them based on permissions (#11117)
@humitos: Settings: remove unused (#11116)
@stsewd: Fix test on .com (#11115)
@stsewd: Notifications: add admin (#11114)
@saadmk11: API V3: Only return notifications for a given organization (#11112)
@humitos: Docs: build documentation with social cards (#11109)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11108)
@humitos: Build: check for pre-compiled build.tools when using ubuntu-lts-latest (#11098)
@humitos: Release 10.18.0 (#11096)
@agjohnson: Use form validation errors for important UI feedback (#11095)
@agjohnson: Some fixes for notifications (#11094)
@dependabot[bot]: Bump peter-evans/create-pull-request from 5 to 6 (#11092)
@stsewd: Use django-safemigrate for migrations (#11087)
@stsewd: Integrations: Don’t allow webhooks without a secret (#11083)
@humitos: Development: use wrangler locally (update NGINX/Dockerfile config) (#10965)

Version 10.18.0

Date:: February 06, 2024

@dependabot[bot]: Bump peter-evans/create-pull-request from 5 to 6 (#11092)
@man-chi: add example list for showing basic asciidoc using Antora (#11091)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11090)
@stsewd: Use html_format instead of mark_safe + format (#11086)
@stsewd: Build: use version slug for get_version_slug (#11085)
@stsewd: Integrations: Don’t allow webhooks without a secret (#11083)
@stsewd: Config file: add support for latest aliases (#11081)
@stsewd: Proxito: always add nginx internal path (#11080)
@stsewd: Redirects: remove unused status field (#11079)
@stsewd: Docs: fix redirects example (#11078)
@humitos: Release 10.17.0 (#11077)
@stsewd: Docs: clarify search configuration patterns (#11076)
@humitos: Build: add support for Ruby (#11075)
@humitos: Build: update some build.tools versions (#11074)
@humitos: Make Sphinx to share environment between commands (#11073)
@ericholscher: Fix provier_name in notification template (#11066)
@humitos: Build: don’t attach notification when build failed before_start (#11057)
@humitos: Notification: create an index for attached_to (#11050)
@stsewd: Redirects: fix infinite loop detection (#11038)
@ericholscher: Release 10.15.1 (#11034)
@humitos: Logging: reduce not useful lines (#11030)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10860)
@stsewd: Fix docker setting (#10565)
@humitos: Deprecation: remove code for config file v1 and default config file (#10367)
@benjaoming: Docs: Re-scope Intersphinx article as a how-to (#9622)

Version 10.17.0

Date:: January 30, 2024

@humitos: Build: update some build.tools versions (#11074)
@humitos: Make Sphinx to share environment between commands (#11073)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11070)
@humitos: Addons: build.current API response fix (#11068)
@stsewd: Integrations: add created and updated fields to model (#11067)
@ericholscher: Fix provier_name in notification template (#11066)
@stsewd: Analytics: don’t record page views for PR previews (#11065)
@stsewd: Custom domain: don’t allow external domain (#11064)
@stsewd: Fix migration (#11063)
@humitos: Notifications: improve copy on error messages (#11062)
@stsewd: Embed API: fix regex patterns for allowed external domains (#11059)
@stsewd: Redirects: check if path is None and fix merge of query params (#11058)
@humitos: Build: don’t attach notification when build failed before_start (#11057)
@humitos: Addons: disable analytics by default (#11056)
@humitos: Release 10.16.1 (#11054)
@stsewd: Docs: move warning from embed API to the top (#11053)
@humitos: APIv3: bring back OrganizationsViewSet that was removed (#11052)
@humitos: Release 10.16.0 (#11051)
@humitos: Notification: create an index for attached_to (#11050)
@humitos: Notification: cancel notifications automatically (#11048)

Version 10.16.1

Date:: January 23, 2024

@humitos: APIv3: bring back OrganizationsViewSet that was removed (#11052)
@humitos: Release 10.16.0 (#11051)

Version 10.16.0

Date:: January 23, 2024

@humitos: Docs: remove dead example (#11047)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11046)
@stsewd: Expose assert_path_is_inside_docroot function (#11045)
@stsewd: Resolver: don’t use str.format (#11044)
@humitos: Analytics: remove them from 404 pages (#11041)
@humitos: Config: allow missing conda.environment when using build.commands (#11040)
@humitos: Translations: update all of them (#11039)
@stsewd: Redirects: fix infinite loop detection (#11038)
@humitos: Admin: remove “default settings” (#11036)
@ericholscher: Release 10.15.1 (#11034)
@humitos: Addons: update form to show all the options (#11031)
@humitos: Logging: reduce not useful lines (#11030)
@humitos: APIv3: endpoints for notifications (#11009)
@humitos: Config: better validation error for conda.environment (#10979)
@stsewd: Docs: document CORS policies (#10853)

Version 10.15.1

Date:: January 16, 2024

@stsewd: Update docs requirements (#11032)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11029)
@stsewd: Redirects: limit to 100 per project (#11028)
@humitos: Build: reset notifications when reseting a build (#11027)
@humitos: Development: define SUPPORT_EMAIL setting (#11026)
@humitos: Notifications: use Template’s Django engine to render them (#11024)
@humitos: Notifications: render Organization notifications on details page (#11023)
@humitos: Notifications: add missing format_values (#11021)
@humitos: Notifications: save format_values when on_retry exception (#11020)
@humitos: Notifications: initialize exception properly (#11019)
@humitos: Notifications: use instance.slug instead of instance.name (#11018)
@humitos: Notification: oauth typo on URL name (#11017)
@humitos: Notifications: typo on constant (#11015)
@humitos: Build: typo on on_retry (#11014)
@humitos: Black: run black over all the code base (Part 2) (#11013)
@humitos: Build: remove browndates for config file (#11012)
@humitos: Release 10.15.0 (#11011)
@humitos: Notifications: small fixes found after reviewer (#10996)
@humitos: Config: better validation error for conda.environment (#10979)

Version 10.15.0

Date:: January 09, 2024

@humitos: pip-compile fixes (#11010)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#11005)
@ericholscher: Fix structlog by downgrading it (#11003)
@humitos: Eslint fix issues (#10998)
@webknjaz: Fix ref to the “new addons integrations” blog post @ custom build doc (#10997)
@humitos: Notifications: small fixes found after reviewer (#10996)
@stsewd: Update common (#10995)
@humitos: Remove leftovers from django-messages-extends (#10994)
@stsewd: Integrations: hardcode deprecation date for incoming webhooks without a secret (#10993)
@stsewd: Development: update steps for testing subscriptions (#10992)
@stsewd: Redirects: remove null option from position field (#10991)
@ericholscher: Release 10.14.0 (#10989)
@humitos: Addons: get translation from main project (#10952)
@humitos: New notification system: implementation (#10922)
@stsewd: Custom domains: don’t allow adding a custom domain on subprojects (#8953)

Version 10.14.0

Date:: January 03, 2024

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10977)
@basnijholt: Fix YAML indentation in example readthedocs.yaml (#10970)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10969)
@humitos: Release 10.13.0 (#10961)
@agjohnson: Allow override of env settings from host (#10959)
@humitos: Addons: get translation from main project (#10952)
@dependabot[bot]: Bump actions/setup-python from 4 to 5 (#10950)
@stsewd: Search: fix default for search.ranking when indexing (#10945)
@ericholscher: Release 10.12.2 (#10944)
@stsewd: Redirects: improvements from design doc (#10881)

Version 10.13.0

Date:: December 19, 2023

@agjohnson: Allow override of env settings from host (#10959)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10957)
@humitos: Addons: normalize search filters (#10951)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10949)
@agjohnson: Allow empty project list on organization team form (#10947)
@ericholscher: Release 10.12.2 (#10944)
@ericholscher: Add AddonsConfig admin (#10938)

Version 10.12.2

Date:: December 05, 2023

@humitos: Requirements: pin django-ipware<6 (#10932)
@humitos: Translation: revert German translation (#10931)
@humitos: Release 10.12.1 (#10929)
@humitos: Release/10.12.0 (#10928)
@humitos: Design: small update to add a PATCH endpoint (#10919)
@stsewd: Search: index in small chunks (#10914)
@stsewd: Search: check for build being None (#10913)
@stsewd: Automation Rules: simplify ordering (#10896)

Version 10.12.1

Date:: November 28, 2023

@humitos: Release/10.12.0 (#10928)
@humitos: Design: small update to add a PATCH endpoint (#10919)

Version 10.12.0

Date:: November 28, 2023

@kurtmckee: Fix a typo in the word ‘Sphinx’ (#10926)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10925)
@humitos: Feature flag: remove CDN_ENABLED which is not used anymore (#10921)
@humitos: Design: small update to add a PATCH endpoint (#10919)
@stsewd: Search: index in small chunks (#10914)
@stsewd: Search: check for build being None (#10913)
@hugovk: Add link to docs in error message (#10910)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10909)
@stsewd: Integrations: always show secret and show warning if secret is not set (#10908)
@stsewd: Integrations: better error message for integrations without a secret (#10903)
@ericholscher: Release 10.11.0 (#10900)
@ericholscher: Mention custom sitemap via robots.txt (#10899)
@humitos: Design doc: new notification system (#10890)
@stsewd: Project: use a choicefield for selecting the versioning scheme (#10845)
@stsewd: Proxito: support single language project (#10766)
@nikblanchet: Docs: Configuration file how-to guide (#10301)
@humitos: Build: expose VCS-related environment variables (#10168)

Version 10.11.0

Date:: November 14, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10898)
@humitos: Release 10.10.0 (#10893)
@jertel: docs: update documentation around version warning banner (#10877)

Version 10.10.0

Date:: November 07, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10889)
@stsewd: Revert “Build: use tag name for checkout” (#10887)
@ericholscher: Make Ubuntu callout correct (#10883)
@ericholscher: Release 10.9.0 (#10880)
@stsewd: Build: use tag name for checkout (#10879)
@stsewd: Resolver: use new methods to resolve documentation pages (#10875)
@humitos: Resolver: don’t use one global instance and implement caching (#10872)
@agjohnson: Add organization view UI filters (#10847)
@stsewd: Redirects (design doc): improving existing functionality (#10825)

Version 10.9.0

Date:: October 31, 2023

@stsewd: Build: use tag name for checkout (#10879)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10876)
@stsewd: Resolver: use new methods to resolve documentation pages (#10875)
@stsewd: CI: update circleci API call (#10874)
@humitos: Addons: improve DB query for projects_feature table (#10871)
@humitos: NGINX: inject the proper readthedocs-version-slug (#10870)
@stsewd: Unresolver: remove old language code compatibility (#10869)
@humitos: Addons: return the first() object (#10868)
@stsewd: Config file: remove deprecated keys from json schema (#10867)
@humitos: Release 10.8.1 (#10865)
@humitos: Release 10.8.0 (#10864)
@humitos: DB: create an index for builds_build table to improve Addons API (#10840)
@stsewd: Redirects (design doc): improving existing functionality (#10825)
@humitos: Addons: accept project-slug and version-slug on endpoint (#10823)
@stsewd: Resolver: refactor (#10813)
@stephenfin: docs: Document how to fetch additional branches (#10795)

Version 10.8.1

Date:: October 24, 2023

@humitos: Release 10.8.0 (#10864)
@humitos: Addons: accept project-slug and version-slug on endpoint (#10823)

Version 10.8.0

Date:: October 24, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10860)
@mathbunnyru: Docs: fix formatting of commented configuration example (#10858)
@stsewd: Tests: set privacy level explicitly (#10854)
@stsewd: Tests: set privacy level explicitly (#10852)
@stsewd: Docs: update docs about default dependencies (#10851)
@stsewd: Update common (#10850)
@stsewd: Revert “Build (python): default 3 to 3.11” (#10846)
@stsewd: Build: install compatible version of virtualenv in images (#10844)
@ericholscher: Keep Ad Customization in the docs (#10843)
@humitos: DB: create an index for builds_build table to improve Addons API (#10840)
@jugmac00: Fix broken link syntax (#10837)
@stsewd: Build: don’t pre-install pip and setuptools in images (#10834)
@stsewd: Build (python): default 3 to 3.11 (#10833)
@humitos: Addons: expand db query to get the type as well (#10829)
@stsewd: Redirects: fix prefix redirects (#10828)
@ericholscher: Release 10.7.1 (#10827)
@humitos: Addons: accept project-slug and version-slug on endpoint (#10823)
@ericholscher: Clarify admin permission (#10822)
@humitos: Addons: resolve versions/translations URLs properly (#10821)
@stsewd: Docs: update root language redirect docs (#10817)
@stsewd: Proxito: normalize code languages and redirect to them (#10750)
@humitos: Deprecation: remove code for config file v1 and default config file (#10367)
@nikblanchet: Docs: Configuration file how-to guide (#10301)

Version 10.7.1

Date:: October 17, 2023

@humitos: Addons: docdiff compare against LATEST (#10820)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10819)
@humitos: Logs: always log documentation size in megabytes (#10812)
@humitos: Script: compile versions for S3 (#10811)
@humitos: Docs: deprecated note about flyout integration/customization (#10810)
@humitos: Release 10.7.0 (#10809)
@A5rocks: Add Python 3.12 to allowed Python versions (#10808)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10807)
@stsewd: Proxito: always use subdomain for serving docs (#10799)
@ericholscher: Release 10.6.1 (#10792)
@humitos: Addons: add test cases for the endpoint (#10754)
@ericholscher: Merge Diataxis into main! (#10034)
@humitos: structlog: migrate application code to better logging (#8705)

Version 10.7.0

Date:: October 10, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10807)
@stsewd: Webhooks: use PUBLIC_API_URL to generate the webhook URL (#10801)
@stsewd: Use get to access build dictionary (#10797)
@ericholscher: Release 10.6.1 (#10792)
@stsewd: Proxito: remove one query from the middleware (#10788)
@stsewd: BuildAPIKey: remove old revoked/expired keys (#10778)
@stsewd: Upgrade ES to 8.x (#10771)
@humitos: VCS: remove unused methods and make new Git pattern the default (#8968)
@ojii: Versioned docs (#22)

Version 10.6.1

Date:: October 03, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10784)
@jidanni: Update index.rst (#10780)
@stsewd: Build: log directory size to be uploaded (#10779)
@stsewd: BuildAPIKey: remove old revoked/expired keys (#10778)
@stsewd: SSO: update Google Workspace integration docs (#10774)
@humitos: Release 10.6.0 (#10772)
@stsewd: Test ES upgrade to 7.17.13 (#10770)
@humitos: Docs: update example for AsciiDoc to simplify it a little (#10763)
@humitos: Build: remove support for MkDocs <= 0.17.3 (#10584)
@humitos: Deprecation: remove support for Sphinx 1.x (#10365)
@stsewd: SearchQuery: use BigAutoField for primary key (#9671)
@ojii: Versioned docs (#22)

Version 10.6.0

Date:: September 26, 2023

@stsewd: Test ES upgrade to 7.17.13 (#10770)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10768)
@humitos: Docs: update example for AsciiDoc to simplify it a little (#10763)
@stsewd: Proxyto: Allow CORS on commercial on public docs pages (#10762)
@stsewd: Fix CORS headers in local dev (#10761)
@oraNod: Docs: add asciidoc example (#10759)
@humitos: APIv3: return single_version field on Project resource (#10758)
@stsewd: Build indexing: fix indexing of external versions (#10756)
@humitos: Addons: move the HTTP header to a GET parameter (#10753)
@humitos: Proxito: update CORS settings (#10751)
@ericholscher: Release 10.5.0 (#10749)
@stsewd: Tasks: remove old fileify task (#10747)
@humitos: Addons: get final project (e.g. subproject) (#10745)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10744)
@stsewd: Subscriptions: remove old models (#10740)
@ericholscher: Change frequency of pageview delete code (#10739)
@stsewd: Versions: allow latest to be a tag (#10738)
@humitos: Proxito: add CORS headers only on public versions (#10737)
@humitos: Docs: remove feature flags page (#10736)
@humitos: Addons: allow users to opt-in into the beta addons (#10733)
@agjohnson: Custom domain doc improvements (#10719)
@humitos: API: return the api_version on the response (#10276)

Version 10.5.0

Date:: September 18, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10744)
@stsewd: Subscriptions: remove old models (#10740)
@ericholscher: Change frequency of pageview delete code (#10739)
@humitos: Proxito: add CORS headers only on public versions (#10737)
@humitos: Docs: remove feature flags page (#10736)
@humitos: Addons: allow users to opt-in into the beta addons (#10733)
@humitos: Docs: review and update the whole FAQ page. (#10732)
@humitos: Release 10.4.0 (#10727)
@humitos: Addons: include hotkeys in API response (#10722)
@humitos: Docs: make sphinx.configuration in the tutorial (#10718)
@humitos: Requirements: revert upgrade to psycopg==3.x (#10713)
@humitos: FooterAPI: use AdminPermission when working with object users (#10709)
@stsewd: Search: stop relying on the DB when indexing (#10696)

Version 10.4.0

Date:: September 12, 2023

@dependabot[bot]: Bump actions/checkout from 3 to 4 (#10724)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10723)
@humitos: Addons: include hotkeys in API response (#10722)
@humitos: Requirements: revert upgrade to psycopg==3.x (#10713)
@atugushev: Fix blog post URL (#10712)
@humitos: Release 10.3.0 (#10711)
@humitos: Develop: another round of black (#10710)
@humitos: Docs: update build.commands note (#10708)
@humitos: Addons: allow to be extended by corporate (#10705)
@humitos: Addons: add CDN-Tags to endpoint and auto-purge cache (#10704)
@stsewd: Footer API: include current user in queryset (#10695)
@agjohnson: Black pass number 2 (#10693)
@stsewd: Subscriptions: remove old code (#10642)

Version 10.3.0

Date:: September 05, 2023

@humitos: Develop: another round of black (#10710)
@humitos: Addons: allow to be extended by corporate (#10705)
@humitos: Addons: add CDN-Tags to endpoint and auto-purge cache (#10704)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10700)
@stsewd: Project: set build_data as blank=True (#10697)
@stsewd: Footer API: include current user in queryset (#10695)
@agjohnson: Black pass number 2 (#10693)
@humitos: Requirements: update docs dependencies (#10687)
@humitos: Addons: manage single version projects (#10686)
@stsewd: Delete imported files when deactivating version (#10684)
@stsewd: 404: skip not built versions (#10681)
@humitos: Release 10.2.0 (#10679)
@stsewd: Search: remove non-generic parser code (#10676)
@stsewd: Automation rules: show dates in admin (#10675)
@humitos: Requirements: use psycopg3 (#10667)
@humitos: Addons: prepare the backend for the new flyout (#10650)
@stsewd: Subscriptions: remove old code (#10642)
@humitos: Deprecation: remove “use system packages” (python.system_packages config key and UI checkbox) (#10562)
@agjohnson: Add beta version of doc diff library for testing (#9546)

Version 10.2.0

Date:: August 29, 2023

@stsewd: Automation rules: show dates in admin (#10675)
@stsewd: Tests: don’t enforce hardcoded brownouts (#10673)
@humitos: Docs: update conda config key to mention build.tools.python (#10672)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10669)
@humitos: Django 3.x upgrade (#10668)
@humitos: Build: define html_theme variable (#10663)
@stsewd: Proxito: remove old implementation (#10660)
@stsewd: CI: Add requirements/testing.txt to pre-commit cache key (#10658)
@stsewd: Set SECURE_PROXY_SSL_HEADER when using docker compose (#10657)
@humitos: Tests: Update Sphinx test matrix for EmbedAPI (#10655)
@humitos: Build: remove using_rtd_theme variable (#10653)
@humitos: Release 10.1.0 (#10652)
@ecormany: docs: typo fix on “Custom and built-in redirects” page (#10651)
@humitos: Addons: prepare the backend for the new flyout (#10650)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10649)
@humitos: Build: do not set sphinx_rtd_theme theme automatically (#10638)
@stsewd: Git: simplify submodule checks (#10635)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10628)
@stsewd: Proxito: Don’t hit storage for 404s (#10617)
@humitos: Feature flag: remove DONT_SHALLOW_CLONE (#10588)
@humitos: Deprecation: remove “use system packages” (python.system_packages config key and UI checkbox) (#10562)
@humitos: Feature flag: remove UPDATE_CONDA_STARTUP (#10494)
@saadmk11: Stop creating a conf.py automatically and doing magic around README handling (#5609)

Version 10.1.0

Date:: August 22, 2023

@ecormany: docs: typo fix on “Custom and built-in redirects” page (#10651)
@humitos: Celery: use django-celery-beat scheduler (#10647)
@humitos: Build: drop websupport2 support from conf.py template (#10646)
@ericholscher: Remove the celery email tasks until we can debug them. (#10641)
@humitos: Development: disable cached Loader on DEBUG=True (#10640)
@humitos: Docs: update tutorial with the latest required changes (#10639)
@humitos: Build: do not set sphinx_rtd_theme theme automatically (#10638)
@humitos: Build: update links to blog post (#10636)
@stsewd: Proxito: allow to generate proxied API URLs with a prefix (#10634)
@ericholscher: Small wording cleanup on Integration howto (#10632)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10628)
@humitos: Black: run black over all the code base (#10619)
@humitos: Revert “Contact projects with a build in the last 3 years” (#10618)
@humitos: Settings: remove CSRF_COOKIE_MASKED (#10608)
@stsewd: Versions: keep type of version in sync with the project (#10606)
@humitos: Import: remove extra/advanced step from project import wizard (#10603)
@benjaoming: Docs: Methodology section (#10417)
@humitos: VCS: remove unused methods and make new Git pattern the default (#8968)

Version 10.0.0

This release is a Django 4.2 upgrade, so it has a major version bump, 10.0!

Date:: August 14, 2023

@ericholscher: Update deprecation timezone to use PDT (#10631)
@stsewd: Custom domain: increase header value length (#10625)
@ericholscher: Use same HomepageView for Community & Business (#10621)
@humitos: Black: run black over all the code base (#10619)
@stsewd: Build: Fix exceptions (#10616)
@stsewd: Revert “Proxito: test new implementation more broadly (#10599)” (#10614)
@humitos: Translations: update them all (#10613)
@humitos: Deprecation: codify browndates for “no config file deprecation” (#10612)
@humitos: Testing: run Coverage report only on CircleCI (#10611)
@humitos: Profile: redirect to /accounts/edit/ view on successful edit (#10610)
@humitos: Release 9.16.4 (#10609)
@stsewd: Admin: show creation/modification dates on the admin page (#10607)
@stsewd: Versions: keep type of version in sync with the project (#10606)
@stsewd: Proxito: test new implementation more broadly (#10599)
@humitos: Django: upgrade to 4.2 (#10595)
@stsewd: Build: replace GitPython with git commands (#10594)
@agjohnson: Add organization listing filter (#10593)
@humitos: Deprecation: notification and feature flag for build.image config (#10589)
@stsewd: Subscriptions: use djstripe for products/features (#10238)

Version 9.16.4

Date:: August 08, 2023

@humitos: Development: minor updates to Dockerfile (#10605)
@stsewd: Proxito: test new implementation more broadly (#10599)
@stsewd: Fix test (#10597)
@agjohnson: Add organization listing filter (#10593)
@agjohnson: Add USE_ORGANIZATIONS context variablea (#10592)
@stsewd: Fix docs (#10591)
@ericholscher: Release 9.16.3 (#10590)
@agjohnson: Update support page (#10580)
@humitos: Search: delete sphinx_domains Django app completely (#10574)
@humitos: Build: skip duplicated commands (#10573)
@ericholscher: Add redirect to about.readthedocs.com for logged out users (#10570)
@humitos: API: analytics return 400 when there is an error (#10240)

Version 9.16.3

Date:: August 01, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10582)
@stsewd: Remove unused code (#10579)
@ericholscher: Uninstall sphinx_domains app to it’s models aren’t registered (#10578)
@ericholscher: Clarify forced redirects (#10577)
@humitos: Build tools: run asdf version from inside the container (#10575)
@humitos: Build: skip duplicated commands (#10573)
@humitos: Build: add mambaforge-22.09 as newer Python tool (#10572)
@humitos: Release 9.16.2 (#10566)
@stsewd: Fix docker setting (#10565)
@humitos: Development: install Docker and Docker Compose with official guides (#10561)
@humitos: Build: use only-if-needed pip’s strategy when installing package (#10560)
@humitos: Docs: mention how to use inv docker.compilebuildtool (#10554)
@humitos: Build: fail builds if there is no index.html in the output dir (#10550)
@humitos: Telemetry: check for Sphinx config before use it (#10546)
@agjohnson: Fix bug with build filter (#10528)
@stsewd: Search: unify Sphinx and generic parser (#10520)
@humitos: Version warning banner: disable it for project not using it already (#10483)

Version 9.16.2

Date:: July 25, 2023

@stsewd: Fix docker setting (#10565)
@humitos: Development: install Docker and Docker Compose with official guides (#10561)
@humitos: Build: use only-if-needed pip’s strategy when installing package (#10560)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10557)
@humitos: Build: use a setting to define the Docker image for the clone step (#10555)
@humitos: Docs: mention how to use inv docker.compilebuildtool (#10554)
@humitos: API: add ?full_name= icontains filter on RemoteRepository (#10551)
@humitos: Telemetry: check for Sphinx config before use it (#10546)
@denisSurkov: Docs: Fix pinned term (#10545)
@humitos: Dependencies: unpin pyyaml (#10544)
@humitos: Release 9.16.1 (#10543)
@humitos: Development: update docs to pull required images only (#10535)
@agjohnson: Add missing Version.external_version_name (#10529)
@agjohnson: Fix bug with build filter (#10528)
@humitos: Requirements: update newrelic (#10525)
@humitos: Build: remove PyPy support (#10523)

Version 9.16.1

Date:: July 17, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10542)
@humitos: Development: update docs to pull required images only (#10535)
@humitos: Addons: return ethicalads data on /_/addons/ endpoint (#10534)
@humitos: Celery: handle known exceptions on delete_closed_external_versions (#10532)
@humitos: Addons: rename library (#10531)
@agjohnson: Add conditional logic to replace project version list view (#10530)
@humitos: Addons: rename endpoint to make it nicer (#10526)
@humitos: Release 9.16.0 (#10524)
@humitos: Build: remove PyPy support (#10523)
@agjohnson: Docs: swap around content for configuration files (#10517)
@humitos: Build: install all the latest Python “core requirements” (#10508)
@stsewd: Build API key: trim name to max allowed length (#10487)
@humitos: Deprecation: show the project slug/link correctly on email (#10432)

Version 9.16.0

Date:: July 11, 2023

@humitos: Revert “Build: remove PyPy support” (#10522)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10521)
@stsewd: Docs: set title explicitly (#10519)
@stsewd: Docs (dev): update server side search integration doc (#10518)
@stsewd: Search: use generic parser for MkDocs projects (#10516)
@humitos: MkDocs: fix USE_MKDOCS_LATEST feature flag logic (#10515)
@humitos: Build: remove PyPy support (#10514)
@humitos: OAuth: catch TokenExpiredError exception (#10510)
@mgeier: Remove a superfluous space character (#10509)
@humitos: Builds: set scale-in protection before/after each build (#10507)
@humitos: Settings: remove old settings (#10504)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10503)
@stsewd: API V2: remove write access to superusers (#10498)
@ericholscher: Reduce logging of common redirects and expected items (#10497)
@benjaoming: Test: Verify “cat .readthedocs.yaml” was called (#10495)
@humitos: Docs: update Conda to its latest available version (#10493)
@benjaoming: Tests: Mock revoking build API key (#10491)
@humitos: Docs: remove setuptools from our docs (#10490)
@stephenfin: docs: Correct typo (#10489)
@stsewd: Build API key: don’t fetch and validate key twice (#10488)
@stsewd: Build API key: trim name to max allowed length (#10487)
@humitos: Docs: use $READTHEDOCS_OUTPUT variable in examples (#10486)
@humitos: Docs: do not fail when unshallow clone (#10485)
@humitos: Version warning banner: disable it for project not using it already (#10483)
@benjaoming: Docs: Update example Sphinx .readthedocs.yaml (#10481)
@benjaoming: Images: Add tzdata as explicit requirement (#10480)
@benjaoming: CI: Use a cache for pre-commit (#10479)
@humitos: Docs: update build.tools versions (#10478)
@humitos: Docs: typos (#10476)
@ericholscher: Release 9.15.0 (#10475)
@MSanKeys963: Docs: Typo fix for integrations.rst (#10474)
@stsewd: Fix pip-tools GitHub action (#10473)
@humitos: Feature flag: remove DONT_CREATE_INDEX (#10471)
@humitos: Notification: expand management command to follow conventions (#10470)
@humitos: Build: always use gvisor Docker runtime (#10469)
@humitos: Script: build tools updates (#10467)
@stsewd: API V2: Optimize /project/active_versions and /version/ endpoints (#10460)
@davidfischer: Update gold docs to reflect cross-site cookie reality (#10459)
@humitos: Addons: improve “active and built Versions” query (#10455)
@stsewd: Add helper task to update dependencies (#10447)
@humitos: DB: do not fetch data and others when deleting rows (#10446)
@benjaoming: Docs: Add “Git provider account connection” feature description (#10442)
@benjaoming: Dashboard: Update docs link (#10441)
@humitos: Deprecation: show the project slug/link correctly on email (#10432)
@benjaoming: Build: Simplify and optimize git backend: New clone+fetch pattern (#10430)
@humitos: Addons: handle API exceptions from unresolver (#10427)
@stsewd: Use project-scoped temporal tokens to interact with the API from the builders (#10378)
@humitos: Bower: disable strict-ssl (#10370)
@EwoutH: Update patch versions and add new ones for all supported languages (#10217)
@humitos: Docs: mention docsify on “Build customization” (#9439)

Version 9.15.0

Date:: June 26, 2023

@MSanKeys963: Docs: Typo fix for integrations.rst (#10474)
@stsewd: Fix pip-tools GitHub action (#10473)
@humitos: Script: build tools updates (#10467)
@humitos: Addons: improve db query when adding HTTP header from El Proxito (#10461)
@stsewd: API V2: Optimize /project/active_versions and /version/ endpoints (#10460)
@benjaoming: Docs: Replace navigation instructions with direct URLs w/ organization chooser (#10457)
@humitos: Addons: improve “active and built Versions” query (#10455)
@stsewd: API V3: add IsAuthenticated to permissions (#10452)
@stsewd: Search: stop creating SphinxDomain objects (#10451)
@stsewd: Unresolver: check for valid schemes when unresolving URL (#10450)
@humitos: Release 9.14.0 (#10449)
@stsewd: Proxito: easy migration to custom path prefixes (#10448)
@stsewd: Add helper task to update dependencies (#10447)
@humitos: Addons: handle API exceptions from unresolver (#10427)
@humitos: Celery: increase frequency of delete_closed_external_versions task (#10425)
@stsewd: Use project-scoped temporal tokens to interact with the API from the builders (#10378)
@EwoutH: Update patch versions and add new ones for all supported languages (#10217)
@humitos: Docs: mention docsify on “Build customization” (#9439)
@davidfischer: Flyout and Footer API design document (#8052)

Version 9.14.0

Date:: June 20, 2023

@stsewd: Test with explicit number of concurrent builds (#10444)
@benjaoming: Do not show paths in 404s (#10443)
@humitos: Deprecation: opt-out from config file email (#10440)
@humitos: Deprecation: send emails to “active projects” only (#10439)
@humitos: Use latest common/ (#10436)
@benjaoming: Docs: Add email template to report abandoned projects (#10435)
@rffontenelle: Update instructions for using transifex client tool (#10434)
@stsewd: CI: trigger circleci job on readthedocs-ext on merge (#10433)
@humitos: Deprecation: show the project slug/link correctly on email (#10432)
@ericholscher: Add the api_client into the sync_repo task (#10431)
@humitos: Release 9.13.3 (#10428)
@humitos: Analytics: create DB index on PageView.date (#10426)
@humitos: Celery: increase frequency of delete_closed_external_versions task (#10425)
@humitos: Feature flag: remove unused ones (#10423)
@benjaoming: Docs: Configuration file pages as explanation and reference (Diátaxis) (#10416)
@ericholscher: Deprecation: send email notifications for config file v2 (#10415)
@ericholscher: Add a cat command and note in the build output when a config file is properly used. (#10413)
@humitos: Build: fail builds without configuration file or using v1 (#10355)
@stsewd: Design doc: secure access to APIs from builders (#10289)

Version 9.13.3

Date:: June 13, 2023

@humitos: GitHub Action: remove team-reviewers because it requires a GH-PAT (#10421)
@ericholscher: Deprecation: send email notifications for config file v2 (#10415)
@humitos: Deprecation: improve Celery task db query (#10414)
@benjaoming: Docs: Add an “explanation index” (#10412)
@benjaoming: Docs: Correct title case for SEO occurrences (#10409)
@benjaoming: Docs: Add $READTHEDOCS_OUTPUT to environment variable reference (#10407)
@benjaoming: Bump sphinx-rtd-theme to 1.2.2 (#10400)
@agjohnson: Fix display issues with project creation config page (#10398)
@benjaoming: Docs: Split email notifications and webhook notifications into separate howtos (#10396)
@agjohnson: Fixes on Git providers (#10395)
@stsewd: Sphinx: don’t override html_context by default (#10394)
@benjaoming: Project: Add deprecation and removal warning to Advanced Settings (#10393)
@humitos: Release 9.13.2 (#10391)
@stsewd: Build: pass api_client down to environment/builders/etc (#10390)
@benjaoming: Docs: Add some messages flagging the upcoming requirement of a .readthedocs.yaml (#10389)
@benjaoming: Dev: invoke options –no-django-debug and –http-domain (#10384)
@benjaoming: Docs: Define ‘maintainer’ so we can reference it (#10381)
@benjaoming: Build: Bug in target_url, failure to add “success” status if no external version exists (#10369)
@humitos: Project: suggest a simple config file on project import wizard (#10356)
@humitos: Config: deprecated notification for projects without config file (#10354)
@nikblanchet: Docs: Configuration file how-to guide (#10301)
@stsewd: Proxito: allow custom path prefixes (#10156)

Version 9.13.2

Date:: June 06, 2023

@stsewd: Build: pass environment explicitly (#10388)
@agjohnson: Try to bump up config file search in ranking (#10387)
@benjaoming: Dev: invoke options –no-django-debug and –http-domain (#10384)
@benjaoming: Doc: Remove broken reference (#10382)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10380)
@stsewd: Logs: remove caching without tags log warning (#10376)
@stsewd: Build: merge BaseEnvironment with BuildEnvironment (#10375)
@stsewd: Build: avoid breaking builds when a new argument is added to a task (#10374)
@stsewd: Remove unused permission classes (#10373)
@benjaoming: Build: Bug in target_url, failure to add “success” status if no external version exists (#10369)
@ericholscher: Release 9.13.1 (#10366)
@benjaoming: Small index page tweak (#10358)
@humitos: Project: suggest a simple config file on project import wizard (#10356)
@humitos: Config: deprecated notification for projects without config file (#10354)

Version 9.13.1

Date:: May 30, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10362)
@benjaoming: Small index page tweak (#10358)
@humitos: Email: trust GH and GL emails and mark them as verified (#10357)
@humitos: Docs: note explaining build.apt_packages doesn’t work with build.commands (#10347)
@humitos: Requirements: upgrade Docker (#10341)
@humitos: Requirements: upgrade DDT to avoid an issue (#10340)
@benjaoming: Bump sphinx-rtd-theme to 1.2.1 (#10338)
@humitos: Version: new field addons (#10337)
@humitos: Release 9.13.0 (#10336)
@humitos: Build: allow multi-line commands on build.commands (#10334)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10330)
@stsewd: Organizations: allow users without organizations to see their own profiles (#10329)
@stsewd: Version comparing: sort 1.x versions last (#10326)
@benjaoming: Organizations: Organization chooser page (#10325)
@benjaoming: Proxito: Search scope narrowed to active project (version, translation or subproject 404s) (#10324)
@stsewd: Proxito: redirect to default version from root language (#10313)
@stsewd: API V3: clean version when deactivated and build version when activated (#10308)
@stsewd: Builds: avoid breaking builds when adding a new field to our APIs (#10295)
@benjaoming: Docs: Update “How to import private repositories” (Diátaxis) (#10251)
@benjaoming: Docs: Relabel howto guides for Git repository configuration (Diátaxis) (#10247)
@stsewd: PageView: use BigAutoField for primary key (#9670)

Version 9.13.0

Date:: May 23, 2023

@humitos: Build: allow multi-line commands on build.commands (#10334)
@stsewd: Organizations: allow users without organizations to see their own profiles (#10329)
@stsewd: Version comparing: sort 1.x versions last (#10326)
@benjaoming: Proxito: Search scope narrowed to active project (version, translation or subproject 404s) (#10324)
@stsewd: Fix resolver tests on .com (#10316)
@stsewd: Search: fix when searching an empty query (#10312)
@stsewd: API V3: clean version when deactivated and build version when activated (#10308)
@agjohnson: Change a few configuration file options from required to not required (#10303)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10298)
@stsewd: GitHub: add feature request template (#10294)
@stsewd: Build: use same version of setuptools when using system_packages (#10287)
@ericholscher: Release 9.12.0 (#10284)
@benjaoming: Allow build.commands without build.tools (#10281)
@stsewd: Embed API V3: allow private versions (#10261)

Version 9.12.0

Date:: May 02, 2023

@benjaoming: Allow build.commands without build.tools (#10281)
@benjaoming: Remove raise_for_exception=False tests (#10280)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10278)
@stsewd: Remove dead code (#10275)
@benjaoming: Dev: Disable cacheops in proxito docker environment (#10274)
@stsewd: Tests: be explicit about the privacy level (#10273)
@stsewd: Fix typo in tests (#10271)
@stsewd: Update docs about setuptools dependency (#10270)
@stsewd: Build: Pin setuptools only when required (#10268)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10267)
@benjaoming: Backend: Make Features ordered in a nice way (#10262)
@stsewd: Proxito: allow overlapping public and external version domains (#10260)
@ericholscher: Revert “Proxito: inject hosting integration header for build.commands (#10219)” (#10259)
@stsewd: Test explicitly without organizations (#10258)
@ericholscher: Release 9.11.0 (#10255)
@stsewd: Tests: set production domain explicitly (#10253)
@benjaoming: Docs: Style guide stash (#10250)
@benjaoming: Docs: New entries to glossary (#10249)
@stsewd: Proxito: handle http to https redirects for all requests (#10199)
@ericholscher: Fix checking of PR status (#10085)
@ewdurbin: implement multiple .readthedocs.yml files per repo (#10001)
@benjaoming: Contextualize 404 page (#9657)

Version 9.11.0

Date:: April 18, 2023

@benjaoming: Fix a little test failure (#10248)
@benjaoming: Scripts: Add export statements and instruction to fetch awscli (compile_version_upload_s3.sh) (#10245)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10244)
@stsewd: API V3: make tests explicit (#10236)
@ericholscher: Release 9.10.1 (#10235)
@dependabot[bot]: Bump peter-evans/create-pull-request from 4 to 5 (#10233)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10232)
@agjohnson: Add notes on private repo support in our install docs (#10230)
@stsewd: Analytics API: check if absolute_uri isn’t present (#10227)
@humitos: Proxito: inject hosting integration header for build.commands (#10219)
@humitos: API: hosting integrations endpoint versioning/structure (#10216)
@benjaoming: Search: index <dl>s as sections and remove Sphinx domain logic (#10128)
@ewdurbin: implement multiple .readthedocs.yml files per repo (#10001)

Version 9.10.1

Date:: April 11, 2023

@dependabot[bot]: Bump peter-evans/create-pull-request from 4 to 5 (#10233)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10232)
@agjohnson: Add notes on private repo support in our install docs (#10230)
@stsewd: Migrate more feature checks (#10228)
@stsewd: Analytics API: check if absolute_uri isn’t present (#10227)
@humitos: Docs: minor changes to examples for consistency (#10225)
@benjaoming: Docs: Experiment with canonical url using READTHEDOCS_CANONICAL_URL (#10224)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10215)
@stsewd: Proxito: refactor allowed_user (#10213)
@stsewd: Proxito: Test infinite redirect on non-existing PDFs (#10212)
@stsewd: API V3: support privacy levels on projects and versions (#10210)
@agjohnson: Fix filter positional arguments (#10202)
@benjaoming: Docs: Gather definitions in the same dl on main index page (#10201)
@humitos: Release 9.10.0 (#10200)
@stsewd: Custom domains: hide https option (#10188)
@stsewd: Proxito: refactor project download view (#10178)
@humitos: Build: hardcode the Docker username for now (#10172)
@humitos: Build: expose VCS-related environment variables (#10168)
@agjohnson: Automation rules: model text changes for UI (#10138)
@stsewd: Unify feature check for organization/project (#8920)

Version 9.10.0

Date:: March 28, 2023

@stsewd: Docs: test new search extension release (#10197)
@humitos: Javascript client: search-as-you-type API response (#10196)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10192)
@agjohnson: Filters: several bug fixes and some filter tuning (#10191)
@agjohnson: Make our homepage conditional on the new dashboard (#10189)
@benjaoming: Docs: Changes to main index page (Diátaxis) (#10186)
@stsewd: Proxito: allow serving files under the projects dir (#10180)
@stsewd: Redirects: test redirects with projects prefix (#10179)
@stsewd: Proxito: refactor project download view (#10178)
@stsewd: Update common (#10177)
@benjaoming: Docs: Removal of implicit Intersphinx reference labels to MyST-based documentation (#10176)
@stsewd: Build: fix API call to version.patch() (#10175)
@agjohnson: Replace nvm/asdf with native CircleCI node installation (#10174)
@humitos: Build: hardcode the Docker username for now (#10172)
@ericholscher: Release 9.9.1 (#10169)
@humitos: Build: expose VCS-related environment variables (#10168)
@humitos: Build: export READTHEDOCS_CANONICAL_URL variable (#10166)
@humitos: Project: only support Git as VCS for new projects (#10114)

Version 9.9.1

Date:: March 21, 2023

@humitos: Build: use safe_open for security reasons (#10165)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10163)
@agjohnson: Update some docs for the new dashboard templates (#10161)
@ericholscher: Revert 92a7182af42e26cab01265d2cc06fc7832832689 (#10158)
@humitos: Lint: update common to get the latest linting changes (#10154)
@stsewd: Proxito: don’t check for index.html if the path already ends with /. (#10153)
@ericholscher: Docs: Disable PDF builds for now (#10152)
@stsewd: Put back template_name on proxito 404 view (#10149)
@silopolis: Fix doc_builder exceptions messages typos and spelling (#10147)
@humitos: Release 9.9.0 (#10146)
@stsewd: Proxito: redirect http->https for public domains (#10142)
@benjaoming: Removing non-used requirements file lint.in (#10140)
@humitos: Build: pass PATH environment variable to Docker container (#10133)
@benjaoming: Docs: New how-to sublevels (Diátaxis) (#10131)
@humitos: Hosting: manual integrations via build contract (#10127)
@benjaoming: Docs: emojis in TOC captions, FontAwesome on external links in TOC (Diátaxis) (#10039)

Version 9.9.0

Date:: March 14, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10139)
@ericholscher: Fix typo (#10130)
@humitos: Lint: one step forward through linting our code (#10129)
@humitos: Build: check for _build/html directory and fail if exists (#10126)
@humitos: Telemetry: typo on Celery task (#10125)
@stsewd: Proxito: actually cache robots.txt and sitemap.xml (#10123)
@humitos: Proxito: add another model to cacheops (#10121)
@humitos: Build: pass shell commands directly (build.jobs / build.commands) (#10119)
@humitos: Release 9.8.0 (#10116)
@humitos: Downloadable artifacts: make PDF and ePub opt-in by default (#10115)
@humitos: Build: fail PDF command (latexmk) if exit code != 0 (#10113)
@humitos: pre-commit: move prospector inside pre-commit (#10105)
@stsewd: Proxito: use unresolver in 404 handler (#10074)
@agjohnson: Add beta version of doc diff library for testing (#9546)

Version 9.8.0

Date:: March 07, 2023

@humitos: Downloadable artifacts: make PDF and ePub opt-in by default (#10115)
@humitos: Proxito: cacheops right model (#10111)
@stsewd: Docs: fix term reference (#10110)
@humitos: Development: allow to define the logging level via an env variable (#10109)
@humitos: Celery: cheat job_status view to return finished after 5 polls (#10107)
@humitos: Proxito: use cacheops for 2 more models (#10106)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10104)
@stsewd: Remove unused tests (#10099)
@stsewd: Canonical redirects: check if the project supports custom domains (#10098)
@stsewd: Fix .com tests (#10097)
@stsewd: Fix migration (#10096)
@benjaoming: Docs: Move a reference and remove an empty paranthesis (#10093)
@benjaoming: Docs: Update documentation for search.ignore (#10091)
@benjaoming: Fix intersphinx references to myst-parser (updated in myst-parser 0.19) (#10090)
@stsewd: Update changelog with security fixes (#10088)
@humitos: Analytics: add Plausible to our dashboard (#10087)
@humitos: Docs: add Plausible (#10086)
@stsewd: Proxito: refactor canonical redirects (#10069)
@stsewd: Proxito: simplify caching logic (#10067)
@ericholscher: Add X-Content-Type-Options as a custom domain header (#10062)
@stsewd: Proxito V2 (#10044)
@stsewd: Proxito: adapt unresolver to make it usable for proxito (#10037)
@agjohnson: Add beta version of doc diff library for testing (#9546)
@davidfischer: Support the new Google analytics gtag.js (#7691)

Version 9.7.0

This release contains one security fix. For more information, see:

GHSA-h4cf-8gv8-4chf

Date:: February 28, 2023

@humitos: Celery: delete Telemetry data that’s at most 3 months older (#10079)
@humitos: Celery: consider only PageView from the last 3 months (#10078)
@humitos: Celery: limit archive_builds_task query to last 90 day ago (#10077)
@humitos: Celery: bugfix when deleting pidbox keys (#10076)
@humitos: Proxito: use django-cacheops to cache some querysets (#10075)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10072)
@ericholscher: Docs: Add opengraph (#10066)
@ericholscher: Subscriptions: Set organization name in Stripe (#10064)
@benjaoming: Support delisting of projects (#10060)
@benjaoming: Docs: Fix undeclared labels after refactor + fix root causes (#10059)
@benjaoming: Docs: Replace duplicate information about staff and contributors with a seealso:: (#10056)
@benjaoming: Docs: Use “Sentence case” for titles (#10055)
@ericholscher: Make fancy new build failed email (#10054)
@humitos: Metric: define build latency metric (#10053)
@humitos: Revert “Requirements: unpin newrelic (#10041)” (#10052)
@humitos: Release 9.6.0 (#10050)
@humitos: Metrics: update URL for latency metric (#10048)
@humitos: Build: log usage of old output directory _build/html (#10038)
@benjaoming: Pin django-filter (#2499)

Version 9.6.0

Date:: February 21, 2023

@humitos: Metrics: update URL for latency metric (#10048)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10045)
@humitos: Submodule: update common (#10043)
@humitos: Requirements: unpin newrelic (#10041)
@benjaoming: Docs: emojis in TOC captions, FontAwesome on external links in TOC (Diátaxis) (#10039)
@ericholscher: Merge Diataxis into main! (#10034)
@ericholscher: Docs: Upgrade Sphinx & sphinx_rtd_theme (#10033)
@stsewd: Proxito: use unresolved domain on page redirect view (#10032)
@ericholscher: Docs: Refactor Reproducible Builds page (Diátaxis) (#10030)
@stsewd: Proxito: make use un project from unresolved_domain in some views (#10029)
@ericholscher: Docs: Refactor the build & build customization pages (Diátaxis) (#10028)
@stsewd: Proxito: move “canonicalizing” logic to docs view (#10027)
@benjaoming: Docs: Navigation reorder (Diátaxis) (#10026)
@humitos: APIv2: better build command sanitization (#10025)
@humitos: Embed API: Glossary terms sharing description (Sphinx) (#10024)
@humitos: Builds: ignore cancelling the build at “Uploading” state (#10006)
@humitos: Build: expose READTHEDOCS_VIRTUALENV_PATH variable (#9971)

Version 9.5.0

This release contains one security fix. For more information, see:

GHSA-mp38-vprc-7hf5

Date:: February 13, 2023

@agjohnson: Bump to latest common (#10019)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#10014)
@benjaoming: Docs: Very small text update (#10012)
@sondalex: Fix code block indentation in Jupyter user guide (#10008)
@benjaoming: Docs: Refactor all business features into feature reference + change “privacy level” page (Diátaxis) (#10007)
@humitos: Redis: use django-redis and add password (#10005)
@benjaoming: Docs: Relabel SEO guide as explanation (Diátaxis) (#10004)
@humitos: Celery: cleanup pidbox keys (#10002)
@stsewd: Use new maintained django-cors-headers package (#10000)
@stsewd: Document about cross-site request (#9999)
@stsewd: Analytics API: catch unresolver exceptions (#9998)
@humitos: Requirements: remove django-kombu (#9996)
@humitos: Release 9.4.0 (#9994)
@agjohnson: Fix ordering of filter for most recently built project (#9992)
@benjaoming: Docs: Refactor security logs as reference (Diátaxis) (#9985)
@humitos: Proxito: always check 404/index.hmtml (#9983)
@stsewd: Proxito: save one queryset (#9980)
@humitos: Settings: simplify all the settings removing a whole old layer (dev) (#9978)
@humitos: Build: expose READTHEDOCS_VIRTUALENV_PATH variable (#9971)
@humitos: Build: remove pdflatex support (#9967)
@benjaoming: Docs: Refactor “Environment variables” into 3 articles (Diátaxis) (#9966)
@benjaoming: Docs: Split “Automation rules” into reference and how-to (Diátaxis) (#9953)
@stsewd: Test new readthedocs-sphinx-search release (#9934)
@stsewd: Subscriptions: use getattr for getting related organization (#9932)
@ericholscher: Allow searching & filtering VersionAutomationRuleAdmin (#9917)
@humitos: Build: use environment variable $READTHEDOCS_OUTPUT to define output directory (#9913)

Version 9.4.0

This release contains one security fix. For more information, see:

GHSA-5w8m-r7jm-mhp9

Date:: February 07, 2023

@agjohnson: Fix ordering of filter for most recently built project (#9992)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9987)
@humitos: Proxito: always check 404/index.hmtml (#9983)
@humitos: Docs: remove outdated and complex code and dependencies (#9981)
@stsewd: Proxito: save one queryset (#9980)
@humitos: Common: update common/ submodule (#9979)
@humitos: Settings: simplify all the settings removing a whole old layer (dev) (#9978)
@humitos: Development: use gunicorn for web and proxito (#9977)
@stsewd: Subscriptions: match stripe customer description with org name (#9976)
@stsewd: Update security docs (#9973)
@humitos: Management commands: remove unused ones (#9972)
@humitos: Build: expose READTHEDOCS_VIRTUALENV_PATH variable (#9971)
@stsewd: Remove custom CORS logic (#9945)
@stsewd: Proxito: refactor middleware (#9933)
@benjaoming: Docs: Remove html_theme_path from conf.py (#9923)
@benjaoming: Docs: Relabel Automatic Redirects as “Incoming links: Best practices and redirects” (Diátaxis) (#9896)
@mwtoews: Docs: add warning that pull requests only build HTML and not other formats (#9892)
@ericholscher: Fix status reporting on PRs with the magic exit code (#9807)
@stsewd: Proxito: refactor doc serving (#9726)
@benjaoming: Do not assign html_theme_path (#9654)
@davidfischer: Switch to universal analytics (#3495)

Version 9.3.1

Date:: January 30, 2023

@ericholscher: Add documentation page on Commercial subscriptions (#9963)
@humitos: MkDocs builder: use proper relative path for --site-dir (#9962)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9960)
@humitos: Requirements: reduce complexity (#9956)
@humitos: Build: rclone retries when uploading artifacts (#9954)
@benjaoming: Docs: Relabel badges as feature reference (Diátaxis) (#9951)
@humitos: Build: improve concurent queryset (#9950)
@benjaoming: Docs: Make the GSOC page orphaned (Diátaxis) (#9949)
@humitos: Celery: ignore task results (#9944)
@agjohnson: Translations: a few copy issues and translator requests (#9937)
@humitos: Release 9.3.0 (#9929)
@humitos: Logging: log slugs when at least one of their builds was finished (#9928)
@benjaoming: Docs: Relabel pages to new top-level “Reference/Policies and legal documents” (Diátaxis) (#9916)
@benjaoming: Docs: Move Main Features and Feature Flags to “Reference/Features” (Diátaxis) (#9915)
@benjaoming: Docs: Add new section “How-to / Troubleshooting” and move 2 existing troubleshooting pages (#9914)
@stsewd: Logs: fix exception logging (#9912)
@stsewd: CORS: don’t allow to pass credentials by default (#9904)
@benjaoming: CI: Add option --show-diff-on-failure to pre-commit (#9893)
@stsewd: Build storage: add additional checks for the source dir (#9890)
@stsewd: Build: use rclone for sync (#9842)
@humitos: Git backend: make default_branch to point to VCS’ default branch (#9424)
@stsewd: Subscriptions: avoid double deletion (#9341)
@ericholscher: Make Build models default to triggered (#8031)

Version 9.3.0

Date:: January 24, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9925)
@benjaoming: Docs: FAQ title/question tweak (#9919)
@stsewd: Logs: fix exception logging (#9912)
@stsewd: Add new allauth templates (#9909)
@benjaoming: Docs: Move and update FAQ (Diátaxis) (#9908)
@ericholscher: Release 9.2.0 (#9905)
@stsewd: CORS: don’t allow to pass credentials by default (#9904)
@abe-101: rm mention of docs/requirements.txt from tutorial (#9902)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9898)
@benjaoming: Docs: Relabel Server Side Search (#9897)
@humitos: Build: standardize output directory for artifacts (#9888)
@humitos: Command contact_owners: add support to filter by usernames (#9882)
@benjaoming: Park resolutions to common build problems in FAQ (#9472)
@stsewd: Subscriptions: avoid double deletion (#9341)

Version 9.2.0

This release contains two security fixes. For more information, see our GitHub advisories:

Date:: January 16, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9898)
@benjaoming: UI updates to Connected Accounts (#9891)
@agjohnson: Replace DPA text with link to our presigned DPA (#9883)
@humitos: Release 9.1.3 (#9881)
@sethfischer: Docs: correct Python console block type (#9880)
@sethfischer: Docs: update build customization Poetry example (#9879)
@stsewd: Embedded JS: Conditionally inject jQuery (#9861)
@humitos: EmbedAPI: decode filepath before open them from S3 storage (#9860)
@benjaoming: Docs: Additions to style guide - placeholders, seealso::, Diátaxis and new word list entry (#9840)
@benjaoming: Docs: Relabel and move explanation and how-tos around OAuth (Diátaxis) (#9834)
@benjaoming: Docs: Split Custom Domains as Explanation and How-to Guide (Diátaxis) (#9676)

Version 9.1.3

Date:: January 10, 2023

@stsewd: Explicitly set JQuery globals on main site (#9877)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9872)
@benjaoming: Move reference labels outside of tabs (#9866)
@stsewd: Embedded JS: Conditionally inject jQuery (#9861)
@humitos: EmbedAPI: decode filepath before open them from S3 storage (#9860)
@humitos: Release 9.1.2 (#9858)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9853)
@ericholscher: Remove intercom from our DPA list (#9846)
@agjohnson: API: add project name/slug filters (#9843)
@benjaoming: Docs: Relabel Organizations as Explanation (Diátaxis) (#9836)
@ericholscher: Docs: Add subset of tests to testing docs (#9817)
@ericholscher: Docs: Refactor downloadable docs (#9768)

Version 9.1.2

Date:: January 03, 2023

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9845)
@agjohnson: Update common submodule (#9841)
@humitos: Docs: update versions on config file page (#9838)
@stsewd: Invitations: fix model name (object_type) (#9837)
@benjaoming: Docs: Relabel Organizations as Explanation (Diátaxis) (#9836)
@benjaoming: Docs: Relabel “Single version documentation” documentation from feature to explanation (Diátaxis) (#9835)
@benjaoming: Docs: Relabel the “Science” page as Explanation (#9832)
@humitos: Build details page: normalize/trim command paths (second attempt) (#9831)
@stsewd: Config file: update JSON schema (#9830)
@benjaoming: Label for subproject select renamed “Child” => “Subproject” + help text added (#9829)
@stsewd: Search API V3: fix view description (#9828)
@stsewd: API V2: test that command is actually saved (#9827)
@benjaoming: Removes fetching of main branch (#9826)
@humitos: Test: path is trimmed when returned by the API (#9824)
@humitos: Release 9.1.1 (#9823)
@humitos: Dependencies: use backtracking pip’s resolver (#9821)
@benjaoming: Docs: Split Subprojects in Explanation and How-to (Diátaxis) (#9785)
@benjaoming: Docs: Split Traffic Analytics to a How-to guide and a Feature entry (Diátaxis) (#9677)

Version 9.1.1

Date:: December 20, 2022

@humitos: Dependencies: use backtracking pip’s resolver (#9821)
@benjaoming: Use sphinx-rtd-theme 1.2.0rc1 (#9818)
@ericholscher: Add subset of tests to testing docs (#9817)
@humitos: Build details page: normalize/trim command paths (#9815)
@DelazJ: Add link to the build notifications guide (#9814)
@ericholscher: Break documentation style guide out into its own file (#9813)
@ericholscher: Disable Sphinx mimetype errors on epub (#9812)
@ericholscher: Docs: Update security log wording (#9811)
@humitos: Docs: configure linkcheck (#9810)
@benjaoming: Docs: Fix build 3 warnings (#9809)
@benjaoming: Fix silent, then loud failure after Tox 4 upgrade (#9803)
@ericholscher: Docs: Split SSO docs into HowTo/Explanation (Diátaxis) (#9801)
@juantocamidokura: Docs: Remove outdated and misleading Poetry guide (#9794)
@benjaoming: CI builds: Checkout main branch in a robust way (#9793)
@ericholscher: Release 9.1.0 (#9792)
@benjaoming: Docs: Relabel Localization as Explanation (Diátaxis) (#9790)
@benjaoming: Fix Circle CI builds: Tox 4 compatibility, add external commands to allowlist (#9789)
@benjaoming: Do not build documentation in Circle CI, Read the Docs handles that :100: (#9788)
@benjaoming: Docs: Move “Choosing between our two platforms” to Explanation (Diátaxis) (#9784)
@benjaoming: Docs: Change “downloadable” to “offline” (#9782)
@benjaoming: Adds missing translation strings (#9770)
@humitos: Admin: install debug_toolbar (#9753)
@benjaoming: Docs: Split up Pull Request Builds into a how-to guide and reference (Diátaxis) (#9679)
@benjaoming: Docs: Split Custom Domains as Explanation and How-to Guide (Diátaxis) (#9676)
@benjaoming: Docs: Split and relabel VCS integration as explanation and how-to (Diátaxis) (#9675)

Version 9.1.0

This release contains an important security fix. See more information on the GitHub advisory.

Date:: December 08, 2022

@benjaoming: Docs: Move “Choosing between our two platforms” to Explanation (Diátaxis) (#9784)
@benjaoming: Abandoned Projects policy: Relax reachability requirement (#9783)
@benjaoming: Docs: Change “downloadable” to “offline” (#9782)
@humitos: Docs: fix raw directive (#9778)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9775)
@humitos: Settings: define default MailerLite setting (#9769)
@ericholscher: Refactor downloadable docs (#9768)
@humitos: Docs: fix minor issues (#9765)
@humitos: Docs: validate Mastodon link (#9764)

Version 9.0.0

This version upgrades our Search API experience to a v3.

Date:: November 28, 2022

@Jean-Maupas: A few text updates (#9761)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9760)
@benjaoming: Docs: 4 diátaxis categories at the top of the navigation sidebar (Diátaxis iteration 0) (#9758)
@ericholscher: Be more explicit where go to in VCS intstructions (#9757)
@benjaoming: Docs: Adding a pattern for reusing “Only on Read the Docs for Business” admonition (Diátaxis refactor) (#9754)
@stsewd: Subscriptions: attach stripe subscription to organizations (#9751)
@stsewd: Search: fix parsing of parameters inside sphinx domains (#9750)
@eltociear: Fix typo in private.py (#9744)
@browniebroke: Docs: update instructions to install deps with Poetry (#9743)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9742)
@humitos: Telemetry: include all the PyPI packages (#9737)
@humitos: Docs: cancel PR builds if there is no documentation changes (#9734)
@humitos: Docs: add an example for custom domain input (#9733)
@humitos: Release 8.9.0 (#9732)
@ericholscher: Add an initial policy for delisting unmaintained projects (#9731)
@saadmk11: Admin: Make VersionInline Read-only (#9697)
@stsewd: Search: API V3 (#9625)
@stsewd: Audit log: log invitations (#9607)
@stsewd: Design doc: new search API (#9533)
@humitos: Docs: poetry example on build.jobs section (#9445)

Version 8.9.0

Date:: November 15, 2022

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9728)
@stsewd: Fix tests (#9725)
@ericholscher: Release 8.8.1 (#9724)
@stsewd: Update security policy (#9723)
@humitos: Docs: refactor “skipping a build” section (#9717)
@stsewd: Proxito: don’t depend on attributes injected in the request (#9711)
@stsewd: Unresolver: support external versions for single version projects (#9709)
@stsewd: Domains: add expired queryset (#9667)
@humitos: Build: skip build based on commands’ exit codes (#9649)
@ericholscher: Change mailing list subscription to when the user validates their email (#9384)

Version 8.8.1

This release contains a security fix, which is the most important part of the update.

Date:: November 09, 2022

Security fix: https://github.com/readthedocs/readthedocs.org/security/advisories/GHSA-98pf-gfh3-x3mp
@stsewd: Unresolver: support external versions for single version projects (#9709)

Version 8.8.0

Date:: November 08, 2022

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9714)
@humitos: Build: bump readthedocs-sphinx-ext to <2.3 (#9707)
@benjaoming: Bump to sphinx-rtd-theme to 1.1.0 (#9701)
@humitos: GHA: only run the preview links action on docs/ path (#9696)
@humitos: Telemetry: not collect Sphinx data if there is no conf.py (#9695)
@stsewd: Static files: don’t 500 on invalid paths (#9694)
@stsewd: Subscriptions: don’t remove stripe id on canceled subscriptions (#9693)
@humitos: Build tools: upgrade all versions (#9692)
@ericholscher: Release 8.7.1 (#9691)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9688)
@benjaoming: Docs: Split up Build Notifications into feature/reference and how-to (Diátaxis) (#9686)
@dojutsu-user: Run blacken-docs precommit hook on all files (#9672)
@benjaoming: Proposal for sphinxcontrib-jquery (#9665)
@stsewd: Subscriptions: use djstripe events to mail owners (#9661)
@benjaoming: Docs: Use current year instead of hard-coded 2010 (#9660)
@SyedMa3: API v3: added support for tags in API (#9513)

Version 8.7.1

Date:: October 24, 2022

@benjaoming: Docs: Comment out the science contact form (#9674)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9663)
@humitos: Template: fix build details page link (#9662)
@benjaoming: Docs: Use current year instead of hard-coded 2010 (#9660)
@humitos: Clean up some old code that’s not used (#9659)
@benjaoming: Adds more basic info to the default 404 page (#9656)
@humitos: Release 8.7.0 (#9655)
@stsewd: Subscriptions: Use djstripe event handlers (#9651)
@stsewd: Search: use path for API URL (#9646)
@humitos: Settings: enable django-debug-toolbar when Django Admin is enabled (#9641)
@humitos: Telemetry: track Sphinx extensions and html_theme variables (#9639)
@humitos: Run django-upgrade (#9628)
@evildmp: Docs: Made some small changes to the MyST migration how-to (#9620)
@dojutsu-user: Add admin functions for wiping a version (#5140)

Version 8.7.0

Date:: October 11, 2022

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9648)
@humitos: Settings: enable django-debug-toolbar when Django Admin is enabled (#9641)
@stsewd: Subscriptions: use stripe price instead of relying on plan object (#9640)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9636)
@humitos: Query: minor improvement (#9634)
@ericholscher: Release 8.6.0 (#9630)
@humitos: Run django-upgrade (#9628)
@stsewd: Search: refactor serializer’s context (#9624)
@benjaoming: Docs: Re-scope Intersphinx article as a how-to (#9622)
@evildmp: Made some small changes to the MyST migration how-to (#9620)
@stsewd: Search: move api.py into a module (#9616)
@humitos: Build: remove DEDUPLICATE_BUILDS feature (#9591)
@stsewd: Email: render template before sending it to the task (#9538)

Version 8.6.0

Date:: September 28, 2022

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9621)
@evildmp: Made some small changes to the MyST migration how-to (#9620)
@boahc077: ci: add minimum GitHub at the workflow level for pip-tools.yaml (#9617)
@stsewd: Search: refactor API view (#9613)
@sashashura: GitHub Workflows security hardening (#9609)
@stsewd: Redirects: test with/without organizations (#9605)
@humitos: Builds: concurrency small optimization (#9602)
@uvidyadharan: Update intersphinx.rst (#9601)
@ericholscher: Release 8.5.0 (#9600)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9596)
@stsewd: OAuth: save refresh token (#9594)
@stsewd: Redirects: allow update (#9593)
@stsewd: Unresolver: strict validation for external versions and other fixes (#9534)
@stsewd: New unresolver implementation (#9500)
@stsewd: API v3: fix organizations permissions (#8771)

Version 8.5.0

Date:: September 12, 2022

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9596)
@stsewd: OAuth: save refresh token (#9594)
@humitos: OAuth: add logging for imported GitHub RemoteRepository (#9590)
@humitos: Telemetry: lowercase JSON keys (#9587)
@stsewd: Embedded js: fix no-sphinx docs (#9586)
@humitos: Release 8.4.3 (#9584)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9583)
@stsewd: Invitations: delete related invitations when deleting an object (#9582)
@stsewd: New unresolver implementation (#9500)

Version 8.4.3

Date:: September 06, 2022

@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9583)
@stsewd: Invitations: delete related invitations when deleting an object (#9582)
@humitos: Docs: improve “Badges” page (#9580)
@stsewd: Use utility function domReady instead of JQuery’s .ready (#9579)
@humitos: Development: disable NGINX logs (#9569)
@humitos: Logging: log time spent to upload build artifacts (#9568)
@humitos: Docs: recommend using pip instead of setuptools (#9567)
@stsewd: Embed API: strip leading / before joining path (#9565)
@stsewd: Embed API: fix CORS check (#9564)
@humitos: Build: upgrade commonmark to 0.9.1 (#9563)
@humitos: Templates: minor typo (#9560)
@stsewd: Proxito: unskip test (#9559)
@ericholscher: Release 8.4.2 (#9558)
@ericholscher: Proxito redirects: pass full_path instead of re-creating it. (#9557)
@stsewd: Embed js: use fetch API for footer (#9551)
@stsewd: Subscriptions: use stripe subscriptions to show details (#9550)
@humitos: Build: cancel old builds (#9549)
@benjaoming: Docs: HTML form for getting in touch with Read the Docs for Science (#9543)
@humitos: Dependencies: pin deploy dependencies (#9537)
@humitos: Code comment (#9518)
@stsewd: Avoid jquery in rtd data (#9493)
@stsewd: Use djstripe models for organization subscriptions (#9486)
@stsewd: Ask for confirmation when adding a user to a project/organization/team (#9440)
@stsewd: Design doc: Better handling of docs URLs (#9425)
@stsewd: Security logs: delete old user security logs (#8620)

Version 8.4.2

Date:: August 29, 2022

@ericholscher: Proxito redirects: pass full_path instead of re-creating it. (#9557)
@humitos: Build: cancel old builds (#9549)
@stsewd: Embedded js: update docstring (#9547)
@benjaoming: Docs: HTML form for getting in touch with Read the Docs for Science (#9543)
@stsewd: Unresolver: port changes from #9540 (#9542)
@stsewd: Domains: test tasks with organizations (#9541)
@stsewd: Proxito: set logging to debug (#9540)
@humitos: Dependencies: pin deploy dependencies (#9537)
@humitos: Release 8.4.1 (#9536)
@humitos: Dependencies: pin django-structlog to 2.2.1 (#9535)
@humitos: Code comment (#9518)
@stsewd: Embedded js: remove more dependency on jquery (#9515)
@humitos: Telemetry: collect user’s requirements (#9514)
@stsewd: Embedded js: remove some dependency from jquery (#9508)
@stsewd: New unresolver implementation (#9500)
@stsewd: Use djstripe models for organization subscriptions (#9486)
@benjaoming: Park resolutions to common build problems in FAQ (#9472)

Version 8.4.1

Date:: August 23, 2022

@humitos: Dependencies: pin django-structlog to 2.2.1 (#9535)
@xk999: Update Transifex link (#9531)
@dependabot[bot]: Bump actions/setup-python from 3 to 4 (#9529)
@github-actions[bot]: Dependencies: all packages updated via pip-tools (#9528)
@humitos: Telemetry: collect user’s requirements (#9514)
@stsewd: Teams: don’t send email notification when users adds themselves to a team (#9511)
@humitos: Preview: escape characters (#9509)
@benjaoming: Removes rstcheck (#9505)
@humitos: Release 8.4.0 (#9504)
@benjaoming: Docs: sphinxcontrib-video was added incorrectly (#9501)
@agjohnson: Fix typo in build concurrency logging (#9499)
@stsewd: Update template from documentation preview (#9495)
@humitos: Dependencies: use pip-tools for all our files (#9480)
@humitos: Dependencies: use GitHub Action + pip-tools (#9479)
@stsewd: Proxito: separate project slug extraction from request manipulation (#9462)
@stsewd: Ask for confirmation when adding a user to a project/organization/team (#9440)
@stsewd: Custom domains: track validation process (#9428)

Version 8.4.0

Date:: August 16, 2022

@benjaoming: Docs: sphinxcontrib-video was added incorrectly (#9501)
@agjohnson: Fix typo in build concurrency logging (#9499)
@stsewd: Embedded js: fix flyout click event (#9498)
@stsewd: Custom urlconf: support serving static files (#9496)
@stsewd: Avoid jquery in rtd data (#9493)
@humitos: Preview: add links to dev documentation (#9491)
@humitos: Use Read the Docs action v1 (#9487)
@humitos: Release 8.3.7 (#9484)
@stsewd: Disable sphinx domains (#9483)
@stsewd: Sphinx domain: change type of ID field (#9482)
@humitos: Build: unpin Pillow for unsupported Python versions (#9473)
@benjaoming: Docs: Read the Docs for Science - new alternative with sphinx-design (#9460)
@stsewd: Ask for confirmation when adding a user to a project/organization/team (#9440)

Version 8.3.7

Date:: August 09, 2022

@stsewd: Sphinx domain: change type of ID field (#9482)
@humitos: Build: unpin Pillow for unsupported Python versions (#9473)
@humitos: Release 8.3.6 (#9465)
@stsewd: Redirects: check only for hostname and path for infinite redirects (#9463)
@benjaoming: Fix missing indentation on reStructuredText badge code (#9404)
@stsewd: Embed JS: fix incompatibilities with sphinx 6.x (jquery removal) (#9359)

Version 8.3.6

Date:: August 02, 2022

@stsewd: Build: use correct build environment for build.commands (#9454)
@benjaoming: Docs: Fixes warnings and other noisy build messages (#9453)
@ericholscher: Release 8.3.5 (#9452)
@humitos: GitHub Action: add link to Pull Request preview (#9450)
@humitos: OAuth: add logging for GitHub RemoteRepository (#9449)
@benjaoming: Docs: Adds Jupyter Book to examples table (#9446)
@humitos: Docs: poetry example on build.jobs section (#9445)

Version 8.3.5

Date:: July 25, 2022

@humitos: GitHub Action: add link to Pull Request preview (#9450)
@humitos: OAuth: add logging for GitHub RemoteRepository (#9449)
@benjaoming: Docs: Adds Jupyter Book to examples table (#9446)
@humitos: Docs: poetry example on build.jobs section (#9445)
@agjohnson: Update env var docs (#9443)
@ericholscher: Update dev domain to devthedocs.org (#9442)
@humitos: Docs: mention docsify on “Build customization” (#9439)
@humitos: Release 8.3.4 (#9436)
@stsewd: Custom domains: don’t allow IPs (#9429)
@stsewd: Audit logs: truncate browser (#9417)

Version 8.3.4

Date:: July 19, 2022

@stsewd: Fix docs (#9432)
@stsewd: Build: check for self.data.version being None (#9430)
@ericholscher: Release 8.3.3 (#9427)
@stsewd: Redirects: merge query params from the redirect and original request (#9420)
@stsewd: Audit logs: truncate browser (#9417)

Version 8.3.3

Date:: July 12, 2022

@davidfischer: Stickybox ad fix (#9421)
@humitos: Logging: add extra log info for oauth (#9416)
@humitos: OAuth: unify the exception used for the user message (#9415)
@humitos: Docs: improve the flyout page to include a full example (#9413)
@humitos: OAuth: resync RemoteRepository weekly for active users (#9410)
@humitos: OAuth: re-sync RemoteRepository on login (#9409)
@stsewd: Analytics: make sure there is only one record with version=None (#9408)
@agjohnson: Add frontend team codeowners rules (#9407)
@humitos: Telemetry: delete old BuildData models (#9403)
@humitos: Sessions: do not save on each request (#9402)
@humitos: Release 8.3.2 (#9400)
@naveensrinivasan: chore: Included githubactions in the dependabot config (#9396)
@stsewd: Build: refactor TaskData (#9389)
@benjaoming: Docs: Add an examples section (#9371)

Version 8.3.2

Date:: July 05, 2022

@neilnaveen: chore: Set permissions for GitHub actions (#9394)
@humitos: Logging: do not log the token itself (#9393)
@stsewd: Test explicitly with/out organizations (#9391)
@stsewd: Telemetry: skip listing conda packages on non-conda envs (#9390)
@stsewd: Enable djstripe again (#9385)
@ericholscher: UX: Improve DUPLICATED_RESERVED_VERSIONS error (#9383)
@ericholscher: Release 8.3.1 (#9379)
@humitos: Docs: remove old feature flags (#9377)
@ericholscher: Properly log build exceptions in Celery (#9375)
@humitos: Middleware: use regular HttpResponse and log the suspicious operation (#9366)
@ericholscher: Add an explicit flyout placement option (#9357)
@stsewd: PR previews: Warn users when enabling the feature on incompatible projects (#9291)

Version 8.3.1

Date:: June 27, 2022

@ericholscher: Properly log build exceptions in Celery (#9375)
@humitos: Docs: remove old FAQ entry (#9374)
@humitos: CSP header: enforce mode (#9373)
@humitos: Development: default value for environment variable (#9370)
@humitos: Middleware: use regular HttpResponse and log the suspicious operation (#9366)
@humitos: Development: remove silent and use long attribute name (#9363)
@ericholscher: Fix glossary ordering (#9362)
@benjaoming: Do not list feature overview twice (#9361)
@agjohnson: Release 8.3.0 (#9358)
@ericholscher: Add an explicit flyout placement option (#9357)
@humitos: Development: allow to pass --ngrok when starting up (#9353)
@humitos: Development: avoid path collision when running multiple builders (#9352)
@humitos: Security: avoid requests with NULL characters (0x00) on GET (#9350)
@humitos: Logging: reduce log verbosity (#9348)
@humitos: Build: handle 422 response on send build status (#9347)
@humitos: Build: truncate command output (#9346)
@benjaoming: Updates and fixes to Development Install guide (#9319)
@agjohnson: Add DMCA takedown request for project dicom-standard (#9311)

Version 8.3.0

Date:: June 20, 2022

@humitos: Security: avoid requests with NULL characters (0x00) on GET (#9350)
@humitos: Logging: reduce log verbosity (#9348)
@humitos: Build: truncate command output (#9346)
@stsewd: Update common (#9345)
@stsewd: Subscriptions: log subscription id when canceling (#9340)
@stsewd: Search: support section titles inside header tags (#9339)
@humitos: Local development: use nodemon to watch files instead of watchmedo (#9338)
@humitos: EmbedAPI: clean images (src) properly from inside a tooltip (#9337)
@humitos: Development: update common/ submodule (#9336)
@stsewd: Gold: log if the subscription has more than one item (#9334)
@humitos: EmbedAPI: handle special case for Sphinx manual references (#9333)
@benjaoming: Add mc client to web container (#9331)
@humitos: Translations: migrate tx/config to new client’s version format (#9327)
@stsewd: Search: index generic doctype (#9322)
@benjaoming: Docs: Improve scoping of two potentially overlapping Triage sections (#9302)

Version 8.2.0

Date:: June 14, 2022

@ericholscher: Docs: Small edits to add a couple keywords and clarify headings (#9329)
@humitos: Translations: integrate Transifex into our Docker tasks (#9326)
@humitos: EmbedAPIv3: make usage of CDN (#9321)
@stsewd: Subscriptions: handle subscriptions with multiple products/plans/items (#9320)
@benjaoming: Update the team page (#9309)
@stsewd: Stripe: use new api version (#9308)
@humitos: Build: avoid overwriting a variable (#9305)
@humitos: Integrations: handle ping event on GitHub (#9303)
@ericholscher: Release 8.1.2 (#9300)
@ericholscher: Fix Docs CI (#9299)
@stsewd: Tests: test build views with organizations (#9298)
@agjohnson: Update mentions of our roadmap to be current (#9293)
@stsewd: lsremote: set max split when parsing remotes (#9292)
@humitos: Tests: make tests-embedapi require regular tests first (#9289)
@ericholscher: Truncate output that we log from commands to 10 lines (#9286)
@stsewd: Docs: update custom domains docs (#9266)
@stsewd: Requirements: update django-allauth (#9249)

Version 8.1.2

Date:: June 06, 2022

@ericholscher: Fix Docs CI (#9299)
@agjohnson: Update mentions of our roadmap to be current (#9293)
@stsewd: lsremote: set max split when parsing remotes (#9292)
@humitos: Tests: make tests-embedapi require regular tests first (#9289)
@agjohnson: Update 8.1.1 changelog with hotfixes (#9288)
@stsewd: Cancel build: get build from the current project (#9287)
@stsewd: Python: increase 3.11 beta version (#9284)
@stsewd: Disable djstripe (#9282)
@stsewd: Python: use 3.11.0b2 (#9278)
@saadmk11: Remote repository: Add user admin action for syncing remote repositories (#9272)
@stsewd: Requirements: update django-allauth (#9249)
@humitos: Build: implementation of build.commands (#9150)

Version 8.1.1

Date:: Jun 1, 2022

@stsewd: Cancel build: get build from the current project (#9287)
@stsewd: Disable djstripe (#9282)
@stsewd: Python: increase 3.11 beta version (#9284)
@stsewd: Python: use 3.11.0b2 (#9278)
@yarons: Typo fix (#9271)
@stsewd: Update json schema (#9270)
@stsewd: Build tools: update versions (#9268)
@stsewd: Fix docs (#9264)
@stsewd: Update commmon (#9248)
@pyup-bot: pyup: Scheduled weekly dependency update for week 18 (#9157)

Version 8.1.0

Date:: May 24, 2022

@humitos: Assets: update package-lock.json with newer versions (#9262)
@agjohnson: Improve contributing dev doc (#9260)
@agjohnson: Update translations, pull from Transifex (#9259)
@humitos: Build: solve problem with sanitized output (#9257)
@humitos: Docs: improve “Environment Variables” page (#9256)
@humitos: Logging: reduce noise on working features (#9255)
@humitos: Docs: jsdoc example using build.jobs and build.tools (#9241)
@stsewd: Docker environment: check for None on stdout/stderr response (#9238)
@stsewd: Proxied static files: use its own storage class (#9237)
@humitos: Docs: gitlab integration update (#9236)
@ericholscher: Release 8.0.2 (#9234)
@stsewd: Fix tests on .com (#9233)
@humitos: Development: only pull the images required (#9182)
@stsewd: Proxito: serve static files from the same domain as the docs (#9168)
@humitos: Build: add a new “Cancelled” final state (#9145)
@stsewd: Collect build data (#9113)
@humitos: Project: use RemoteRepository to define default_branch (#8988)
@humitos: Design doc: forward path to a future builder (#8190)

Version 8.0.2

Date:: May 16, 2022

@stsewd: Fix tests on .com (#9233)
@agjohnson: Disable codecov annotations (#9186)
@choldgraf: Note sub-folders with a single domain. (#9185)
@stsewd: BuildCommand: add option to merge or not stderr with stdout (#9184)
@agjohnson: Fix bumpver issue (#9181)
@agjohnson: Release 8.0.1 (#9180)
@agjohnson: Spruce up docs on pull request builds (#9177)
@ericholscher: Fix RTD branding in the code (#9175)
@agjohnson: Fix copy issues on model fields (#9170)
@stsewd: Proxito: serve static files from the same domain as the docs (#9168)
@stsewd: User: delete organizations where the user is the last owner (#9164)
@ericholscher: Add a basic djstripe integration (#9087)
@stsewd: Custom domains: don’t allow adding a custom domain on subprojects (#8953)

Version 8.0.1

Date:: May 09, 2022

@ericholscher: Fix RTD branding in the code (#9175)
@ericholscher: Remove our old out-dated architecture diagram (#9169)
@humitos: Docs: mention ubuntu-22.04 as a valid option (#9166)
@ericholscher: Initial test of adding plan to CDN (#9163)
@ericholscher: Fix links in docs from the build page refactor (#9162)
@stsewd: Analytics: skip requests from bots on 404s (#9161)
@ericholscher: Note build.jobs required other keys (#9160)
@ericholscher: Add docs showing pip-tools usage on dependencies (#9158)
@ericholscher: Expierment with pip-tools for our docs.txt requirements (#9124)
@ericholscher: Add a basic djstripe integration (#9087)

Version 8.0.0

Date:: May 03, 2022

Note

We are upgrading to Ubuntu 22.04 LTS and also to Python 3.10.

Projects using Mamba with the old feature flag, and now removed, CONDA_USES_MAMBA, have to update their .readthedocs.yaml file to use build.tools.python: mambaforge-4.10 to continue using Mamba to create their environment. See more about build.tools.python at https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python

@stsewd: Search: fix parsing of footnotes (#9154)
@humitos: Mamba: remove CONDA_USES_MAMBA feature flag (#9153)
@ericholscher: Remove prebuild step so docs keep working (#9143)
@stsewd: lsremote: fix incorrect kwarg (#9142)
@stsewd: Rebase of #9136 (#9141)
@ericholscher: Release 7.6.2 (#9140)
@humitos: Docs: feature documentation for build.jobs (#9138)
@stsewd: Builds: fix retry (#9133)
@humitos: External versions: save state (open / closed) (#9128)
@stsewd: Resolver: allow to ignore custom domains (#9089)
@humitos: Update project to use Ubuntu 22.04 LTS (#9010)
@OriolAbril: add note on setting locale_dirs (#8972)
@stsewd: Design doc: collect data about builds (#8124)

Version 7.6.2

Date:: April 25, 2022

@stsewd: Builds: fix retry (#9133)
@stsewd: Build: log more data (#9132)
@stsewd: Analytics: add feature flag to skip tracking 404s (#9131)
@humitos: External versions: save state (open / closed) (#9128)
@stsewd: Build: log more attributes (#9127)
@stsewd: git: respect SKIP_SYNC_* flags when using lsremote (#9125)
@agjohnson: Release 7.6.1 (#9123)
@pyup-bot: pyup: Scheduled weekly dependency update for week 16 (#9121)
@stsewd: Fix docs (#9120)
@thomasrockhu-codecov: ci: add informational Codecov status checks (#9119)
@stsewd: Build: use gvisor for projects using build.jobs (#9114)
@humitos: Docs: call linkcheck Sphinx builder for our docs (#9091)

Version 7.6.1

Date:: April 19, 2022

@humitos: Logging: reduce verbosity (#9107)
@stsewd: Analytics: Don’t use full_path in get_or_create (#9099)
@humitos: Build: do not upload build.tool to production S3 (#9098)
@ericholscher: Cleanup Redirects docs (#9095)

Version 7.6.0

Date:: April 12, 2022

@stsewd: Celery: workaround fix for bug on retrying builds (#9096)
@stsewd: CI: use circle api v2 to trigger builds (#9094)
@ericholscher: Try to fix .com tests (#9092)
@humitos: Notification: don’t send it on build retry (#9086)
@stsewd: Docs: add notes about gvisor on Fedora (#9085)
@stsewd: Update common (#9084)
@humitos: Build: bugfix RepositoryError.CLONE_ERROR message (#9083)
@stsewd: Redirects: remove unused code (#9080)
@stsewd: Proxito: only check for index files if there is a version (#9079)
@stsewd: Adapt scripts and docs to make use of the new github personal tokens (#9078)
@stsewd: Redirects: avoid using re.sub (#9077)
@stsewd: Proxito: fix URL parsing (#9075)
@ericholscher: Release 7.5.1 (#9074)
@pyup-bot: pyup: Scheduled weekly dependency update for week 14 (#9073)
@humitos: Github: use probot auto-assign bot (#9069)
@agjohnson: Add gVisor runtime option for build containers (#9066)
@humitos: Docs: build.jobs reference documentation (#9056)
@humitos: Proxito: do not serve non-existent versions (#9048)
@stsewd: Traffic analytics: track 404s (#9027)
@humitos: SyncRepositoryTask: rate limit to 1 per minute per project (#9021)
@stsewd: Sync versions: filter by type on update (#9019)
@humitos: Build: implement build.jobs config file key (#9016)

Version 7.5.1

Date:: April 04, 2022

@humitos: Github: use probot auto-assign bot (#9069)
@stsewd: Docs: update sphinx-tabs (#9061)
@stsewd: Docs: use sphinx-multiproject (#9057)
@humitos: Docs: build.jobs reference documentation (#9056)
@humitos: Build: use same hack for VCS and build environments (#9055)
@ericholscher: Fix jinja2 on embed tests (#9053)
@jsquyres: director.py: restore READTHEDOCS_VERSION_[TYPE|NAME] (#9052)
@ericholscher: Fix tests around jinja2 (#9050)
@humitos: Build: do not send VCS build status on specific exceptions (#9049)
@humitos: Proxito: do not serve non-existent versions (#9048)
@agjohnson: Release 7.5.0 (#9047)
@humitos: Build: Mercurial (hg) compatibility with old versions (#9042)
@eyllanesc: Fixes link (#9041)
@ericholscher: Fix jinja2 pinning on Sphinx 1.8 feature flagged projects (#9036)
@humitos: Copyright date (#9022)
@humitos: SyncRepositoryTask: rate limit to 1 per minute per project (#9021)
@humitos: Build: use same build environment for setup and build (#9018)
@stsewd: Git: fix annotated tags on lsremote (#9017)
@humitos: Build: implement build.jobs config file key (#9016)
@abravalheri: Improve displayed version name when building from PR (#8237)

Version 7.5.0

Date:: March 28, 2022

@humitos: Build: Mercurial (hg) compatibility with old versions (#9042)
@eyllanesc: Fixes link (#9041)
@ericholscher: Fix jinja2 pinning on Sphinx 1.8 feature flagged projects (#9036)
@agjohnson: Add bumpver configuration (#9029)
@davidfischer: Update the community ads application link (#9028)
@ericholscher: Don’t use master branch explicitly in requirements (#9025)
@humitos: Copyright date (#9022)
@humitos: GitHub OAuth: use bigger pages to make fewer requests (#9020)
@humitos: Build: use same build environment for setup and build (#9018)
@stsewd: Git: fix annotated tags on lsremote (#9017)
@humitos: Build: log when a build is reset (#9015)
@pyup-bot: pyup: Scheduled weekly dependency update for week 11 (#9012)
@humitos: Build: allow users to use Ubuntu 22.04 LTS (#9009)
@humitos: Build: proof of concept for pre/post build commands (build.jobs) (#9002)

Version 7.4.2

Date:: March 14, 2022

@stsewd: CI: fix codecov again (#9007)
@stsewd: CI: fix codecov (#9006)
@agjohnson: Release 7.4.1 (#9004)
@pyup-bot: pyup: Scheduled weekly dependency update for week 10 (#9003)
@humitos: Upgrade common submodule (#9001)
@humitos: Build: RepositoryError message (#8999)
@stsewd: Search: fix integration with latest sphinx (#8994)
@humitos: API: validate RemoteRepository when creating a Project (#8983)
@stsewd: Tests: fix mock.patch order (#8909)
@humitos: Celery: remove queue priority (#8848)
@dogukanteber: Use django-storages’ manifest files class instead of the overriden class (#8781)
@abravalheri: Improve displayed version name when building from PR (#8237)

Version 7.4.1

Date:: March 07, 2022

@humitos: Upgrade common submodule (#9001)
@humitos: Build: RepositoryError message (#8999)
@humitos: Requirements: remove django-permissions-policy (#8987)
@stsewd: Archive builds: avoid filtering by commands__isnull (#8986)
@humitos: Build: cancel error message (#8984)
@humitos: API: validate RemoteRepository when creating a Project (#8983)
@humitos: Celery: trigger archive_builds frequently with a lower limit (#8981)
@pyup-bot: pyup: Scheduled weekly dependency update for week 09 (#8977)
@stsewd: MkDocs: allow None on extra_css/extra_javascript (#8976)
@stsewd: CDN: avoid cache tags collision (#8969)
@stsewd: Docs: warn about custom domains on subprojects (#8945)
@humitos: Code style: format the code using darker (#8875)
@dogukanteber: Use django-storages’ manifest files class instead of the overriden class (#8781)
@nienn: Docs: Add links to documentation on creating custom classes (#8466)
@stsewd: Integrations: allow to pass more data about external versions (#7692)

Version 7.4.0

Date:: March 01, 2022

@stsewd: Fix typo on exception (#8975)
@humitos: Celery: increase timeout limit for sync_remote_repositories task (#8974)
@agjohnson: Fix a couple integration admin bugs (#8964)
@humitos: Build: allow NULL when updating the config (#8962)
@agjohnson: Release 7.3.0 (#8957)
@pyup-bot: pyup: Scheduled weekly dependency update for week 08 (#8954)
@humitos: Celery: upgrade to latest version (#8952)
@humitos: Requirements: upgrade gitpython because of security issue (#8950)
@humitos: Test: remove verbose warnings (#8949)
@agjohnson: Pin storages with boto3 (#8947)
@stsewd: Optimize archive_builds task (#8944)
@humitos: Build: reset build error before start building (#8943)
@humitos: Build: comment record=False usage (#8939)
@humitos: Django3: use new JSON fields instead of old TextFields (#8934)
@humitos: Build: ability to cancel a running build from dashboard (#8850)
@humitos: Celery: remove queue priority (#8848)

Version 7.3.0

Date:: February 21, 2022

@humitos: Requirements: upgrade gitpython because of security issue (#8950)
@humitos: Test: remove verbose warnings (#8949)
@agjohnson: Pin storages with boto3 (#8947)
@stsewd: Fix codeowners (#8946)
@stsewd: Optimize archive_builds task (#8944)
@humitos: Build: reset build error before start building (#8943)
@humitos: Build: comment record=False usage (#8939)
@humitos: Django3: use new JSON fields instead of old TextFields (#8934)
@agjohnson: Tune build config migration (#8931)
@humitos: Build: use ubuntu-20.04 image for setup VCS step (#8930)
@humitos: Celery: remove duplication of task names (#8929)
@humitos: Sentry and Celery: do not log RepositoryError in Sentry (#8928)
@ericholscher: Add x-hoverxref-version to CORS (#8927)
@humitos: Deploy: avoid locking the table when adding new JSON field (#8926)
@humitos: Build: access valid arguments (#8925)
@humitos: Comment: add comment from PR review (#8921)
@stsewd: Move subscription tasks (#8916)
@pyup-bot: pyup: Scheduled weekly dependency update for week 07 (#8915)
@stsewd: Proxito: add top-level docs (#8913)
@humitos: Celery: remove queue priority (#8848)

Version 7.2.1

Date:: February 15, 2022

@humitos: Sentry: ignore logging known exceptions (#8919)
@humitos: Build: do not send notifications on known failed builds (#8918)
@humitos: Celery: use on_retry to handle BuildMaxConcurrencyError (#8917)
@lkeegan: typo fix (#8911)
@stsewd: Fix tests (#8908)
@agjohnson: Throw an exception from Celery retry() (#8905)
@agjohnson: Reduce verbose logging on generic command failure (#8904)
@humitos: Build: define missing variable (#8903)
@humitos: Search: call apply_async to fix the issue (#8900)
@humitos: Build: allow to not record commands on sync_repository_task (#8899)
@humitos: Release 7.2.0 (#8898)
@stsewd: Fix linter (#8897)
@stsewd: Support for CDN when privacy levels are enabled (#8896)
@ericholscher: Don’t be so excited always in our emails :) (#8888)
@humitos: Docs: reduce visibility of Config File V1 (#8887)
@humitos: Builder: unpin pip (#8886)
@stsewd: Dependencies: remove unused packages (#8881)
@stsewd: Subscriptions: move some querysets (#8876)
@humitos: Django3: delete old JSONField and use the new ones (#8869)
@humitos: Django3: add new django.db.models.JSONField (#8868)

Version 7.2.0

Date:: February 08, 2022

@stsewd: Fix linter (#8897)
@ericholscher: Don’t be so excited always in our emails :) (#8888)
@stsewd: CI: Don’t install debug tools when running tests (#8882)
@agjohnson: Fix issue with build task routing and config argument (#8877)
@humitos: Celery: use an internal namespace to store build task’s data (#8874)
@agjohnson: Release 7.1.2 (#8873)
@agjohnson: Release 7.1.1 (#8872)
@humitos: Build: pin pip as workaround (#8865)
@humitos: Logging: reduce verbosity (#8856)
@humitos: Task router: check new config build.tools.python for conda (#8855)
@humitos: Logging: reduce logs in task router (#8854)
@humitos: Build process: use Celery handlers (#8815)

Version 7.1.2

Date:: January 31, 2022

@humitos: Build: pin pip as workaround (#8865)

Version 7.1.1

Date:: January 31, 2022

@humitos: Task router: check new config build.tools.python for conda (#8855)
@humitos: Logging: reduce logs in task router (#8854)
@humitos: django-storages: upgrade (#8853)
@humitos: Config: remove pipfile from schema (#8851)
@stsewd: AuditLog: always fill organization id & slug (#8846)
@stsewd: Docs (dev): fix server side search (#8845)
@humitos: Docs: remove beta warning from config file’s build key (#8843)
@agjohnson: Fix more casing issues (#8842)
@agjohnson: Update choosing a platform doc (#8837)
@pyup-bot: pyup: Scheduled weekly dependency update for week 04 (#8835)
@humitos: Django3: use BooleanField(null=True) (#8834)
@stsewd: Docs: fix edit on links (#8833)

Version 7.1.0

Date:: January 25, 2022

@astrojuanlu: Detail what URLs are expected in issue template (#8832)
@humitos: Cleanup: delete unused Django management commands (#8830)
@simonw: Canonical can point as stable, not just latest (#8828)
@humitos: Docs: remove USE_TESTING_BUILD_IMAGE (#8824)
@davidfischer: Use stickybox ad placement on RTD themed projects (#8823)
@ericholscher: Quiet the Unresolver logging (#8822)
@stsewd: Workaround for HttpExchange queries casting IDs as uuid/int wrongly (#8821)
@stsewd: Fix queryset for generic models (#8820)
@ericholscher: Release 7.0.0 (#8818)
@pyup-bot: pyup: Scheduled weekly dependency update for week 03 (#8817)
@stsewd: Subscriptions: move views (#8816)

Version 7.0.0

This is our 7th major version! This is because we are upgrading to Django 3.2 LTS.

Date:: January 17, 2022

@stsewd: Subscriptions: move views (#8816)
@stsewd: Fix docs (#8808)
@agjohnson: Release 6.3.3 (#8806)
@agjohnson: Fix linting issue on project private view (#8805)
@pyup-bot: pyup: Scheduled weekly dependency update for week 02 (#8804)
@astrojuanlu: Remove explicit username from tutorial (#8803)
@humitos: Bitbucket: update to match latest API changes (#8801)
@humitos: Cleanup: remove old/outdated code (#8793)
@stsewd: API v3: check if the name generates a valid slug (#8791)
@astrojuanlu: Make commercial docs more visible (#8780)
@stsewd: API v3: less overrides (#8770)
@stsewd: Move subscription models (#8746)
@humitos: Django3: minimal upgrade to Django3 (#8717)
@davidfischer: Make the analytics cookie a session cookie (#8694)
@ericholscher: Add ability to rebuild a specific build (#6995)

Version 6.3.3

Date:: January 10, 2022

@pyup-bot: pyup: Scheduled weekly dependency update for week 02 (#8804)
@astrojuanlu: Remove explicit username from tutorial (#8803)
@humitos: Bitbucket: update to match latest API changes (#8801)
@humitos: Requirements: downgrade celery (#8796)
@humitos: Requirements: downgrade redis to 3.5.3 (#8795)
@humitos: Cleanup: remove old/outdated code (#8793)
@humitos: Spam: deny dashboard on spammy projects (#8792)
@ericholscher: Mention subproject aliases (#8785)
@humitos: Config file: system_site_packages overwritten from project’s setting (#8783)
@astrojuanlu: Make commercial docs more visible (#8780)
@humitos: Spam: allow to mark a project as (non)spam manually (#8779)
@stsewd: API v3: less overrides (#8770)
@stsewd: Move subscription models (#8746)
@davidfischer: Make the analytics cookie a session cookie (#8694)

Version 6.3.2

Date:: January 04, 2022

@cagatay-y: Fix broken link in edit-source-links-sphinx.rst (#8788)
@pyup-bot: pyup: Scheduled weekly dependency update for week 52 (#8787)
@astrojuanlu: Cap setuptools even if installed packages are ignored (#8777)
@pyup-bot: pyup: Scheduled weekly dependency update for week 51 (#8776)
@astrojuanlu: Follow up to dev docs split (#8774)
@stsewd: API v3: improve message when using the API on the browser (#8768)
@stsewd: API v3: don’t include subproject_of on subprojects (#8767)
@davidfischer: Use ad client stickybox feature on RTD’s own docs (#8766)
@stsewd: API v3: explicitly test with RTD_ALLOW_ORGANIZATIONS=False (#8765)
@stsewd: Update tasks.py (#8764)
@ericholscher: Release 6.3.1 (#8763)
@humitos: Update common/ to latest version (#8761)
@stsewd: Skip slug check when editing an organization (#8760)
@stsewd: Explicit settings for some tests (#8759)
@ericholscher: Fix EA branding in docs (#8758)
@pyup-bot: pyup: Scheduled weekly dependency update for week 50 (#8757)
@astrojuanlu: Add MyST Markdown examples everywhere (#8752)
@stsewd: Docs: split user and dev docs (#8751)
@humitos: Logging: tweaks and minor improvements (#8736)
@stsewd: Audit: test models (#8495)

Version 6.3.1

Date:: December 14, 2021

@stsewd: Explicit settings for some tests (#8759)
@stsewd: Don’t run spam rules check after ban action (#8756)
@astrojuanlu: Add MyST Markdown examples everywhere (#8752)
@astrojuanlu: Update mambaforge to latest version (#8749)
@stsewd: Update django (#8748)
@astrojuanlu: Remove sphinx-doc.org from external domains (#8747)
@stsewd: Fix call to sync_remote_repositories (#8742)
@stsewd: Tests: set privacy level explicitly (#8740)
@humitos: Spam: contact link on template (#8739)
@humitos: Spam: fix admin filter (#8738)
@stsewd: Always clear cache after each test (#8737)
@humitos: Logging: tweaks and minor improvements (#8736)
@humitos: Logs: typo on keyname (#8734)
@humitos: Log: use structlog-sentry to send logs to Sentry (#8732)
@humitos: docs: use Python 3.8 to build our docs (#8731)
@agjohnson: Release 6.3.0 (#8730)
@stsewd: Custom Domain: make cname_target configurable (#8728)
@stsewd: Test external serving for projects with -- in slug (#8716)
@astrojuanlu: Add guide to migrate from reST to MyST (#8714)
@astrojuanlu: Avoid future breakage of setup.py invokations (#8711)
@humitos: structlog: migrate application code to better logging (#8705)
@humitos: EmbedAPI: log success requests (#8689)
@ericholscher: Add ability to rebuild a specific build (#6995)

Version 6.3.0

Date:: November 29, 2021

@humitos: Tests: run tests with Python3.8 in CircleCI (#8718)
@stsewd: Test external serving for projects with -- in slug (#8716)
@humitos: requirements: add requests-oauthlib (#8712)
@astrojuanlu: Avoid future breakage of setup.py invokations (#8711)
@humitos: spam: fix admin filter (#8707)
@humitos: oauth: sync remote repositories fix (#8706)
@humitos: structlog: migrate application code to better logging (#8705)
@astrojuanlu: Add guide on Poetry (#8702)
@humitos: EmbedAPI: log success requests (#8689)

Version 6.2.1

Date:: November 23, 2021

@agjohnson: Fix issue with PR build hostname parsing (#8700)
@ericholscher: Fix sharing titles (#8695)
@stsewd: Downgrade celery and friends (#8693)
@stsewd: Downgrade pyyaml (#8691)
@stsewd: Downgrade redis (#8690)
@humitos: Spam: make admin filters easier to understand (#8688)
@astrojuanlu: Clarify how to pin the Sphinx version (#8687)
@stsewd: Webhooks: fix link to docs (#8685)
@stsewd: Docs: update docs about search on subprojects (#8683)
@stsewd: Update common (#8681)
@pyup-bot: pyup: Scheduled weekly dependency update for week 46 (#8680)

Version 6.2.0

Date:: November 16, 2021

@rokroskar: docs: update faq to mention apt for dependencies (#8676)
@stsewd: UserProfile: add time fields (#8675)
@stsewd: Admin: don’t use update to ban users (#8674)
@stsewd: UserProfile: add historical model (#8673)
@astrojuanlu: Add entry on Jupyter Book to the FAQ (#8669)
@stsewd: Proxito: add CDN-Cache-Control headers (#8667)
@humitos: Spam: sort admin filters and show threshold (#8666)
@humitos: Cleanup: remove old code (#8665)
@humitos: Spam: check for spam rules after user is banned (#8664)
@humitos: Spam: use 410 - Gone status code when blocked (#8661)
@astrojuanlu: Upgrade readthedocs-sphinx-search (#8660)
@agjohnson: Release 6.1.2 (#8657)
@astrojuanlu: Update requirements pinning (#8655)
@stsewd: Historical records: set the change reason explicitly on the instance (#8627)
@stsewd: Support for generic webhooks (#8522)

Version 6.1.2

Date:: November 08, 2021

@astrojuanlu: Update requirements pinning (#8655)
@ericholscher: Fix GitHub permissions required (#8654)
@stsewd: Organizations: allow to add owners by email (#8651)
@pyup-bot: pyup: Scheduled weekly dependency update for week 44 (#8645)
@humitos: Spam: use thresholds to decide actions (#8632)
@astrojuanlu: Document generic webhooks (#8609)
@stsewd: Organizations: show audit logs (#8588)

Version 6.1.1

Date:: November 02, 2021

@agjohnson: Drop beta from title of build config option (#8637)
@astrojuanlu: Remove mentions to old Python version specification (#8635)
@jugmac00: fix typos (#8630)
@Arthur-Milchior: Correct an example (#8628)
@davidfischer: Inherit theme template (#8626)
@astrojuanlu: Clarify duration of extra DNS records (#8625)
@astrojuanlu: Promote mamba more in the documentation, hide CONDA_USES_MAMBA (#8624)
@davidfischer: Floating ad placement for docs.readthedocs.io (#8621)
@stsewd: Audit: track downloads separately from page views (#8619)
@humitos: Celery: quick hotfix to task (#8617)

Version 6.1.0

Date:: October 26, 2021

@astrojuanlu: Clarify docs (#8608)
@stsewd: Move more organization tests (#8606)
@astrojuanlu: New Read the Docs tutorial, part III (and finale?) (#8605)
@humitos: SSO: re-sync VCS accounts for SSO organization daily (#8601)
@humitos: Django Action: re-sync SSO organization’s users (#8600)
@pyup-bot: pyup: Scheduled weekly dependency update for week 42 (#8598)
@saadmk11: Don’t show the rebuild option on closed/merged Pull Request builds (#8590)
@carltongibson: Adjust Django intersphinx link to stable version. (#8589)
@humitos: Small fixes to asdf image upload script (#8587)
@astrojuanlu: Documentation names cleanup (#8586)
@stsewd: Fix docs (#8584)
@adamtheturtle: Fix typo “interpreters” (#8583)
@ericholscher: Small fixes to asdf image upload script (#8578)
@stsewd: Move organization views (#8577)
@humitos: EmbedAPIv3: docs for endpoint and guide updated (#8566)
@stsewd: GitLab integration: escape path (#8525)
@stsewd: Domain: allow to disable domain creation/update (#8020)

Version 6.0.0

Date:: October 13, 2021

This release includes the upgrade of some base dependencies:

Python version from 3.6 to 3.8
Ubuntu version from 18.04 LTS to 20.04 LTS

Starting from this release, all the Read the Docs code will be tested and QAed on these versions.

@ericholscher: Release 5.25.1 (#8576)
@deepto98: Moved authenticated_classes definitions from API classes to AuthenticatedClassesMixin (#8562)
@humitos: Upgrade to Ubuntu 20.04 and Python 3.8 (#7421)

Version 5.25.1

Date:: October 11, 2021

@astrojuanlu: Small fixes (#8564)
@deepto98: Moved authenticated_classes definitions from API classes to AuthenticatedClassesMixin (#8562)
@humitos: Build: update ca-certificates before cloning (#8559)
@humitos: Build: support Python 3.10.0 stable release (#8558)
@astrojuanlu: Document new build specification (#8547)
@astrojuanlu: Add checkbox to subscribe new users to newsletter (#8546)

Version 5.25.0

Date:: October 05, 2021

@humitos: Docs: comment about how to add a new tool/version for builders (#8548)
@astrojuanlu: Add checkbox to subscribe new users to newsletter (#8546)
@humitos: Build: missing updates from review (#8544)
@humitos: EmbedAPI: allow CORS for /api/v3/embed/ (#8543)
@humitos: Script tools cache: fix environment variables (#8541)
@humitos: EmbedAPIv3: proxy URLs to be available under /_/ (#8540)
@humitos: Docker: use the correct image tag (#8539)
@humitos: Requirement: ping django-redis-cache to git tag (#8536)
@pyup-bot: pyup: Scheduled weekly dependency update for week 39 (#8531)
@astrojuanlu: Promote and restructure guides (#8528)
@stsewd: Analytics: allow to download all data (#8498)
@stsewd: HistoricalRecords: add additional fields (ip and browser) (#8490)

Version 5.24.0

Date:: September 28, 2021

@humitos: EmbedAPIv3: updates after QA with sphinx-hoverxref (#8521)
@stsewd: Contact users: show progress (#8518)
@stsewd: Rename audit retention days setting (#8517)
@stsewd: Contact users: make notification sticky (#8516)
@stsewd: Contact users: report usernames instead of PK (#8515)
@stsewd: Audit: update admin (#8514)
@pyup-bot: pyup: Scheduled weekly dependency update for week 38 (#8510)
@stsewd: New config for new docker build images (#8478)
@stsewd: Audit: expose user security logs (#8477)
@humitos: Build: use new Docker images from design document (#8453)
@humitos: Embed APIv3: initial implementation (#8319)

Version 5.23.6

Date:: September 20, 2021

@astrojuanlu: Change newsletter form (#8509)
@stsewd: Contact users: Allow to pass additional context to each email (#8507)
@astrojuanlu: Update onboarding (#8504)
@astrojuanlu: List default installed dependencies (#8503)
@astrojuanlu: Clarify that the development installation instructions are for Linux (#8494)
@stsewd: Audit: attach organization (#8491)
@astrojuanlu: Add virtual env instructions to local installation (#8488)
@humitos: Requirement: update orjson (#8487)
@humitos: Release 5.23.5 (#8486)
@astrojuanlu: New Read the Docs tutorial, part II (#8473)

Version 5.23.5

Date:: September 14, 2021

@humitos: Organization: only mark artifacts cleaned as False if they are True (#8481)
@astrojuanlu: Fix link to version states documentation (#8475)
@stsewd: OAuth models: increase avatar_url lenght (#8472)
@pzhlkj6612: Docs: update the links to the dependency management content of setuptools docs (#8470)
@stsewd: Permissions: avoid using project.users, use proper permissions instead (#8458)
@humitos: Docker build images: update design doc (#8447)
@astrojuanlu: New Read the Docs tutorial, part I (#8428)

Version 5.23.4

Date:: September 07, 2021

@pzhlkj6612: Docs: update the links to the dependency management content of setuptools docs (#8470)
@nienn: Add custom team img styling (#8467)
@nienn: Docs: Change “right-click” to “click” (#8465)
@stsewd: Permissions: avoid using project.users, use proper permissions instead (#8458)
@stsewd: Add templatetag to filter by admin projects (#8456)
@stsewd: Support form: don’t allow to change the email (#8455)
@stsewd: Search: show only results from the current role_name being filtered (#8454)
@pyup-bot: pyup: Scheduled weekly dependency update for week 35 (#8451)
@stsewd: Update common (#8449)
@stsewd: API v3 (subprojects): filter by correct owner/organization (#8446)
@astrojuanlu: Rework Team page (#8441)
@mforbes: Added note about how to use Anaconda Project. (#8436)
@stsewd: Contact users: pass user and domain in the context (#8430)
@astrojuanlu: New Read the Docs tutorial, part I (#8428)
@stsewd: Footer: remove auth block (#8397)
@stsewd: API: fix subprojects creation when organizaions are enabled (#8393)
@stsewd: QuerySets: remove unused overrides (#8299)
@stsewd: QuerySets: filter permissions by organizations (#8298)

Version 5.23.3

Date:: August 30, 2021

@stsewd: Update common (#8449)
@stsewd: Upgrade ES to 7.14.0 (#8448)
@humitos: Docs: typo in tutorial (#8442)
@astrojuanlu: Docs miscellaneous enhancements (#8440)
@astrojuanlu: New Read the Docs tutorial, part I (#8428)
@humitos: Track organization artifacts cleanup (#8418)

Version 5.23.2

Date:: August 24, 2021

@astrojuanlu: Add MyST (Markdown) examples to “cross referencing with Sphinx” guide (#8437)
@saadmk11: Added Search and Filters for RemoteRepository and RemoteOrganization admin list page (#8431)
@agjohnson: Try out codeowners (#8429)
@humitos: Proxito: do not log response header for each custom domain request (#8427)
@cclauss: Fix undefined names (#8425)
@stsewd: Allow cookies from cross site requests to avoid problems with iframes (#8422)
@cclauss: Finish codespell – Concludes #8409 (#8421)
@cclauss: codespell CHANGELOG.rst (#8420)
@cclauss: codespell part 2 - Continues #8409 (#8419)
@ericholscher: Don’t filter on large items in the auditing sidebar. (#8417)
@astrojuanlu: Fix YAML extension (#8416)
@ericholscher: Release 5.23.1 (#8415)
@stsewd: Audit: attach project from the request if available (#8414)
@stsewd: Docs: update logout button image (#8413)
@pyup-bot: pyup: Scheduled weekly dependency update for week 33 (#8411)
@cclauss: Fix typos discovered by codespell in /docs (#8409)
@stsewd: Support: update contact information via Front webhook (#8406)
@stsewd: Docs: environment variables (#8390)
@stsewd: Allow users to remove themselves from a project (#8384)
@stsewd: Docs: document how to terminate a session (#8286)

Version 5.23.1

Date:: August 16, 2021

@cclauss: Fix typos discovered by codespell in /docs (#8409)
@stsewd: Audit: use analytics’ get_client_ip (#8404)
@steko: Add documentation about webhooks for Gitea (#8402)
@ericholscher: Add CSP header to the domain options (#8388)
@stsewd: Cookies: set samesite: Lax by default (#8304)
@stsewd: Docs: document how to terminate a session (#8286)
@stsewd: Docs: update sharing (#8239)

Version 5.23.0

Date:: August 09, 2021

@ericholscher: Only call analytics tracking of flyout when analytics are enabled (#8398)
@pyup-bot: pyup: Scheduled weekly dependency update for week 31 (#8385)
@stsewd: Audit: track user events (#8379)
@stsewd: Cookies: set samesite: Lax by default (#8304)
@stsewd: Docs: update sharing (#8239)
@DetectedStorm: Update LICENSE (#5125)

Version 5.22.0

Date:: August 02, 2021

@pzhlkj6612: Docs: fix typo in versions.rst: -> need (#8383)
@ericholscher: Remove clickjacking middleware for proxito (#8378)
@stsewd: Config file: use string for python.version (#8372)
@humitos: Add support for Python3.10 on testing Docker image (#8328)
@stsewd: Analytics: don’t fail if the page was created in another request (#8310)

Version 5.21.0

Date:: July 27, 2021

@stsewd: Fix migrations (#8373)
@ericholscher: Build out the MyST section of the getting started (#8371)
@stsewd: Fix tasks (#8370)
@astrojuanlu: Update common (#8368)
@astrojuanlu: Redirect users to appropriate support channels using template chooser (#8366)
@humitos: Proxito: return user-defined HTTP headers on custom domains (#8360)
@ericholscher: Release 5.20.3 (#8356)
@stsewd: Track model changes with django-simple-history (#8355)
@stsewd: SSO: move models (#8330)

Version 5.20.3

Date:: July 19, 2021

@Nkarnaud: change vieweable to viewable on home page: issue#8346 (#8351)
@stsewd: Builds: don’t record git rev-parse command (#8348)
@stsewd: UI: allow to close notifications (#8345)
@stsewd: Use email from DEFAULT_FROM_EMAIL to contact users (#8344)
@stsewd: Downgrade taggit (#8342)
@stsewd: Dont mutate env vars outside the BuildEnv classes (#8340)
@stsewd: Guides: how to import a private project using an ssh key (#8336)

Version 5.20.2

Date:: July 13, 2021

@humitos: psycopg2: pin to a compatible version with Django 2.2 (#8335)
@stsewd: Contact owners: use correct organization to filter (#8325)
@humitos: Design doc: fix render api endpoints (#8320)
@pyup-bot: pyup: Scheduled weekly dependency update for week 27 (#8317)
@mongolsteppe: Fixing minor error (#8313)
@stsewd: Build: remove after_vcs signal (#8311)
@The-Compiler: Add link to redirect docs (#8308)
@ericholscher: Add docs about setting up permissions for GH apps & orgs (#8305)
@stsewd: Schema: fix version type (#8303)
@stsewd: Slugify: don’t generate slugs with trailing - (#8302)
@ericholscher: Increase guide depth (#8300)
@humitos: autoscaling: remove app autoscaling tasks (#8297)
@humitos: PR build status: re-try up to 3 times if it fails for some reason (#8296)
@SethFalco: feat: add json schema (#8294)
@pyup-bot: pyup: Scheduled weekly dependency update for week 26 (#8293)
@stsewd: Organizations: validate that a correct slug is generated (#8292)
@stsewd: Footer: remove unused context vars (#8285)
@astrojuanlu: Add new guide about Jupyter in Sphinx (#8283)
@humitos: oauth webhook: check the Project has a RemoteRepository (#8282)
@stsewd: Allow to email users from a management command (#8243)
@humitos: Design doc: Embed APIv3 (#8222)
@astrojuanlu: Add proposal for new Sphinx and RTD tutorials (#8106)
@stsewd: Allow to change the privacy level of external versions (#7825)
@stsewd: Add tests for remove index files (#6381)

Version 5.20.1

Date:: June 28, 2021

@stsewd: Organizations: validate that a correct slug is generated (#8292)
@stsewd: Footer: remove unused context vars (#8285)
@stsewd: Search: remove additional fields (#8284)
@humitos: oauth webhook: check the Project has a RemoteRepository (#8282)
@stsewd: Search: small improvements (#8276)
@stsewd: Search: ask for confirmation when running reindex_elasticsearch (#8275)
@saadmk11: Hit Elasticsearch only once for each search query through the APIv2 (#8228)
@humitos: Design doc: Embed APIv3 (#8222)
@stsewd: QuerySets: remove include_all (#8212)
@astrojuanlu: Add proposal for new Sphinx and RTD tutorials (#8106)
@stsewd: Add tests for remove index files (#6381)

Version 5.20.0

Date:: June 22, 2021

@humitos: Migration: fix RemoteRepository - Project data migration (#8271)
@ericholscher: Release 5.19.0 (#8266)
@humitos: Sync RemoteRepository for external collaborators (#8265)
@stsewd: Git: don’t expand envvars in Gitpython (#8263)
@pyup-bot: pyup: Scheduled weekly dependency update for week 24 (#8262)
@stsewd: Builds: check for nonexistent object (#8261)
@humitos: Make Project -> ForeignKey -> RemoteRepository (#8259)
@agjohnson: Add basic security policy (#8254)
@stsewd: Search: remove workaround for subprojects (#8211)
@stsewd: Search: allow to filter by project slugs (#8149)

Version 5.19.0

Warning

This release contains a security fix to our CSRF settings: https://github.com/readthedocs/readthedocs.org/security/advisories/GHSA-3v5m-qmm9-3c6c

Date:: June 15, 2021

@stsewd: Builds: check for nonexistent object (#8261)
@ericholscher: Remove video from our Sphinx quickstart. (#8246)
@ericholscher: Remove “Markdown” from Mkdocs title (#8245)
@astrojuanlu: Make sustainability page more visible (#8244)
@stsewd: Builds: move send_build_status to builds/tasks.py (#8241)
@humitos: Add ability to rebuild a specific build (#8227)
@ericholscher: Don’t do any CORS checking on Embed API requests (#8226)
@stsewd: Footer: return well formed html (#8202)
@agjohnson: Add project/build filters (#8142)
@humitos: Sign Up: limit the providers allowed to sign up (#8062)
@stsewd: Search: use multi-fields for Wildcard queries (#7613)
@ericholscher: Add ability to rebuild a specific build (#6995)

Version 5.18.0

Date:: June 08, 2021

@stsewd: Fix tests (#8240)
@ericholscher: Backport manual indexes (#8235)
@ericholscher: Clean up SSO docs (#8233)
@stsewd: Cache get_project (#8231)
@ericholscher: Don’t do any CORS checking on Embed API requests (#8226)
@saadmk11: Optimize Index time database query (#8224)
@stsewd: Proxito: check if attribute exists (#8220)
@agjohnson: Update gitter channel name (#8217)
@ericholscher: Remove IRC from our docs (#8216)
@stsewd: QuerySets: filter by admin/team (#8214)
@stsewd: QuerySets: remove unused detail parameter (#8213)
@pyup-bot: pyup: Scheduled weekly dependency update for week 21 (#8206)
@stsewd: QuerySets: refactor _add_user_repos (#8182)
@stsewd: Organizations: simplify querysets/managers (#8180)
@akien-mga: Docs: Add section about deleting downloadable content (#8162)
@stsewd: Search: refactor views (#8157)
@stsewd: Search: little optimization when saving search queries (#8132)
@akien-mga: Docs: Add some details to the User Defined Redirects (#7894)
@agjohnson: Add APIv3 version edit URL (#7594)
@saadmk11: Add List API Endpoint for RemoteRepository and RemoteOrganization (#7510)

Version 5.17.0

Date:: May 24, 2021

@stsewd: Proxito: don’t require the middleware for proxied apis (#8203)
@stsewd: Builds: prevent code injection in cwd (#8198)
@ericholscher: Remove specific name from security page at user request (#8195)
@humitos: Docker: remove volumes= argument when creating the container (#8194)
@stsewd: Proxito: fix https and canonical redirects (#8193)
@stsewd: API v2: allow listing when using private repos (#8192)
@stsewd: Docker: set cwd explicitly (#8191)
@stsewd: API v2: allow to filter more endpoints (#8189)
@stsewd: Proxito: redirect to main project from subprojects (#8187)
@pyup-bot: pyup: Scheduled weekly dependency update for week 20 (#8186)
@agjohnson: Add DPA to legal docs in documentation (#8130)

Version 5.16.0

Date:: May 18, 2021

@stsewd: QuerySets: check for .is_superuser instead of has_perm (#8181)
@humitos: Build: use is_active method to know if the build should be skipped (#8179)
@humitos: APIv2: disable listing endpoints (#8178)
@stsewd: Project: use IntegerField for remote_repository from project form. (#8176)
@stsewd: Docs: remove some lies from cross referencing guide (#8173)
@stsewd: Docs: add space to bash code (#8171)
@pyup-bot: pyup: Scheduled weekly dependency update for week 19 (#8170)
@stsewd: Querysets: include organizations in is_active check (#8163)
@stsewd: Querysets: remove private and for_project (#8158)
@davidfischer: Disable FLOC by introducing permissions policy header (#8145)
@stsewd: Build: allow to install packages with apt (#8065)

Version 5.15.0

Date:: May 10, 2021

@stsewd: Ads: don’t load script if a project is marked as ad_free (#8164)
@stsewd: Querysets: include organizations in is_active check (#8163)
@stsewd: Querysets: simplify project querysets (#8154)
@pyup-bot: pyup: Scheduled weekly dependency update for week 18 (#8153)
@stsewd: Search: default to search on default version of subprojects (#8148)
@stsewd: Remove protected privacy level (#8146)
@stsewd: Embed: fix paths that start with / (#8139)
@humitos: Metrics: run metrics task every 30 minutes (#8138)
@humitos: web-celery: add logging for OOM debug on suspicious tasks (#8131)
@agjohnson: Fix a few style and grammar issues with SSO docs (#8109)
@stsewd: Embed: don’t fail while querying sections with bad id (#8084)
@stsewd: Design doc: allow to install packages using apt (#8060)

Version 5.14.3

Date:: April 26, 2021

@humitos: Metrics: run metrics task every 30 minutes (#8138)
@humitos: web-celery: add logging for OOM debug on suspicious tasks (#8131)
@stsewd: Celery router: check all n last builds for Conda (#8129)
@jonels-msft: Include aria-label in flyout search box (#8127)
@humitos: Logging: use %s to format the variable (#8125)
@stsewd: Build: improve list_packages_installed (#8122)
@stsewd: BuildCommand: don’t leak stacktrace to the user (#8121)
@stsewd: API (v2): use empty list in serializer’s exclude (#8120)
@astrojuanlu: Miscellaneous doc improvements (#8118)
@pyup-bot: pyup: Scheduled weekly dependency update for week 16 (#8117)
@agjohnson: Fix a few style and grammar issues with SSO docs (#8109)

Version 5.14.2

Date:: April 20, 2021

@stsewd: OAuth: check if user exists (#8115)
@stsewd: Sync versions: don’t fetch/return all versions (#8114)
@astrojuanlu: Improve contributing docs, take 2 (#8113)
@stsewd: ImportedFile: remove md5 field (#8111)
@stsewd: Config file: improve docs and help text (#8110)
@stsewd: Docs: add warning about design docs (#8104)
@Harmon758: Docs: fix typo in config-file/v2.rst (#8102)
@cocobennett: Improve documentation on contributing to documentation (#8082)

Version 5.14.1

Date:: April 13, 2021

@stsewd: OAuth: protection against deleted objects (#8081)
@cocobennett: Add page and page_size to server side api documentation (#8080)
@stsewd: Version warning banner: inject on role=”main” or main tag (#8079)
@stsewd: OAuth: avoid undefined var (#8078)
@stsewd: Conda: protect against None when appending core requirements (#8077)
@humitos: SSO: add small paragraph mentioning how to enable it on commercial (#8063)
@agjohnson: Add separate version create view and create view URL (#7595)

Version 5.14.0

Date:: April 06, 2021

This release includes a security update which was done in a private branch PR. See our security changelog for more details.

@pyup-bot: pyup: Scheduled weekly dependency update for week 14 (#8071)
@astrojuanlu: Clarify ad-free conditions (#8064)
@humitos: SSO: add small paragraph mentioning how to enable it on commercial (#8063)
@stsewd: Build environment: allow to run commands with a custom user (#8058)
@humitos: Design document for new Docker images structure (#7566)

Version 5.13.0

Date:: March 30, 2021

@stsewd: Test proxied embed API (#8051)
@stsewd: Feature flag: remove EXTERNAL_BUILD (#8050)
@stsewd: Sync versions: always use a task (#8049)
@stsewd: Versions: don’t create versions in bulk (#8046)
@stsewd: Embed: add cache tags (#8045)
@ericholscher: Fix proxito slash redirect for leading slash (#8044)
@pyup-bot: pyup: Scheduled weekly dependency update for week 12 (#8038)
@humitos: Docs: cleanup of old/deprecated documents (#7994)
@flying-sheep: Add publicly visible env vars (#7891)
@stsewd: Remove broadcast function (#7044)

Version 5.12.2

Date:: March 23, 2021

@humitos: AWS homepage link (#8037)
@hukkinj1: Fix a typo in the docs (#8035)
@stsewd: Clean some feature flags (#8034)
@ericholscher: Standardize footerjs code (#8032)
@stsewd: Docs: remove pdf format in MkdDocs example (#8030)
@stsewd: Search: don’t leak data for projects with this feature disabled (#8029)
@ericholscher: Canonicalize all proxito slashes (#8028)
@ericholscher: Make pageviews analytics show top 25 pages (#8027)
@ericholscher: Add CSV header data for search analytics (#8026)
@stsewd: HTMLFile: make md5 field nullable (#8025)
@humitos: Use RemoteRepository relation to match already imported projects (#8024)
@stsewd: Badge: exclude duplicated builds (#8023)
@stsewd: Intersphinx: declare user agent (#8022)
@stsewd: Builds: restart build commands before a new build (#7999)
@saadmk11: Remote Repository and Remote Organization Normalization (#7949)
@stsewd: Build: don’t track changed files (#7874)

Version 5.12.1

Date:: March 16, 2021

@pyup-bot: pyup: Scheduled weekly dependency update for week 11 (#8019)
@stsewd: Embed: Allow to override embed view for proxied use (#8018)
@humitos: RemoteRepository: Improvements to sync_vcs_data.py script (#8017)
@humitos: Stripe checkout: handle events (#8016)
@humitos: Remove contrib/ directory (#8014)
@stsewd: Dockerfile: install lsb_release (#8010)
@davidfischer: Fix AWS image so it looks sharp (#8009)
@stsewd: Update common (#8008)
@stsewd: Update Sphinx (#8007)
@2Fake: fix small typo (#8005)
@stsewd: Embed: validate query arguments (#8003)
@humitos: Stripe Checkout: handle duplicated wehbook (#8002)
@saadmk11: Add __str__ to RemoteRepositoryRelation and RemoteOrganizationRelation and Use raw_id_fields in Admin (#8001)
@saadmk11: Remove duplicate results from RemoteOrganization API (#8000)
@humitos: Typo fixed on checkout.js (#7998)
@ericholscher: Make SupportView login_required (#7997)
@ericholscher: Release 5.12.0 (#7996)
@pyup-bot: pyup: Scheduled weekly dependency update for week 10 (#7995)
@saadmk11: Remove json field from RemoteRepositoryRelation and RemoteOrganizationRelation model (#7993)
@humitos: Use independent Docker image to build assets (#7992)
@Pradhvan: Fixes typo in getting-started-with-sphinx: (#7991)
@humitos: Allow donate app to use Stripe Checkout for one-time donations (#7983)
@ericholscher: Add proxito healthcheck (#7948)
@Pradhvan: Docs: Adds Myst to the getting started with sphinx (#7938)
@humitos: Use Stripe Checkout for Gold Users (#7889)
@stsewd: Docs: guide about reproducible builds (#7888)

Version 5.12.0

Date:: March 08, 2021

@pyup-bot: pyup: Scheduled weekly dependency update for week 10 (#7995)
@saadmk11: Remove json field from RemoteRepositoryRelation and RemoteOrganizationRelation model (#7993)
@humitos: Use independent Docker image to build assets (#7992)
@Pradhvan: Fixes typo in getting-started-with-sphinx: (#7991)
@stsewd: Search: use doctype from indexed pages instead of the db (#7984)
@humitos: Allow donate app to use Stripe Checkout for one-time donations (#7983)
@humitos: Update development/standards guide (#7981)
@stsewd: Docs: update expand_tabs to work with the latest version of sphinx-tabs (#7979)
@ericholscher: Fix build routing (#7978)
@stsewd: Builds: register tasks to delete inactive external versions (#7975)
@stsewd: Embed: fix join (#7974)
@stsewd: Embed: change proxied urls (#7973)
@ericholscher: refactor footer, add jobs & status page (#7970)
@stsewd: Sphinx domain: remove API (#7969)
@humitos: Upgrade postgres-client to v12 in Docker image (#7967)
@saadmk11: Add management command to Load Project and RemoteRepository Relationship from JSON file (#7966)
@astrojuanlu: Update guide on conda support (#7965)
@stsewd: Embed: add more tests (#7962)
@humitos: Lower rank of development/install.html (#7960)
@stsewd: Embed: refactor view (#7955)
@stsewd: Search: make –queue required for management command (#7952)
@ericholscher: Add proxito healthcheck (#7948)
@Pradhvan: Docs: Adds Myst to the getting started with sphinx (#7938)
@ericholscher: Add a support form to the website (#7929)
@humitos: Use Stripe Checkout for Gold Users (#7889)
@stsewd: Docs: guide about reproducible builds (#7888)
@stsewd: Docs: update links from build images (#7886)
@stsewd: Install latest mkdocs by default as we do with sphinx (#7869)
@stsewd: Docs: document analytics (#7857)
@stsewd: Remove some feature flags (#7846)
@stsewd: Update requirements/deploy.txt (#7843)
@humitos: Implementation of APIv3 (#4863)

Version 5.11.0

Date:: March 02, 2021

@saadmk11: Add management command to Load Project and RemoteRepository Relationship from JSON file (#7966)
@humitos: Lower rank of development/install.html (#7960)
@saadmk11: Add Management Command to Dump Project and RemoteRepository Relationship in JSON format (#7957)
@davidfischer: Enable the cached template loader (#7953)
@stsewd: Update common to master (#7951)
@stsewd: Embed: refactor tests (#7947)
@stsewd: Downgrade jedi (#7946)
@FatGrizzly: Added warnings for previous gitbook users (#7945)
@stsewd: Move embed app (#7943)
@ericholscher: Change our sponsored hosting from Azure -> AWS. (#7940)
@Pradhvan: Docs: Adds Myst to the getting started with sphinx (#7938)
@ericholscher: Add a support form to the website (#7929)
@stsewd: Drop six (#7890)
@fabianmp: Allow to use a different url for intersphinx object file download (#7807)

Version 5.10.0

Date:: February 23, 2021

@pyup-bot: pyup: Scheduled weekly dependency update for week 08 (#7941)
@PawelBorkar: Update license (#7934)
@humitos: Route external versions to the queue were default version was built (#7933)
@humitos: Pin jedi dependency to avoid breaking ipython (#7932)
@humitos: Use admin user for SLUMBER API on local environment (#7925)
@stsewd: Search: add cache tags (#7922)
@humitos: Use S3 from community (#7920)
@stsewd: Use only one variant of the config file (#7918)
@pyup-bot: pyup: Scheduled weekly dependency update for week 07 (#7913)
@humitos: Router PRs builds to last queue where a build was executed (#7912)
@stsewd: Search: improve re-index management command (#7904)
@stsewd: Search: link to main project in subproject results (#7880)
@humitos: Upgrade Celery and friends to latest versions (#7786)

Version 5.9.0

Date:: February 16, 2021

Last Friday we migrated our site from Azure to AWS (read the blog post). This is the first release into our new AWS infra.

@humitos: Router PRs builds to last queue where a build was executed (#7912)
@humitos: Update common/ submodule (#7910)
@humitos: Upgrade Redis version to match production (#7909)
@davidfischer: Make storage classes into module level vars (#7908)
@csdev: fix typo (#7902)
@humitos: Match Redis version from AWS producion (#7897)
@pyup-bot: pyup: Scheduled weekly dependency update for week 06 (#7896)
@nedbat: Doc fix: two endpoints had ‘pip’ for the project_slug (#7895)
@stsewd: Set storage for BuildCommand and BuildEnvironment as private (#7893)
@pyup-bot: pyup: Scheduled weekly dependency update for week 05 (#7887)
@humitos: Add support for Python 3.9 on “testing” Docker image (#7885)
@stsewd: Add version_changed signal (#7878)
@stsewd: Search: don’t index permalinks (#7876)
@stsewd: Update common (#7873)
@pyup-bot: pyup: Scheduled weekly dependency update for week 04 (#7867)
@humitos: Log Stripe errors when trying to delete customer/subscription (#7853)
@humitos: Save builder when the build is concurrency limited (#7851)
@stsewd: Remove some feature flags (#7846)
@stsewd: Fix conf.py for external versions (#7845)
@humitos: Metric tasks for community (#7841)
@pyup-bot: pyup: Scheduled weekly dependency update for week 03 (#7840)
@humitos: Speed up concurrent builds by limited to 5 hours ago (#7839)
@humitos: Match Redis version with production (#7838)
@saadmk11: Add Option to Enable External Builds Through Project Update API (#7834)
@stsewd: Docs: mention the version warning is for sphinx only (#7832)
@agjohnson: Hide design docs from documentation (#7826)
@stsewd: Update docs about preview from pull/merge requests (#7823)
@humitos: Register MetricsTask to send metrics to AWS CloudWatch (#7817)
@humitos: Use S3 (MinIO emulator) as storage backend (#7812)
@zachdeibert: Cloudflare to Cloudflare CNAME Records (#7801)
@humitos: Documentation for /organizations/ endpoint in commercial (#7800)
@stsewd: Privacy Levels: migrate protected projects to private (#7608)
@pawamoy: Don’t lose python/name tags values in mkdocs.yml (#7507)
@stsewd: Install latest version of setuptools (#7290)
@humitos: Implementation of APIv3 (#4863)

Version 5.8.5

Date:: January 18, 2021

@pyup-bot: pyup: Scheduled weekly dependency update for week 03 (#7840)
@humitos: Speed up concurrent builds by limited to 5 hours ago (#7839)
@humitos: Match Redis version with production (#7838)
@saadmk11: Add Option to Enable External Builds Through Project Update API (#7834)
@stsewd: Docs: mention the version warning is for sphinx only (#7832)
@stsewd: Tests: make PRODUCTION_DOMAIN explicit (#7831)
@stsewd: Docs: make it easy to copy/pasta examples (#7829)
@stsewd: PR preview: pass PR and build urls to sphinx context (#7828)
@agjohnson: Hide design docs from documentation (#7826)
@stsewd: Footer: add cache tags (#7821)
@humitos: Log Stripe Resource fallback creation in Sentry (#7820)
@humitos: Register MetricsTask to send metrics to AWS CloudWatch (#7817)
@saadmk11: Add management command to Sync RemoteRepositories and RemoteOrganizations (#7803)
@stsewd: Mkdocs: default to “docs” for docs_dir (#7766)

Version 5.8.4

Date:: January 12, 2021

@pyup-bot: pyup: Scheduled weekly dependency update for week 02 (#7818)
@stsewd: List SYNC_VERSIONS_USING_A_TASK flag in the admin (#7802)
@ericholscher: Update build concurrency numbers for Business (#7794)
@stsewd: Sphinx: use html_baseurl for setting the canonical URL (#7540)

Version 5.8.3

Date:: January 05, 2021

@humitos: Change query on send_build_status task for compatibility with .com (#7797)
@ericholscher: Update build concurrency numbers for Business (#7794)
@pyup-bot: pyup: Scheduled weekly dependency update for week 01 (#7793)
@timgates42: docs: fix simple typo, -> translations (#7781)
@ericholscher: Release 5.8.2 (#7776)
@humitos: Use Python3.7 on conda base environment when using mamba (#7773)
@stsewd: Remove domain verify signal and task (#7763)
@stsewd: Import page: fix wizard form (#7702)
@ericholscher: Migrate sync_versions from an API call to a task (#7548)
@humitos: Design document for RemoteRepository DB normalization (#7169)

Version 5.8.2

Date:: December 21, 2020

@humitos: Use Python3.7 on conda base environment when using mamba (#7773)
@stsewd: Remove domain verify signal and task (#7763)
@humitos: Register StopBuilder task to be executed by builders (#7759)
@stsewd: Footer: remove absolute_uri (#7758)
@stsewd: Search: use alias to link to search results of subprojects (#7757)
@stsewd: Footer: remove jsonp call (#7756)
@humitos: Register AutoscaleBuildersTask (#7755)
@saadmk11: Set The Right Permissions on GitLab OAuth RemoteRepository (#7753)
@stsewd: Use lru_cache for caching methods (#7751)
@fabianmp: Allow to add additional binds to Docker build container (#7684)

Version 5.8.1

Date:: December 14, 2020

@humitos: Register ShutdownBuilder task (#7749)
@saadmk11: Use “path_with_namespace” for GitLab RemoteRepository full_name Field (#7746)
@stsewd: Features: remove USE_NEW_PIP_RESOLVER (#7745)
@stsewd: Version sync: exclude external versions when deleting (#7742)
@stsewd: Search: limit number of sections and domains to 10K (#7741)
@stsewd: Traffic analytics: don’t pass context if the feature isn’t enabled (#7740)
@stsewd: Analytics: move page views to its own endpoint (#7739)
@stsewd: FeatureQuerySet: make check for date inclusive (#7737)
@stsewd: Typo: date -> data (#7736)
@saadmk11: Use remote_id and vcs_provider Instead of full_name to Get RemoteRepository (#7734)
@pyup-bot: pyup: Scheduled weekly dependency update for week 49 (#7730)
@saadmk11: Update parts of code that were using the old RemoteRepository model fields (#7728)
@stsewd: Builds: don’t delete them when a version is deleted (#7679)
@stsewd: Sync versions: create new versions in bulk (#7382)
@humitos: Use mamba under a feature flag to create conda environments (#6815)

Version 5.8.0

Date:: December 08, 2020

@stsewd: Update common (#7731)
@stsewd: Bitbucket: mainbranch can be None (#7725)
@stsewd: Search: use with_positions_offsets term vector for some fields (#7724)
@stsewd: Search: filter only active and built versions from subprojects (#7723)
@stsewd: Extra features: allow to display them conditionally (#7715)
@humitos: Define pre/post_collectstatic signals and send them (#7701)
@davidfischer: Support the new Google analytics gtag.js (#7691)
@stsewd: HTMLFile: remove slug field (#7680)
@stsewd: External versions: delete after 3 months of being merged/closed (#7678)
@stsewd: Automation Rules: keep history of recent matches (#7658)
@stsewd: Search: update to ES 7.x (#7582)

Version 5.7.0

Date:: December 01, 2020

@davidfischer: Ensure there is space for sidebar ads (#7716)
@humitos: Install six as core requirement for builds (#7710)
@stsewd: Features: increase feature_id max_length (#7698)
@ericholscher: Release 5.6.1 (#7695)
@stsewd: Tests: mock trigger_build (#7681)
@stsewd: Sync versions: use stable version instead of querying all versions (#7380)

Version 5.6.5

Date:: November 23, 2020

@stsewd: Tests: mock trigger_build (#7681)
@stsewd: Tests: mock update_docs_task to speed up tests (#7677)
@stsewd: Versions: add timestamp fields (#7676)
@stsewd: Tests: create an organization when running in .com (#7673)
@davidfischer: Speed up the tag index page (#7671)
@davidfischer: Fix for out of order script loading (#7670)
@davidfischer: Set ad configuration values if using explicit placement (#7669)
@pyup-bot: pyup: Scheduled weekly dependency update for week 46 (#7668)
@stsewd: Tests: mock trigger build to speed up tests (#7661)
@stsewd: Remote repository: save and set default_branch (#7646)
@stsewd: Search: exclude some fields from source results (#7640)
@stsewd: Search: allow to search on different versions of subprojects (#7634)
@stsewd: Search: refactor api view (#7633)
@saadmk11: Add Initial Modeling with Through Model and Data Migration for RemoteRepository Model (#7536)
@stsewd: ImportedFile: remove slug 1/2 (#7228)
@humitos: Changes required for APIv3 in corporate (#6489)

Version 5.6.4

Date:: November 16, 2020

@davidfischer: Fix for out of order script loading (#7670)
@davidfischer: Set ad configuration values if using explicit placement (#7669)
@pyup-bot: pyup: Scheduled weekly dependency update for week 46 (#7668)
@pyup-bot: pyup: Scheduled weekly dependency update for week 45 (#7655)
@stsewd: Automation rules: add delete version action (#7644)
@stsewd: Search: exclude some fields from source results (#7640)
@saadmk11: Add Initial Modeling with Through Model and Data Migration for RemoteRepository Model (#7536)
@humitos: Changes required for APIv3 in corporate (#6489)

Version 5.6.3

Date:: November 10, 2020

@pyup-bot: pyup: Scheduled weekly dependency update for week 43 (#7602)

Version 5.6.2

Date:: November 03, 2020

@humitos: Check only for override settings (part 2) (#7630)
@humitos: Check only override settings (#7628)
@davidfischer: Display sidebar ad when scrolled (#7621)
@humitos: Reserve 1Gb for Application Memory (#7618)
@humitos: Catch requests.exceptions.ReadTimeout when removing container (#7617)
@humitos: Allow search and filter in Django Admin for Message model (#7615)
@stsewd: CI: use badge from circleci (#7614)
@stsewd: Search: respect feature flag in dashboard search (#7611)
@ericholscher: Release 5.6.1 (#7604)
@stsewd: CI: use circleci (#7603)

Version 5.6.1

Date:: October 26, 2020

@agjohnson: Bump common to include docker task changes (#7597)
@agjohnson: Default to sphinx theme 0.5.0 when defaulting to latest sphinx (#7596)
@humitos: Use correct Cache-Tag (CDN) and X-RTD-Project header on subprojects (#7593)
@davidfischer: Ads JS hotfix (#7586)
@agjohnson: Add remoterepo query param (#7580)
@agjohnson: Undeprecate APIv2 in docs (#7579)
@agjohnson: Add settings and docker configuration for working with new theme (#7578)
@stsewd: Search: exclude chagelog from results (#7570)
@stsewd: Search: better results for single terms (#7569)
@stsewd: Search: refactor query objects (#7568)
@humitos: Add our readthedocs_processor data to our notifications (#7565)
@stsewd: Update ES to 6.8.12 (#7559)
@stsewd: Builds: always install latest version of our sphinx extension (#7542)
@stsewd: Bring back project privacy level (#7525)
@ericholscher: Add future default true to Feature flags (#7524)
@stsewd: Add feature flag to not install the latest version of pip (#7522)
@davidfischer: No longer proxy RTD ads through RTD servers (#7506)
@stsewd: Subprojects: fix form (#7491)
@AvdN: correct inconsistent indentation of YAML (#7459)

Version 5.6.0

Date:: October 19, 2020

@stsewd: Search: exclude chagelog from results (#7570)
@stsewd: Docs: show example of a requirements.txt file (#7563)
@stsewd: Update ES to 6.8.12 (#7559)
@pyup-bot: pyup: Scheduled weekly dependency update for week 40 (#7537)
@ericholscher: Add future default true to Feature flags (#7524)
@davidfischer: No longer proxy RTD ads through RTD servers (#7506)
@davidfischer: Allow projects to opt-out of analytics (#7175)

Version 5.5.3

Date:: October 13, 2020

@ericholscher: Add a reference to the Import guide at the start of Getting started (#7547)
@kuzmoyev: Include month-ago day to traffic data (#7545)
@stsewd: Downloads: fix translation of a subproject (#7541)
@stsewd: Domains: more robust form (#7523)
@stsewd: Revert “Revert ES: update dependencies” (#7439)
@stsewd: Search: remove old endpoint (#7414)

Version 5.5.2

Date:: October 06, 2020

@stsewd: Domain: show created/modified date in admin (#7517)
@stsewd: Tests: fix eslint (#7516)
@ericholscher: Revert “New docker image for builders: 8.0” (#7514)
@srijan-deepsource: Fix some code quality issues (#7494)

Version 5.5.1

Date:: September 28, 2020

@stsewd: Domain: fix form (#7502)
@stsewd: Builders: little refactor (#7500)
@ericholscher: Add proper div names on our ad placements (#7493)
@saadmk11: APIv3 Version list slug filter added (#7372)
@humitos: Use “-j auto” on sphinx-build command to build in parallel (#7128)

Version 5.5.0

Date:: September 22, 2020

@stsewd: Don’t install pygments (#7490)
@humitos: Limit concurrency per-organization (#7489)
@pyup-bot: pyup: Scheduled weekly dependency update for week 37 (#7482)
@humitos: Use permissions (project and group) for RemoteRepository.admin on GitLab (#7479)

Version 5.4.3

Date:: September 15, 2020

@stsewd: Domain: inherit from TimeStampedModel (#7476)
@stsewd: Truncate output at the start for large commands (#7473)
@stsewd: Add dependency explicitly (dateutil) (#7415)
@stsewd: Domains: add ssl_status field (#7398)
@stsewd: Search: allow ignoring files from indexing (#7308)
@stsewd: Search: SSS integration guide (#7232)

Version 5.4.2

Date:: September 09, 2020

@humitos: Show “Connected Services” form errors to the user (#7469)
@humitos: Allow to extend OrganizationTeamBasicForm from -corporate (#7467)
@pyup-bot: pyup: Scheduled weekly dependency update for week 36 (#7465)
@AvdN: correct invalid YAML (#7458)
@stsewd: Remote repository: filter by account before deleting (#7454)
@humitos: Truncate the beginning of the commands’ output (#7449)
@davidfischer: Update links to advertising (#7443)
@stsewd: Revert “Don’t retry on POST” (#7442)
@stsewd: Organizations: move signals (#7441)
@stsewd: Organizations: move forms (#7438)
@humitos: Grab the correct name of RemoteOrganization to use in the query (#7430)
@stsewd: Revert “ES: update dependencies” (#7429)
@pyup-bot: pyup: Scheduled weekly dependency update for week 35 (#7423)
@humitos: Mark a build as DUPLICATED (same version) only it’s close in time (#7420)

Version 5.4.1

Date:: September 01, 2020

@stsewd: Docs: update readthedcos-sphinx-search ext (#7427)
@humitos: Upgrade Django to 2.2.16 (#7426)
@bmorrison4: Fix typo in docs/guides/adding-custom-css.rst (#7424)
@stsewd: Test: set privacy level explicitly (#7422)
@stsewd: Pip: test new resolver (#7412)
@stsewd: Update common (#7411)
@stsewd: Release 5.4.0 (#7410)
@stsewd: Docker: install requirements from local changes (#7409)
@stsewd: ES: update dependencies (#7408)
@pyup-bot: pyup: Scheduled weekly dependency update for week 34 (#7406)
@stsewd: API client: don’t retry on POST (#7383)
@saadmk11: build_url added to all API v3 build endpoints (#7373)
@stsewd: Guide: deprecating content (#7333)
@humitos: Auto-join email users field for Team model (#7328)
@stsewd: Guide: Cross-referencing with Sphinx (#7326)
@humitos: Sync RemoteRepository and RemoteOrganization in all VCS providers (#7310)
@stsewd: Page views: use origin URL instead of page name (#7293)

Version 5.4.0

Date:: August 25, 2020

@stsewd: ES: match version used in production (#7407)
@davidfischer: Advertising docs tweaks (#7400)
@stsewd: Docs: update readthedocs-sphinx-search (#7399)
@keewis: document installing into a environment with pinned dependencies (#7397)
@pyup-bot: pyup: Scheduled weekly dependency update for week 32 (#7377)
@stsewd: Builds: store build commands in storage (#7356)
@stsewd: Guide: Cross-referencing with Sphinx (#7326)

Version 5.3.0

Date:: August 18, 2020

@humitos: Remove the comma added in logs that breaks grep parsing (#7393)
@stsewd: GitLab webhook: don’t fail on invalid payload (#7391)
@stsewd: Task router: improve logging (#7389)
@stsewd: External providers: better logging for GitLab (#7385)
@stsewd: Task router: small changes (#7379)
@stsewd: Search: return relatives URLS (#7376)
@stsewd: Sync versions: little optimization when deleting versions (#7367)
@agjohnson: Add feature flag to just skip the sync version task entirely (#7366)
@agjohnson: Convert zip to list for templates (#7359)
@stsewd: Search: implement stable API (#7255)
@stsewd: Search: improve parser (#7233)

Version 5.2.3

Date:: August 04, 2020

@davidfischer: Add a middleware for referrer policy (#7346)
@stsewd: Footer: don’t show the version warning for external version (#7340)
@ericholscher: Lower rank for custom install docs. (#7339)
@benjaoming: Argument list for “python -m virtualenv” without empty strings (#7330)
@stsewd: Docs: fix some links (#7317)
@stsewd: Docs: little improvements on getting start docs (#7316)
@stsewd: Search: migrate null ranks to zero (#7274)
@stsewd: Docs: make it more clear search on subprojects (#7272)

Version 5.2.2

Date:: July 29, 2020

@agjohnson: Reduce robots.txt cache TTL (#7334)
@davidfischer: Use the privacy embed for YouTube (#7320)
@DougCal: re-worded text on top of “Import a Repository” (#7318)
@stsewd: Docs: make it clear the config file options are per version (#7314)
@humitos: Feature to disable auto-generated index.md/README.rst files (#7305)
@stsewd: Sphinx: always exclude the build directory (#7303)
@humitos: Enable SessionAuthentication on APIv3 endpoints (#7295)
@humitos: Allow to extend TeamManager (#7294)
@pyup-bot: pyup: Scheduled weekly dependency update for week 28 (#7287)
@humitos: Make “homepage” optional when updating a project (#7286)
@humitos: Allow users to set hidden on versions via APIv3 (#7285)
@humitos: DONT_INSTALL_DOCUTILS feature flag (#7276)
@humitos: Documentation for Single Sign-On feature on commercial (#7212)

Version 5.2.1

Date:: July 14, 2020

@davidfischer: Fix a case where “tags” is interpreted as a project slug (#7284)
@stsewd: Dashboard: little optimization (#7281)
@stsewd: Automation rules: privacy levels (#7278)
@stsewd: Templates: optimize permissions check (#7277)
@agjohnson: Fix versions (#7271)
@stsewd: Tweak priority a little more (#7270)
@stsewd: Don’t default on the migration (#7269)
@saadmk11: Automation rule to make versions hidden added (#7265)
@humitos: Add is_member template filter (#7264)
@stsewd: Docs: set ranking for some pages (#7257)
@stsewd: Sphinx: add –keep-going when fail_on_warning is true (#7251)
@saadmk11: Don’t allow Domain name matching production domain to be created (#7244)
@humitos: Documentation for Single Sign-On feature on commercial (#7212)

Version 5.2.0

Date:: July 07, 2020

@saadmk11: Version docs Typo fix (#7266)
@stsewd: CI: fix linter (#7261)
@GioviQ: Update manage-translations.rst (#7260)
@ericholscher: Add additional logging for sync_repository task (#7254)
@stsewd: Search: custom search page ranking (#7237)

Version 5.1.5

Date:: July 01, 2020

@choldgraf: cross-linking build limitations for pr builds (#7248)
@humitos: Allow to extend Import Project page from corporate (#7234)
@humitos: Make RemoteRepository.full_name db_index=True (#7231)
@stsewd: Search: tweak fuzziness (#7225)
@ericholscher: Re-add the rst filter that got removed (#7223)

Version 5.1.4

Date:: June 23, 2020

@stsewd: Search: index from html files for mkdocs projects (#7208)
@stsewd: Search: recursively parse sections (#7207)
@stsewd: Search: more general parser for html (#7204)
@humitos: Use total_memory to calculate “time” Docker limit (#7203)
@davidfischer: Feature flag for using latest Sphinx (#7201)
@ericholscher: Mention that we don’t index search in PR builds (#7199)
@davidfischer: Add a feature flag to use latest RTD Sphinx ext (#7198)
@ericholscher: Release 5.1.3 (#7197)
@stsewd: Search: improve results for simple queries (#7194)
@stsewd: Search: refactor json parser (#7184)
@stsewd: Remove unused dep (#7147)
@agjohnson: Use theme release 0.5.0rc1 for docs (#7037)
@humitos: Skip promoting new stable if current stable is not machine=True (#6695)

Version 5.1.3

Date:: June 16, 2020

@davidfischer: Fix the project migration conflict (#7196)
@stsewd: Search: fix pagination (#7195)
@ericholscher: Document the fact that PR builds are now enabled on .org (#7187)
@stsewd: Project: make description shorter (#7186)
@stsewd: Migrate private versions (#7181)
@ericholscher: Update sharing examples (#7179)
@davidfischer: Allow projects to opt-out of analytics (#7175)
@stsewd: Docs: install readthedocs-sphinx-search from pypi (#7174)
@humitos: Rename API endpoint call (#7173)
@ericholscher: Reduce logging in proxito middleware so it isn’t in Sentry (#7172)
@ericholscher: Release 5.1.2 (#7171)
@humitos: Use CharField.choices for Build.status_code (#7166)
@davidfischer: Store pageviews via signals, not tasks (#7106)
@stsewd: Move organizations models (#6776)

Version 5.1.2

Date:: June 09, 2020

@humitos: Use CharField.choices for Build.status_code (#7166)
@humitos: Install argh for Docker environment (#7164)
@ericholscher: Reindex search on the reindex queue (#7161)
@stsewd: Project search: Show original description when there isn’t highlight (#7160)
@stsewd: Search: highlight results from projects (#7158)
@ericholscher: Fix custom URLConf redirects (#7155)
@ericholscher: Allow blank=True for URLConf (#7153)
@stsewd: Fix flaky test (#7148)
@stsewd: Search: Make total_results not null (#7145)
@stsewd: Project: make external_builds_enabled not null (#7144)
@saadmk11: Do not Pre-populate username field for account delete (#7143)
@davidfischer: Add feature flag to use the stock Sphinx builders (#7141)
@ericholscher: Move changes_files to before search indexing (#7138)
@stsewd: Proxito middleware: reset to original urlconf after request (#7137)
@stsewd: Search: don’t index permalinks (#7134)
@ericholscher: Revert “Merge pull request #7101 from readthedocs/show-last-total” (#7133)
@ericholscher: Release 5.1.1 (#7129)
@humitos: Use “-j auto” on sphinx-build command to build in parallel (#7128)
@humitos: De-duplicate builds (#7123)
@stsewd: Search: refactor API to not emulate a Django queryset (#7114)
@davidfischer: Store pageviews via signals, not tasks (#7106)
@stsewd: Search: don’t index line numbers from code blocks (#7104)
@humitos: Document Embed APIv2 endpoint (#7095)
@ericholscher: Add a project-level configuration for PR builds (#7090)
@stsewd: Remove usage of project.privacy_level (#7013)
@pyup-bot: pyup: Scheduled weekly dependency update for week 18 (#7012)
@stsewd: Allow to enable server side search for MkDocs (#6986)
@stsewd: Pass the NO_COLOR env var to builder (#6981)
@humitos: Limit concurrency in translations (#6969)
@ericholscher: Add ability for users to set their own URLConf (#6963)

Version 5.1.1

Date:: May 26, 2020

@stsewd: Search: show total_results from last query (#7101)
@humitos: Add a tip in EmbedAPI to use Sphinx reference in section (#7099)
@ericholscher: Release 5.1.0 (#7098)
@ericholscher: Add a setting for storing pageviews (#7097)
@humitos: Document Embed APIv2 endpoint (#7095)
@stsewd: Footer: Check for mkdocs doctype too (#7094)
@ericholscher: Fix the unresolver not working properly with root paths (#7093)
@ericholscher: Add a project-level configuration for PR builds (#7090)
@santos22: Fix tests ahead of django-dynamic-fixture update (#7073)
@ericholscher: Add ability for users to set their own URLConf (#6963)
@dojutsu-user: Store Pageviews in DB (#6121)
@humitos: GitLab Integration (#3327)

Version 5.1.0

Date:: May 19, 2020

This release includes one major new feature which is Pageview Analytics. This allows projects to see the pages in their docs that have been viewed in the past 30 days, giving them an idea of what pages to focus on when updating them.

This release also has a few small search improvements, doc updates, and other bugfixes as well.

@ericholscher: Add a setting for storing pageviews (#7097)
@stsewd: Footer: Check for mkdocs doctype too (#7094)
@ericholscher: Fix the unresolver not working properly with root paths (#7093)
@stsewd: Privacy levels: migrate protected versions (#7092)
@humitos: Guide for Embed API (#7089)
@davidfischer: Document HSTS support (#7083)
@stsewd: Search: record queries with 0 results (#7081)
@stsewd: Search: track total results (#7080)
@humitos: Proxy embed URL (#7079)
@stsewd: Search: Little refactor (#7076)
@davidfischer: Canonical/HTTPS redirect fix (#7075)
@santos22: Fix tests ahead of django-dynamic-fixture update (#7073)
@stsewd: Sphinx Search: don’t skip indexing if one file fails (#7071)
@stsewd: Search: generate full link from the server side (#7070)
@ericholscher: Fix PR builds being marked built (#7069)
@ericholscher: Add a page about choosing between .com/.org (#7068)
@ericholscher: Release 5.0.0 (#7064)
@stsewd: Search: Index more content from sphinx (#7063)
@santos22: Hide unbuilt versions in footer flyout (#7056)
@ericholscher: Docs: Refactor and simplify our docs (#7052)
@stsewd: Search Document: remove unused class methods (#7035)
@stsewd: Search: iterate over valid facets only (#7034)
@stsewd: RTDFacetedSearch: pass filters in one way only (#7032)
@dojutsu-user: Store Pageviews in DB (#6121)

Version 5.0.0

Date:: May 12, 2020

This release includes two large changes, one that is breaking and requires a major version upgrade:

We have removed our deprecated doc serving code that used core/views, core/symlinks, and builds/syncers (#6535). All doc serving should now be done via proxito. In production this has been the case for over a month, we have now removed the deprecated code from the codebase.
We did a large documentation refactor that should make things nicer to read and highlights more of our existing features. This is the first of a series of new documentation additions we have planned
@ericholscher: Fix the caching of featured projects (#7054)
@ericholscher: Docs: Refactor and simplify our docs (#7052)
@stsewd: Mention using ssh URLs when using private submodules (#7046)
@ericholscher: Show project slug in Version admin (#7042)
@stsewd: List apiv3 first (#7041)
@stsewd: Remove CELERY_ROUTER flag (#7040)
@stsewd: Search: remove unused taxonomy field (#7033)
@agjohnson: Use a high time limit for celery build task (#7029)
@ericholscher: Clean up build admin to make list display match search (#7028)
@stsewd: Task Router: check for None (#7027)
@stsewd: Implement repo_exists for all VCS backends (#7025)
@stsewd: Mkdocs: Index pages without anchors (#7024)
@agjohnson: Move docker limits back to setting (#7023)
@humitos: Fix typo (#7022)
@stsewd: Fix linter (#7021)
@ericholscher: Release 4.1.8 (#7020)
@ericholscher: Cleanup unresolver logging (#7019)
@stsewd: Document about next when using a secret link (#7015)
@stsewd: Remove unused field project.version_privacy_level (#7011)
@ericholscher: Add proxito headers to redirect responses (#7007)
@stsewd: Make hidden field not null (#6996)
@humitos: Show a list of packages installed on environment (#6992)
@eric-wieser: Ensure invoked Sphinx matches importable one (#6965)
@ericholscher: Add an unresolver similar to our resolver (#6944)
@KengoTODA: Replace “PROJECT” with project object (#6878)
@humitos: Remove code replaced by El Proxito and stateless servers (#6535)

Version 4.1.8

Date:: May 05, 2020

This release adds a few new features and bugfixes. The largest change is the addition of hidden versions, which allows docs to be built but not shown to users on the site. This will keep old links from breaking but not direct new users there.

We’ve also expanded the CDN support to make sure we’re passing headers on 3xx and 4xx responses. This will allow us to expand the timeout on our CDN.

We’ve also updated and added a good amount of documentation in this release, and we’re starting a larger refactor of our docs to help users understand the platform better.

@ericholscher: Cleanup unresolver logging (#7019)
@ericholscher: Add CDN to the installed apps (#7014)
@eric-wieser: Emit a better error if no feature flag is found (#7009)
@ericholscher: Add proxito headers to redirect responses (#7007)
@ericholscher: Add Priority 0 to Celery (#7006)
@stsewd: Update conftest (#7002)
@ericholscher: Start storing JSON data for PR builds (#7001)
@yarikoptic: Add a note if build status is not being reported (#6999)
@stsewd: Update common (#6997)
@davidfischer: Exclusively handle proxito HSTS from the backend (#6994)
@humitos: Mention concurrent builds limitation in “Build Process” (#6993)
@humitos: Show a list of packages installed on environment (#6992)
@humitos: Document SHARE_SPHINX_DOCTREE flag (#6991)
@humitos: Contact us via email for Feature Flags (#6990)
@santos22: Alter field url on webhook (#6988)
@ericholscher: Log sync_repository_task when we run it (#6987)
@ericholscher: Remove old SSL cert warning, since they now work. (#6985)
@agjohnson: More fixes for automatic Docker limits (#6982)
@davidfischer: Add details to our changelog for 4.1.7 (#6978)
@ericholscher: Release 4.1.7 (#6976)
@humitos: Remove DOCKER_LIMITS (#6975)
@ericholscher: Catch infinite canonical redirects (#6973)
@eric-wieser: Ensure invoked Sphinx matches importable one (#6965)
@ericholscher: Add an unresolver similar to our resolver (#6944)
@stsewd: Add support for Mkdocs search (#6937)
@humitos: Optimization on sync_versions to use ls-remote on Git VCS (#6930)
@humitos: Split X-RTD-Version-Method header into two HTTP headers. (#6907)
@stsewd: Allow to override sign in and sign out views (#6901)
@stsewd: Hide version privacy (#6808)
@stsewd: Implement hidden state for versions (#6792)
@stsewd: Design doc for privacy levels (#6194)

Version 4.1.7

Date:: April 28, 2020

As of this release, most documentation on Read the Docs Community is now behind Cloudflare’s CDN. It should be much faster for people further from US East. Please report any issues you experience with stale cached documentation (especially CSS/JS).

Another change in this release related to how custom domains are handled. Custom domains will now redirect HTTP -> HTTPS if the Domain’s “HTTPS” flag is set. Also, the subdomain URL (eg. <project>.readthedocs.io/...) should redirect to the custom domain if the Domain’s “canonical” flag is set. These flags are configurable in your project dashboard under Admin > Domains.

Many of the other changes related to improvements for our infrastructure to allow us to have autoscaling build and web servers. There were bug fixes for projects using versions tied to annotated git tags and custom user redirects will now send query parameters.

@ericholscher: Reduce proxito logging (#6970)
@humitos: Log build/sync tasks when triggered (#6967)
@humitos: Stop builders gracefully on SIGTERM (#6960)
@stsewd: Try to fix annotated tags (#6959)
@stsewd: Include query params in 404 redirects (#6957)
@ericholscher: Fix the trailing slash in our repo regexs (#6956)
@davidfischer: Add canonical to the Domain listview in the admin (#6954)
@davidfischer: Allow setting HSTS on a per domain basis (#6953)
@humitos: Refactor how we handle GitHub webhook events (#6949)
@humitos: Return 400 when importing an already existing project (#6948)
@humitos: Return max_concurrent_builds in ProjectAdminSerializer (#6946)
@tom-doerr: Update year (#6945)
@humitos: Revert “Use requests.head to query storage.exists” (#6941)
@ericholscher: Release 4.1.6 (#6940)
@stsewd: Remove note about search analytics being beta (#6939)
@stsewd: Add troubleshooting section for dev search docs (#6933)
@davidfischer: Index date and ID together on builds (#6926)
@davidfischer: CAA records are not only for users of Cloudflare DNS (#6925)
@davidfischer: Docs on supporting root domains (#6923)
@ericholscher: Add basic support for lower priority PR builds (#6921)
@ericholscher: Change the dashboard search to default to searching files (#6920)
@davidfischer: Canonicalize domains and redirect in proxito (#6905)
@zdover23: Made syntactical improvements and fixed some vocabulary issues. (#6825)

Version 4.1.6

Date:: April 21, 2020

@stsewd: Revert usage of watchman (#6934)
@Mariatta: Fix typo: you -> your (#6931)
@humitos: Do not override the domain of Azure Storage (#6928)
@humitos: Per-project concurrency and check before triggering the build (#6927)
@davidfischer: Remove note about underscore in domain (#6924)
@stsewd: Pass INIT to azurite (#6918)
@humitos: Use requests.head to query storage.exists (#6917)
@stsewd: Bring back search highlight (#6914)
@ericholscher: Improve logging around status setting on PR builds (#6912)
@ericholscher: Add hoverxref to our docs (#6911)
@stsewd: Safely join storage paths (#6910)
@humitos: Release 4.1.5 (#6909)
@ericholscher: Fix Cache-Tag header name (#6908)
@stsewd: Handle paths with trailing / (#6906)
@ericholscher: Include the project slug in the PR context (#6904)
@ericholscher: Fix single version infinite redirect (#6900)
@humitos: Load YAML files safely (#6897)
@humitos: Use a custom Task Router to route tasks dynamically (#6849)
@zdover23: Made syntactical improvements and fixed some vocabulary issues. (#6825)
@humitos: Add CORS headers to Azurite (#6784)
@stsewd: Force to use proxied API for footer and search (#6768)
@ericholscher: Only output debug logging from RTD app (#6717)
@ericholscher: Add ability to sort dashboard by modified date (#6680)
@stsewd: Protection against None when sending notifications (#6610)
@stsewd: Guide: private python packages in .com (#6530)

Version 4.1.5

Date:: April 15, 2020

@ericholscher: Fix Cache-Tag header name (#6908)
@stsewd: Handle paths with trailing / (#6906)
@ericholscher: Fix single version infinite redirect (#6900)
@ericholscher: Release 4.1.4 (#6899)
@humitos: On Azure .exists blob timeout, log the exception and return False (#6895)
@ericholscher: Fix URLs like /projects/subproject from 404ing when they don’t end with a slash (#6888)
@ericholscher: Allocate docker limits based on server size. (#6879)

Version 4.1.4

Date:: April 14, 2020

@humitos: On Azure .exists blob timeout, log the exception and return False (#6895)
@ericholscher: Fix URLs like /projects/subproject from 404ing when they don’t end with a slash (#6888)
@ericholscher: Add CloudFlare Cache tags support (#6887)
@stsewd: Update requirements (#6885)
@stsewd: Be explicit with PUBLIC_DOMAIN setting (#6881)
@stsewd: Allow to override project detail view (#6880)
@ericholscher: Allocate docker limits based on server size. (#6879)
@ericholscher: Make the status name in CI configurable via setting (#6877)
@ericholscher: Add 12 hour caching to our robots.txt serving (#6876)
@humitos: Filter triggered builds when checking concurrency (#6875)
@ericholscher: Fix issue with sphinx domain types with : in them: (#6874)
@stsewd: Make dashboard faster for projects with a lot of subprojects (#6873)
@ericholscher: Release 4.1.3 (#6872)
@stsewd: Don’t do unnecessary queries when listing subprojects (#6869)
@stsewd: Optimize resolve_path (#6867)
@stsewd: Don’t do extra query if the project is a translation (#6865)
@stsewd: Remove private argument from resolver (#6864)
@stsewd: Support mkdocs html pages as doctype (#6846)
@stsewd: Reduce queries to storage to serve 404 pages (#6845)
@stsewd: Rework custom domains docs (#6844)
@stsewd: Add checking the github oauth app in the troubleshooting page (#6827)
@humitos: Return full path URL (including html) on /api/v2/docurl/ endpoint (#6082)

Version 4.1.3

Date:: April 07, 2020

@stsewd: Don’t do unnecessary queries when listing subprojects (#6869)
@stsewd: Don’t do extra query if the project is a translation (#6865)
@stsewd: Remove private argument from resolver (#6864)
@ericholscher: Make development docs a bit easier to find (#6861)
@davidfischer: Add an advertising API timeout (#6856)
@humitos: Add more exceptions as WARNING log level (#6851)
@humitos: Limit concurrent builds (#6847)
@humitos: Release 4.1.2 (#6840)
@humitos: Report build status in a smarter way (#6839)
@stsewd: Update messages-extends to latest version (#6838)
@humitos: Do not save pip cache when using CACHED_ENVIRONMENT (#6820)
@stsewd: Force to reinstall package (#6817)
@ericholscher: Denormalize from_url_without_rest onto the redirects model (#6780)
@davidfischer: Developer docs emphasize the Docker setup (#6682)
@davidfischer: Document setting up connected accounts in dev (#6681)
@humitos: Return full path URL (including html) on /api/v2/docurl/ endpoint (#6082)

Version 4.1.2

Date:: March 31, 2020

@humitos: Report build status in a smarter way (#6839)
@stsewd: Update messages-extends to latest version (#6838)
@humitos: Allow receiving None for template_html when sending emails (#6834)
@ericholscher: Fix silly issue with sync_callback (#6830)
@ericholscher: Show the builder in the Build admin (#6826)
@ericholscher: Properly call sync_callback when there aren’t any MULTIPLE_APP_SERVERS settings (#6823)
@stsewd: Allow to override app from where to read templates (#6821)
@humitos: Do not save pip cache when using CACHED_ENVIRONMENT (#6820)
@stsewd: Allow to override ProfileDetail view (#6819)
@ericholscher: Release 4.1.1 (#6818)
@stsewd: Force to reinstall package (#6817)
@humitos: Show uploading state (#6816)
@humitos: Use watchman when calling runserver in local development (#6813)
@humitos: Call proper handler (#6811)
@humitos: Show “Uploading” build state when uploading artifacts into storage (#6810)
@stsewd: Make search compatible with sphinx 2.2.1 (#6804)
@stsewd: Changes on 404, robots, and sitemap (#6798)
@humitos: Update guide about building consuming too much resources (#6778)

Version 4.1.1

Date:: March 24, 2020

@stsewd: Force to reinstall package (#6817)
@humitos: Show uploading state (#6816)
@stsewd: Respect order when serving 404 (version -> default_version) (#6805)
@humitos: Use storage.open API correctly for tar files (build cached envs) (#6799)
@humitos: Check 404 page once when slug and default_version is the same (#6796)
@humitos: Do not reset the build start time when running build env (#6794)
@humitos: Skip .cache directory for cached builds if it does not exist (#6791)
@ericholscher: Remove GET args from the path passed via proxito header (#6790)
@stsewd: Check for /index on pages’ slug (#6789)
@ericholscher: Release 4.1.0 (#6788)
@ericholscher: Revert “Add feature flag to just completely skip sync and symlink operations (#6689)” (#6781)

Version 4.1.0

Date:: March 17, 2020

@ericholscher: Properly proxy the Proxito headers via nginx/sendfile (#6782)
@ericholscher: Revert “Add feature flag to just completely skip sync and symlink operations (#6689)” (#6781)
@humitos: Upgrade django-storages to support URLs with more http methods (#6771)
@davidfischer: Use the hotfixed version of django-messages-extends (#6767)
@ericholscher: Release 4.0.3 (#6766)
@stsewd: Document usage or pytest marks (#6764)
@humitos: Pull/Push cached environment using storage (#6763)
@stsewd: Refactor search view to make use of permission_classes (#6761)
@stsewd: Run proxito tests with proxito (#6714)
@stsewd: Proxy footer api on docs’ domains (#6630)

Version 4.0.3

Date:: March 10, 2020

@stsewd: Document usage or pytest marks (#6764)
@stsewd: Update some dependencies (#6762)
@stsewd: Refactor search view to make use of permission_classes (#6761)
@ericholscher: Revert “Merge pull request #6739 from readthedocs/agj/docs-tos-pdf” (#6760)
@ericholscher: Expand the logic in our proxito mixin. (#6759)
@comradekingu: Spelling: “Set up your environment” (#6752)
@humitos: Use storage.exists on HEAD method (#6751)
@humitos: Pull only latest image for development (#6750)
@humitos: Update common submodule (#6749)
@ericholscher: Release 4.0.2 (#6741)
@agjohnson: Add TOS PDF output (#6739)
@ericholscher: Don’t call virtualenv with --no-site-packages (#6738)
@GallowayJ: Drop mock dependency (#6723)
@stsewd: Run proxito tests with proxito (#6714)
@humitos: New block on footer template to override from corporate (#6702)
@humitos: Point users to support email instead asking to open an issue (#6650)
@stsewd: Proxy footer api on docs’ domains (#6630)

Version 4.0.2

Date:: March 04, 2020

@ericholscher: Don’t call virtualenv with --no-site-packages (#6738)
@stsewd: Catch ConnectionError from request on api timing out (#6735)
@ericholscher: Release 4.0.1 (#6733)
@humitos: Improve Proxito 404 handler to render user-facing Maze when needed (#6726)

Version 4.0.1

Date:: March 03, 2020

@ericholscher: Add feature flag for branch & tag syncing to API. (#6729)
@stsewd: Don’t fail a build on api timing out (#6719)
@stsewd: Be explicit on privacy level for search tests (#6713)
@stsewd: Make easy to run search tests in docker compose (#6711)
@davidfischer: Docker settings improvements (#6709)
@davidfischer: Workaround SameSite cookies (#6708)
@davidfischer: Figure out the host IP when using Docker (#6707)
@davidfischer: Pin the version of Azurite for docker-compose development (#6706)
@ericholscher: Release 4.0.0 (#6704)
@humitos: Rename docker settings to fix local environment (#6703)
@sduthil: API v3 doc: fix typos in URL for PATCH /versions/slug/ (#6698)
@humitos: Sort versions in-place to help performance (#6696)
@humitos: Use .iterator when sorting versions (#6694)
@agjohnson: Add feature flag to just completely skip sync and symlink operations (#6689)
@humitos: Disable more loggings in development environment (#6683)
@davidfischer: Use x-forwarded-host in local docker environment (#6679)
@humitos: Allow user to set build.image: testing in the config file (#6676)
@agjohnson: Add azurite –loose option (#6669)
@stsewd: Have more control over search tests (#6644)
@davidfischer: Enable content security policy in report-only mode (#6642)
@stsewd: Add test settings file for proxito (#6623)
@stsewd: Guide: using private submodules in rtd.com (#6527)

Version 4.0.0

Date:: February 25, 2020

This release upgrades our codebase to run on Django 2.2. This is a breaking change, so we have released it as our 4th major version.

@stsewd: Data migration for old integration models (#6675)
@ericholscher: Release 3.12.0 (#6674)
@humitos: Upgrade to Django 2.2.9 (#6494)
@davidfischer: Show message if version list truncated (#6276)

Version 3.12.0

Date:: February 18, 2020

This version has two major changes:

It updates our default docker images to stable=5.0 and latest=6.0.
It changes our PR builder domain to readthedocs.build
@humitos: Use PUBLIC_DOMAIN_USES_HTTPS for resolver tests (#6673)
@stsewd: Always run CoreTagsTests with http (#6671)
@ericholscher: Remove old docker settings (#6670)
@stsewd: Update gitpython and django (#6667)
@humitos: New docker release (6.0 and testing) (#6654)
@humitos: Default python version per Docker image (#6653)
@stsewd: Add pytest-custom_exit_code (#6648)
@ericholscher: Initial attempt to serve PR builds at readthedocs.build (#6629)
@ericholscher: Remove re-authing of users on downloads. (#6619)
@stsewd: Don’t trigger a sync twice on creation/deletion for GitHub (#6614)
@s-weigand: Add linkcheck test for the docs (#6543)

Version 3.11.6

Date:: February 04, 2020

@ericholscher: Note we aren’t doing GSOC in 2020 (#6618)
@ericholscher: only serve x-rtd-slug project if it exists (#6617)
@ericholscher: Add check for a single_version project having a version_slug for PR builds (#6615)
@stsewd: Fix linter (#6613)
@stsewd: Create unique container per sync (#6612)
@stsewd: Check for None before assignment (#6611)
@ericholscher: Raise exception when we get an InfiniteRedirect (#6609)
@ericholscher: Release 3.11.5 (#6608)
@humitos: Avoid infinite redirect on El Proxito on 404 (#6606)
@stsewd: Don’t error when killing/removing non-existent container (#6605)
@humitos: Use proper path to download/install readthedocs-ext (#6603)
@humitos: Use timeout on internal API calls (#6602)
@stsewd: Don’t assume build isn’t None in a docker build env (#6599)
@ericholscher: Fix issue with pip 20.0 breaking on install (#6598)
@stsewd: More protection against None (#6597)
@agjohnson: Revert “Update celery requirements to its latest version” (#6596)
@Blackcipher101: Changed documentation of Api v3 (#6574)
@ericholscher: Use our standard auth mixin for proxito downloads (#6572)
@humitos: Move common docker compose configs to common repository (#6539)

Version 3.11.5

Date:: January 29, 2020

@humitos: Avoid infinite redirect on El Proxito on 404 (#6606)
@humitos: Use proper path to download/install readthedocs-ext (#6603)
@stsewd: Don’t assume build isn’t None in a docker build env (#6599)
@ericholscher: Fix issue with pip 20.0 breaking on install (#6598)
@agjohnson: Revert “Update celery requirements to its latest version” (#6596)
@stsewd: Remove .cache from parent dir (#6595)
@agjohnson: Release 3.11.4 again (#6594)
@agjohnson: Release 3.11.4 (#6593)
@ericholscher: Use our standard auth mixin for proxito downloads (#6572)
@stsewd: Migrate doctype from project to version (#6523)

Version 3.11.4

Date:: January 28, 2020

@humitos: Disable django debug toolbar in El Proxito (#6591)
@stsewd: Respect docker setting on repo sync (#6589)
@humitos: Merge pull request #6588 from readthedocs/humitos/support-ext (#6588)
@humitos: Fix argument of update_repos (#6583)
@humitos: Mount proper shared docker volume (#6581)
@ericholscher: Use our standard auth mixin for proxito downloads (#6572)
@stsewd: Delete .cache dir on wipe (#6571)
@humitos: Run old redirect tests via El Proxito (#6570)
@humitos: Remove ‘build environment’ from guides (#6568)
@ericholscher: Fix /en/latest redirects (#6564)
@stsewd: Merge pull request #6561 from stsewd/move-method (#6561)
@stsewd: Use settings override in footer (#6560)
@ericholscher: Fix proxito redirects breaking without a / (#6558)
@stsewd: Remove unused file (#6557)
@mgeier: DOC: Change a lot of http links to https (#6553)
@stsewd: Don’t use an instance of VCS when isn’t needed (#6548)
@saadmk11: Add GitHub OAuth App Permission issue to PR Builder Troubleshooting docs (#6547)
@humitos: Move common docker compose configs to common repository (#6539)
@preetmishra: Update Transifex Integration details in Internationalization page. (#6531)
@stsewd: Migrate doctype from project to version (#6523)
@stsewd: Simplify docker image (#6519)
@Parth1811: Fixes #5388 – Added Documentation for constraint while using Conda (#6509)
@stsewd: Improve test for sync_repo (#6504)
@humitos: Show debug toolbar when running docker compose (#6488)
@dibyaaaaax: Add python examples for API v3 Documentation (#6487)

Version 3.11.3

Date:: January 21, 2020

@ericholscher: Pass proper path to redirect code (#6555)
@Daniel-Mietchen: Fixing a broken link (#6550)
@stsewd: Guide: Intersphinx in Read the Docs (#6520)
@humitos: Add netcat and telnet for celery debugging with rdb (#6518)
@humitos: Core team development standards guide (#6517)
@dibyaaaaax: Add www to the broken link (#6513)
@davidfischer: Don’t allow empty tags (#6512)
@Parth1811: Fixes #6510 – Removed the show_analytics checks from the template (#6511)
@stsewd: Only install node on eslint step on travis (#6505)
@stsewd: Don’t pass build to environment when doing a sync (#6503)
@ericholscher: Release 3.11.2 (#6502)
@Blackcipher101: Added “dirhtml” target (#6500)
@humitos: Use CELERY_APP_NAME to call the proper celery app (#6499)
@stsewd: Copy path from host only when using a LocalBuildEnviroment (#6482)
@stsewd: Set env variables in the same way for DockerBuildEnvironment and Loc… (#6481)
@stsewd: Use environment variable per run, not per container (#6480)
@humitos: Update celery requirements to its latest version (#6448)
@stsewd: Execute checkout step respecting docker setting (#6436)
@humitos: Serve non-html at documentation domain though El Proxito (#6419)

Version 3.11.2

Date:: January 08, 2020

@ericholscher: Fix link to my blog post breaking https (#6495)
@humitos: Use a fixed IP for NGINX under docker-compose (#6491)
@humitos: Add ‘index.html’ to the path before using storage.url(path) (#6476)
@agjohnson: Release 3.11.1 (#6473)
@humitos: Use tasks from common (including docker ones) (#6471)
@humitos: Upgrade Django due a security issue (#6470)
@humitos: Fix celery auto-reload command (#6469)
@humitos: Use django storage to build URL returned by El Proxito (#6466)
@ericholscher: Handle GitHub Push events with deleted: true in the JSON (#6465)
@humitos: Serve external version through El Proxito (#6434)
@segevfiner: Remove a stray backtick from import-guide.rst (#6362)

Version 3.11.1

Date:: December 18, 2019

@humitos: Upgrade Django due a security issue (#6470)
@humitos: Use django storage to build URL returned by El Proxito (#6466)
@ericholscher: Handle GitHub Push events with deleted: true in the JSON (#6465)
@ericholscher: Update troubleshooting steps for PR builder (#6463)
@ericholscher: Add DOCKER_NORELOAD to compose settings (#6461)
@stsewd: Be explicit when using setup_env (#6451)
@keshavvinayak01: Fixed remove_search_analytics issue (#6447)
@saadmk11: Fix logic to build internal/external versions on update_repos management command (#6442)
@humitos: Refactor get_downloads to make one query for default_version (#6441)
@humitos: Do not expose env variables on external versions (#6440)
@humitos: Better ES settings on docker-compose (#6439)
@humitos: Remove global pip cache (#6437)
@humitos: Bring Azure storage backend classes to this repository (#6433)
@stsewd: Show predefined match on automation rules admin (#6432)
@stsewd: Override production domain explicitly (#6431)
@humitos: inv tasks to use when developing with docker (#6418)
@piyushpalawat99: Fix #6395 (#6402)
@stsewd: Only pass public versions to html context (#6118)
@ericholscher: Add an “Edit Versions” listing to the Admin menu (#6110)
@saadmk11: Extend webhook notifications with build status (#5621)

Version 3.11.0

Date:: December 03, 2019

@davidfischer: Use media availability instead of querying the filesystem (#6428)
@stsewd: Remove beta note about sharing by password and header auth (#6426)
@humitos: Use trigger_build for update_repos command (#6422)
@humitos: Add more supported field to APIv3 docs (#6417)
@humitos: Add AuthenticationMiddleware to El Proxito tests (#6416)
@stsewd: Update docs on sharing (#6410)
@humitos: Use WORKDIR to cd into a directory in Dockerfile (#6409)
@humitos: Use /data inside Azurite container to persist data (#6407)
@humitos: Serve non-html files from nginx (X-Accel-Redirect) (#6404)
@humitos: Perform redirects at DB level (#6398)
@humitos: Allow to extend El Proxito views from commercial (#6397)
@humitos: Migrate El Proxito views to class-based views (#6396)
@agjohnson: Fix CSS and how we were handling html in automation rule UI (#6394)
@ericholscher: Release 3.10.0 (#6391)
@stsewd: Set privacy level explicitly (#6390)
@ericholscher: Redirect index files in proxito instead of serving (#6387)
@humitos: Fully working docker-compose file (#6295)
@saadmk11: Refactor Subproject validation to use it for Forms and API (#6285)
@saadmk11: Refactor Gold Views (#6272)
@stsewd: Add docs for automatin rules (#6072)

Version 3.10.0

Date:: November 19, 2019

@stsewd: Set privacy level explicitly (#6390)
@ericholscher: Redirect index files in proxito instead of serving (#6387)
@stsewd: Fix search indexing (#6380)
@humitos: Include creditcard.png image (#6379)
@stsewd: Silent curl (#6377)
@stsewd: Use github actions to trigger tests in corporate (#6376)
@saadmk11: Show only users projects in the APIv3 browsable form (#6374)
@humitos: Release 3.9.0 (#6371)
@davidfischer: Pin the node dependencies with a package-lock (#6370)
@ericholscher: Small optimization to not compute the highest version when it isn’t displayed (#6360)
@krptic07: remove rss feed (#6348)
@pyup-bot: pyup: Scheduled weekly dependency update for week 44 (#6347)
@ericholscher: Port additional features to proxito (#6286)
@stsewd: Add docs for automatin rules (#6072)
@stsewd: Implement UI for automation rules (#5996)

Version 3.9.0

Date:: November 12, 2019

@davidfischer: Pin the node dependencies with a package-lock (#6370)
@humitos: Force PUBLIC_DOMAIN_USES_HTTPS on version compare tests (#6367)
@segevfiner: Remove a stray backtick from import-guide.rst (#6362)
@stsewd: Don’t compare inactive or non build versions (#6361)
@stsewd: Fix test (#6358)
@ericholscher: Change the default of proxied_api_host to api_host (#6355)
@stsewd: Dont link to dashboard from footer (#6353)
@humitos: Upgrade django-storages (#6339)
@pyup-bot: pyup: Scheduled weekly dependency update for week 43 (#6334)
@KartikKapil: added previous year gsoc projects (#6333)
@stsewd: Support 6.0rc1 build image (#6329)
@stsewd: Don’t error on non existing version (#6325)
@stsewd: Remove files from storage and delete indexes from ES when no longer needed (#6323)
@stsewd: Fix eslint (#6317)
@humitos: Revert “Adding RTD prefix for docker only in setting.py and all… (#6315)
@anindyamanna: Fixed Broken links (#6300)
@stsewd: Use sync instead of copy for blob storage (#6298)
@sciencewhiz: Fix missing word in wipe guide (#6294)
@jaferkhan: Removed unused code from view and template (#6250) (#6288)
@stsewd: Rename test name (#6283)
@davidfischer: Store version media availability (#6278)
@davidfischer: Link to the terms of service (#6277)
@saadmk11: API V3 Subproject Creation Bug fix (#6275)
@stsewd: Fix footer (#6274)
@stsewd: Fix tests (#6269)
@stsewd: Refactor profile’s views (#6267)
@humitos: Default to None when using the Serializer as Form for Browsable… (#6266)
@ericholscher: Fix inactive version list not showing when no results returned (#6264)
@ericholscher: Downgrade django-storges. (#6263)
@ericholscher: Release 3.8.0 (#6262)
@stsewd: Update doccs version detail (api v3) (#6259)
@stsewd: Merge #6176 to master (#6258)
@humitos: Remove privacy_level field from APIv3 (#6257)
@saadmk11: Redirect /projects/ URL to /dashboard/ (#6255)
@davidfischer: Allow project badges for private version (#6252)
@stsewd: Add pub_date to project admin (#6244)
@saadmk11: Allow only post requests for delete views (#6242)
@Iamshankhadeep: Changing created to modified time (#6234)
@ericholscher: Initial stub of proxito (#6226)
@saadmk11: Add Better error message for lists in config file (#6200)
@stsewd: Put view under login (#6193)
@humitos: Ship API v3 (#6169)
@stsewd: Protection against ReDoS (#6163)
@dojutsu-user: Optimize json parsing (#6160)
@tapaswenipathak: Added missing i18n for footer api (#6144)
@stsewd: Use different setting for footer api url (#6131)
@dojutsu-user: Remove ‘highlight’ URL param from search results (#6087)
@Iamshankhadeep: Adding RTD prefix for docker only in setting.py and all other places where is needed (#6040)
@stsewd: Design doc for organizations (#5958)

Version 3.8.0

Date:: October 09, 2019

@stsewd: Update doccs version detail (api v3) (#6259)
@stsewd: Merge #6176 to master (#6258)
@humitos: Remove privacy_level field from APIv3 (#6257)
@saadmk11: Redirect /projects/ URL to /dashboard/ (#6255)
@davidfischer: Allow project badges for private version (#6252)
@pyup-bot: pyup: Scheduled weekly dependency update for week 40 (#6251)
@saadmk11: Add note about specifying dependencies (#6248)
@stsewd: Add pub_date to project admin (#6244)
@humitos: Do not use –cache-dir for pip if CLEAN_AFTER_BUILD is enabled (#6239)
@stsewd: Update pytest (#6233)
@iambenzo: remove /projects/ (#6228)
@ericholscher: Initial stub of proxito (#6226)
@davidfischer: Improve the version listview (#6224)
@stsewd: Override production media artifacts on test (#6220)
@davidfischer: Customize default build media storage for the FS (#6215)
@agjohnson: Release 3.7.5 (#6214)
@stsewd: Remove dead code (#6213)
@stsewd: Only use the sphinx way to mock (#6212)
@saadmk11: Only Build Active Versions from Build List Page Form (#6205)
@saadmk11: Make raw_config private (#6199)
@Iamshankhadeep: moved expandable_fields to meta class (#6198)
@stsewd: Put view under login (#6193)
@dojutsu-user: Remove pie-chart from search analytics page (#6192)
@stsewd: Refactor SearchAnalytics view (#6190)
@stsewd: Refactor ProjectRedirects views (#6187)
@stsewd: Refactor ProjectTranslations views (#6185)
@stsewd: Refactor ProjectNotications views (#6183)
@stsewd: Refactor views ProjectUsers (#6178)
@humitos: Create subproject relationship via APIv3 endpoint (#6176)
@stsewd: Refactor views ProjectVersion (#6175)
@davidfischer: Add terms of service (#6174)
@davidfischer: Document connected account permissions (#6172)
@stsewd: Refactor views projects (#6171)
@dojutsu-user: Optimize json parsing (#6160)
@humitos: APIv3 endpoint: allow to modify a Project once it’s imported (#5952)

Version 3.7.5

Date:: September 26, 2019

@davidfischer: Remove if storage blocks (#6191)
@davidfischer: Update security docs (#6179)
@davidfischer: Add the private spamfighting module to INSTALLED_APPS (#6177)
@davidfischer: Document connected account permissions (#6172)
@stsewd: Require login for old redirect (#6170)
@humitos: Remove old and unused code (#6167)
@stsewd: Clean up views (#6166)
@stsewd: Update docs for sharing (#6164)
@pyup-bot: pyup: Scheduled weekly dependency update for week 36 (#6158)
@saadmk11: Remove PR Builder Project Idea from RTD GSoC Docs (#6147)
@ericholscher: Serialize time in search queries properly (#6142)
@humitos: Allow to extend DomainCreate view (#6139)
@saadmk11: Integration Re-sync Bug Fix (#6124)
@stsewd: Don’t log BuildEnvironmentWarning as error (#6112)
@dojutsu-user: Add Search Guide (#6101)
@saadmk11: Add PR Builder guide to docs (#6093)
@dojutsu-user: Record search queries smartly (#6088)
@dojutsu-user: Remove ‘highlight’ URL param from search results (#6087)

Version 3.7.4

Date:: September 05, 2019

@ericholscher: Remove paid support callout (#6140)
@ericholscher: Fix IntegrationAdmin with raw_id_fields for Projects (#6136)
@ericholscher: Fix link to html_extra_path (#6135)
@stsewd: Move out authorization from FooterHTML view (#6133)
@agjohnson: Add setting for always cleaning the build post-build (#6132)
@pyup-bot: pyup: Scheduled weekly dependency update for week 35 (#6129)
@stsewd: Refactor footer_html view to class (#6125)
@ericholscher: Use raw_id_fields in the TokenAdmin (#6116)
@davidfischer: Fixed footer ads supported on all themes (#6115)
@stsewd: Don’t log BuildEnvironmentWarning as error (#6112)
@pllim: Use the force when fetching with Git (#6109)
@dojutsu-user: Record search queries smartly (#6088)
@stsewd: Add move method to automation rule (#5998)
@dojutsu-user: Index more domain data into elasticsearch (#5979)

Version 3.7.3

Date:: August 27, 2019

@pllim: Use the force when fetching with Git (#6109)
@davidfischer: Small improvements to the SEO guide (#6105)
@davidfischer: Update intersphinx mapping with canonical sources (#6085)
@davidfischer: Fix lingering 500 issues (#6079)
@davidfischer: Technical docs SEO guide (#6077)
@saadmk11: GitLab Build Status Reporting for PR Builder (#6076)
@davidfischer: Update ad details docs (#6074)
@davidfischer: Gold makes projects ad-free again (#6073)
@saadmk11: Auto Sync and Re-Sync for Manually Created Integrations (#6071)
@pyup-bot: pyup: Scheduled weekly dependency update for week 32 (#6067)
@saadmk11: PR Builder GitLab Integration (#6066)
@davidfischer: Send media downloads to analytics (#6063)
@davidfischer: IPv6 in X-Forwarded-For fix (#6062)
@humitos: Remove warning about beta state of conda support (#6056)
@saadmk11: Update GitLab Webhook creating to enable merge request events (#6055)
@ericholscher: Release 3.7.2 (#6054)
@dojutsu-user: Update feature flags docs (#6053)
@saadmk11: Add indelx.html filename to the external doc url (#6051)
@dojutsu-user: Search analytics improvements (#6050)
@stsewd: Sort versions taking into consideration the vcs type (#6049)
@humitos: Avoid returning invalid domain when using USE_SUBDOMAIN=True in dev (#6026)
@dojutsu-user: Search analytics (#6019)
@tapaswenipathak: Remove django-guardian model (#6005)
@stsewd: Add manager and description field to AutomationRule model (#5995)
@davidfischer: Cleanup project tags (#5983)
@davidfischer: Search indexing with storage (#5854)
@wilvk: fix sphinx startup guide to not to fail on rtd build as per #2569 (#5753)

Version 3.7.2

Date:: August 08, 2019

@dojutsu-user: Update feature flags docs (#6053)
@saadmk11: Add indelx.html filename to the external doc url (#6051)
@dojutsu-user: Search analytics improvements (#6050)
@stsewd: Sort versions taking into consideration the vcs type (#6049)
@ericholscher: When called via SyncRepositoryTaskStep this doesn’t exist (#6048)
@davidfischer: Fix around community ads with an explicit ad placement (#6047)
@ericholscher: Release 3.7.1 (#6045)
@saadmk11: Do not delete media storage files for external version (#6035)
@tapaswenipathak: Remove django-guardian model (#6005)
@davidfischer: Cleanup project tags (#5983)
@davidfischer: Search indexing with storage (#5854)

Version 3.7.1

Date:: August 07, 2019

@pyup-bot: pyup: Scheduled weekly dependency update for week 31 (#6042)
@agjohnson: Fix issue with save on translation form (#6037)
@saadmk11: Do not delete media storage files for external version (#6035)
@saadmk11: Do not show wipe version message on build details page for External versions (#6034)
@saadmk11: Send site notification on Build status reporting failure and follow DRY (#6033)
@davidfischer: Use Read the Docs for Business everywhere (#6029)
@davidfischer: Remove project count on homepage (#6028)
@stsewd: Fix missing arg in tests (#6022)
@ericholscher: Update get_absolute_url for External Versions (#6020)
@dojutsu-user: Search analytics (#6019)
@saadmk11: Fix issues around remote repository for sending Build status reports (#6017)
@ericholscher: Expand the scope between before_vcs and after_vcs (#6015)
@davidfischer: Handle .x in version sorting (#6012)
@tapaswenipathak: Update note (#6008)
@davidfischer: Link to Read the Docs for Business docs from relevant sections (#6004)
@davidfischer: Note RTD for Biz requires SSL for custom domains (#6003)
@davidfischer: Allow searching in the Django Admin for gold (#6001)
@saadmk11: More explicit tests for build managers (#6000)
@dojutsu-user: Fix logic involving creation of Sphinx Domains (#5997)
@dojutsu-user: Fix: no highlighting of matched keywords in search results (#5994)
@saadmk11: Do not copy external version artifacts twice (#5992)
@saadmk11: Update GitHub build status details URL (#5987)
@humitos: Missing list.extend line when appending conda dependencies (#5986)
@saadmk11: Fix github build status reporting bug (#5985)
@dojutsu-user: Use try…catch block with underscore.js template. (#5984)
@davidfischer: Cleanup project tags (#5983)
@ericholscher: Release 3.7.0 (#5982)
@stsewd: More explicit tests for version managers (#5981)
@dojutsu-user: Search Fix: section_subtitle_link is not defined (#5980)
@stsewd: More explicit setup for tests (#5977)
@pyup-bot: pyup: Scheduled weekly dependency update for week 29 (#5975)
@stsewd: Update gitpython (#5974)
@davidfischer: Community only ads for more themes (#5973)
@darrowco: updated to psycopg2 (2.8.3) (#5965)
@humitos: Append core requirements to Conda environment file (#5956)
@humitos: Show APIv3 Token under Profile settings (#5954)
@stsewd: Remove skip submodules flag (#5406)

Version 3.7.0

Date:: July 23, 2019

@dojutsu-user: Search Fix: section_subtitle_link is not defined (#5980)
@stsewd: More explicit setup for tests (#5977)
@stsewd: Update gitpython (#5974)
@davidfischer: Community only ads for more themes (#5973)
@kittenking: Fix typos across readthedocs.org repository (#5971)
@dojutsu-user: Fix: parse_json also including html in titles (#5970)
@saadmk11: update external version check for notification task (#5969)
@pranay414: Improve error message for invalid submodule URLs (#5957)
@humitos: Append core requirements to Conda environment file (#5956)
@Abhi-khandelwal: Exclude Spam projects count from total_projects count (#5955)
@humitos: Show APIv3 Token under Profile settings (#5954)
@ericholscher: Release 3.6.1 (#5953)
@ericholscher: Missed a couple places to set READTHEDOCS_LANGUAGE (#5951)
@dojutsu-user: Hotfix: Return empty dict when no highlight dict is present (#5950)
@humitos: Use a cwd where the user has access inside the container (#5949)
@saadmk11: Small Changes to PR Builder Code (#5948)
@saadmk11: update build status message for github (#5947)
@ericholscher: Integrate indoc search into our prod docs (#5946)
@ericholscher: Explicitly delete SphinxDomain objects from previous versions (#5945)
@ericholscher: Properly return None when there’s no highlight on a hit. (#5944)
@ericholscher: Add READTHEDOCS_LANGUAGE to the environment during builds (#5941)
@ericholscher: Merge the GSOC 2019 in-doc search changes (#5919)
@saadmk11: Add check for external version in conf.py.tmpl for warning banner (#5900)
@Abhi-khandelwal: Point users to commercial solution for their private repositories (#5849)
@ericholscher: Merge initial work from Pull Request Builder GSOC (#5823)

Version 3.6.1

Date:: July 17, 2019

@ericholscher: Missed a couple places to set READTHEDOCS_LANGUAGE (#5951)
@dojutsu-user: Hotfix: Return empty dict when no highlight dict is present (#5950)
@humitos: Use a cwd where the user has access inside the container (#5949)
@saadmk11: Small Changes to PR Builder Code (#5948)
@ericholscher: Explicitly delete SphinxDomain objects from previous versions (#5945)
@ericholscher: Properly return None when there’s no highlight on a hit. (#5944)
@ericholscher: Release 3.6.0 (#5943)
@ericholscher: Bump the Sphinx extension to 1.0 (#5942)
@ericholscher: Add READTHEDOCS_LANGUAGE to the environment during builds (#5941)
@dojutsu-user: Small search doc fix (#5940)
@dojutsu-user: Indexing speedup (#5939)
@dojutsu-user: Small improvement in parse_json (#5938)
@dojutsu-user: Use attrgetter in sorted function (#5936)
@saadmk11: Refine PR Builder Code (#5933)
@dojutsu-user: Fix spacing between the results and add highlight url param (#5932)
@ericholscher: Merge the GSOC 2019 in-doc search changes (#5919)
@dojutsu-user: Add tests for section-linking (#5918)
@saadmk11: Update build list and detail page UX (#5916)
@humitos: APIv3 endpoint to manage Environment Variables (#5913)
@humitos: Split APIv3 tests on different files (#5911)
@stsewd: Better msg when gitpython fails (#5903)
@saadmk11: Add check for external version in conf.py.tmpl for warning banner (#5900)
@humitos: Update APIv3 documentation with latest changes (#5895)

Version 3.6.0

Date:: July 16, 2019

@ericholscher: Bump the Sphinx extension to 1.0 (#5942)
@ericholscher: Add READTHEDOCS_LANGUAGE to the environment during builds (#5941)
@dojutsu-user: Small search doc fix (#5940)
@dojutsu-user: Indexing speedup (#5939)
@dojutsu-user: Small improvement in parse_json (#5938)
@dojutsu-user: Use attrgetter in sorted function (#5936)
@saadmk11: Refine PR Builder Code (#5933)
@dojutsu-user: Fix spacing between the results and add highlight url param (#5932)
@Abhi-khandelwal: remove the usage of six (#5930)
@dojutsu-user: Fix count value of docsearch REST api (#5926)
@ericholscher: Merge the GSOC 2019 in-doc search changes (#5919)
@dojutsu-user: Add tests for section-linking (#5918)
@saadmk11: Update build list and detail page UX (#5916)
@humitos: These Project’s methods are not used (#5915)
@saadmk11: Github Status reporting Test fix (#5914)
@humitos: APIv3 endpoint to manage Environment Variables (#5913)
@humitos: Split APIv3 tests on different files (#5911)
@saadmk11: Add Feature Flag to Enable External Version Building (#5910)
@ericholscher: Pass the build_pk to the task instead of the build object itself (#5904)
@stsewd: Better msg when gitpython fails (#5903)
@saadmk11: Exclude external versions from get_latest_build (#5901)
@humitos: Update conda at startup (#5897)
@humitos: Update APIv3 documentation with latest changes (#5895)
@stsewd: Add tests for version and project querysets (#5894)
@davidfischer: Rework on documentation guides (#5893)
@humitos: Lint (pep257: D415) (#5892)
@davidfischer: Fix spaces in email subject link (#5891)
@saadmk11: Build only HTML and Save external version artifacts in different directory (#5886)
@humitos: APIv3 CRUD for Redirect objects (#5879)
@ericholscher: Add config to Build and Version admin (#5877)
@pyup-bot: pyup: Scheduled weekly dependency update for week 26 (#5874)
@stsewd: Call distinct to the end of the querysets (#5872)
@pranay414: Change rtfd to readthedocs (#5871)
@humitos: APIv3 refactor some fields (#5868)
@saadmk11: Send Build Status Report Using GitHub Status API (#5865)
@humitos: APIv3 “Import Project” endpoint (#5857)
@stsewd: Remove django guardian from querysets (#5853)
@humitos: Hide “Protected” privacy level from users (#5833)
@dojutsu-user: Add section linking for the search result (#5829)

Version 3.5.3

Date:: June 19, 2019

@davidfischer: Treat docs warnings as errors (#5825)
@davidfischer: Fix some unclear verbiage (#5820)
@davidfischer: Rework documentation index page (#5819)
@davidfischer: Upgrade intersphinx to Django 1.11 (#5818)
@pyup-bot: pyup: Scheduled weekly dependency update for week 24 (#5817)
@humitos: Disable changing domain when editing the object (#5816)
@saadmk11: Update docs with sitemap sort order change (#5815)
@davidfischer: Optimize requests to APIv3 (#5803)
@ericholscher: Show build length in the admin (#5802)
@stsewd: Move search functions (#5801)
@ericholscher: A few small improvements to help with search admin stuff (#5800)
@stsewd: Simplify es indexing (#5798)
@humitos: Use a real SessionBase object on FooterNoSessionMiddleware (#5797)
@stsewd: Add logging in magic methods (#5795)
@stsewd: Fix unbound var in search view (#5794)
@davidfischer: Mention security issue in the changelog (#5790)
@stsewd: Index path with original path name (#5785)
@stsewd: Use querysets from the class not from an instance (#5783)
@saadmk11: Add Build managers and Update Build Querysets. (#5779)
@davidfischer: Project advertising page/form update (#5777)
@davidfischer: Update docs around opt-out of ads (#5776)
@saadmk11: Sitemap sort order priorities updated (#5724)
@dojutsu-user: [Design Doc] In Doc Search UI (#5707)
@saadmk11: Pull Request Builder Design Doc (#5705)
@humitos: Support single version subprojects URLs to serve from Django (#5690)
@agjohnson: Add a contrib Dockerfile for local build image on Linux (#4608)

Version 3.5.2

This is a quick hotfix to the previous version.

Date:: June 11, 2019

@ericholscher: Fix version of our sphinx-ext we’re installing (#5789)
@stsewd: Get version from the api (#5788)

Version 3.5.1

This version contained a security fix for an open redirect issue. The problem has been fixed and deployed on readthedocs.org. For users who depend on the Read the Docs code line for a private instance of Read the Docs, you are encouraged to update to 3.5.1 as soon as possible.

Date:: June 11, 2019

@stsewd: Update build images in docs (#5782)
@saadmk11: Validate dict when parsing the mkdocs.yml file (#5775)
@stsewd: Pin textclassifier dependencies (#5773)
@stsewd: Fix tests on master (#5769)
@stsewd: Don’t use implicit relative import (#5767)
@stsewd: Use version_pk to trigger builds (#5765)
@davidfischer: Domain UI improvements (#5764)
@ericholscher: Try to fix Elastic connection pooling issues (#5763)
@pyup-bot: pyup: Scheduled weekly dependency update for week 22 (#5762)
@ericholscher: Try to fix Elastic connection pooling issues (#5760)
@davidfischer: Escape variables in mkdocs data (#5759)
@humitos: Serve 404/index.html file for htmldir Sphinx builder (#5754)
@wilvk: fix sphinx startup guide to not to fail on rtd build as per #2569 (#5753)
@stsewd: Fix mkdocs relpath (#5749)
@stsewd: Call lock per task (#5748)
@stsewd: Pin kombu to 4.3.0 (#5747)
@agjohnson: Clarify latexmk option usage (#5745)
@ericholscher: Hotfix latexmx builder to ignore error codes (#5744)
@ericholscher: Hide the Code API search in the UX for now. (#5743)
@davidfischer: Add init.py under readthedocs/api (#5742)
@dojutsu-user: Fix design docs missing from toctree (#5741)
@ericholscher: Release 3.5.0 (#5740)
@saadmk11: Pytest Timezone Warning Fixed (#5739)
@humitos: Filter by projects with no banned users (#5733)
@davidfischer: Fix the sidebar ad color (#5731)
@saadmk11: Permanent redirect feature added (#5727)
@humitos: Move version “Clean” button to details page (#5706)
@gorshunovr: Update flags documentation (#5701)
@davidfischer: Storage updates (#5698)
@stsewd: Remove files after build (#5680)
@stsewd: Move community support to email (#5651)
@davidfischer: Optimizations and UX improvements to the dashboard screen (#5637)
@chrisjsewell: Use --upgrade instead of --force-reinstall for pip installs (#5635)
@stsewd: Move file validations out of the config module (#5627)
@humitos: Remove old/deprecated build endpoints (#5479)
@shivanshu1234: Add link to in-progress build from dashboard. (#5431)
@stsewd: Downgrade pytest-django (#5294)

Version 3.5.0

Date:: May 30, 2019

@pyup-bot: pyup: Scheduled weekly dependency update for week 21 (#5737)
@humitos: Update feature flags exposed to user in docs (#5734)
@davidfischer: Fix the sidebar ad color (#5731)
@davidfischer: Create a funding file (#5729)
@davidfischer: Small commercial hosting page rework (#5728)
@mattparrilla: Add note about lack of support for private repos (#5726)
@humitos: Canonical consistency example (#5722)
@humitos: Use nonstopmode for latexmk (#5714)
@cclauss: Identity is not the same thing as equality in Python (#5713)
@pyup-bot: pyup: Scheduled weekly dependency update for week 20 (#5712)
@humitos: Move version “Clean” button to details page (#5706)
@ericholscher: Explicitly mention a support email (#5703)
@davidfischer: Storage updates (#5698)
@humitos: Enable auth validate passwords (#5696)
@stsewd: Simplify lock acquire (#5695)
@stsewd: Simplify update docs task (#5694)
@pyup-bot: pyup: Scheduled weekly dependency update for week 19 (#5692)
@saadmk11: Warning about using sqlite 3.26.0 for development (#5681)
@davidfischer: Configure the security middleware (#5679)
@stsewd: Fix bug in notifications (#5678)
@pyup-bot: pyup: Scheduled weekly dependency update for week 18 (#5667)
@saadmk11: pylint fix for notifications, restapi and config (#5664)
@saadmk11: pylint fix for readthedocs.search (#5663)
@saadmk11: pylint fix for readthedocs.projects (#5662)
@saadmk11: pylint fix for readthedocs.doc_builder (#5660)
@humitos: Support Docker 5.0 image (#5657)
@humitos: Use latexmk if Sphinx > 1.6 (#5656)
@humitos: Upgrade docker python package to latest release (#5654)
@saadmk11: pylint fix for readthedocs.core (#5650)
@pyup-bot: pyup: Scheduled weekly dependency update for week 17 (#5645)
@saadmk11: Serve custom 404 pages from Django (#5644)
@yarons: Typo fix (#5642)
@saadmk11: Sitemap hreflang syntax invalid for regional language variants fix (#5638)
@davidfischer: Optimizations and UX improvements to the dashboard screen (#5637)
@davidfischer: Redirect project slugs with underscores (#5634)
@saadmk11: Standardizing the use of settings directly (#5632)
@saadmk11: Note for Docker image size in Docker instructions (#5630)
@davidfischer: UX improvements around SSL certificates (#5629)
@davidfischer: Gold project sponsorship changes (#5628)
@davidfischer: Make sure there’s a contact when opting out of advertising (#5626)
@stsewd: Remove unused volume from docker (#5625)
@dojutsu-user: hotfix: correct way of getting environment variables (#5622)
@pyup-bot: pyup: Scheduled weekly dependency update for week 16 (#5619)
@ericholscher: Release 3.4.2 (#5613)
@ericholscher: Add explicit egg version to unicode-slugify (#5612)
@dojutsu-user: Remove ProxyMiddleware (#5607)
@dojutsu-user: Remove ‘Versions’ tab from Admin Dashboard. (#5600)
@dojutsu-user: Notify the user when deleting a superproject (#5596)
@saadmk11: Handle 401, 403 and 404 when setting up webhooks (#5589)
@saadmk11: Unify usage of settings and remove the usage of getattr for settings (#5588)
@saadmk11: Note about admin page in the docs (#5585)
@humitos: Remove USE_SETUPTOOLS_LATEST feature flag (#5578)
@saadmk11: Validate docs dir before writing custom js (#5569)
@rshrc: Added note in YAML docs (#5565)
@shivanshu1234: Specify python3 in installation instructions. (#5552)
@davidfischer: Write build artifacts to (cloud) storage from build servers (#5549)
@saadmk11: “Default branch: latest” does not exist Fix. (#5547)
@dojutsu-user: Update readthedocs-environment.json file when env vars are added/deleted (#5540)
@humitos: Update common to its latest version (#5517)
@saadmk11: Profile page performance issue Fix (#5472)
@stsewd: Remove unused form (#5443)
@stsewd: Use relative paths in config module (#5377)
@humitos: Initial structure for APIv3 (#5356)
@stsewd: Add models for automation rules (#5323)
@stsewd: Downgrade pytest-django (#5294)
@ericholscher: Add search for DomainData objects (#5290)
@gorshunovr: Change version references to :latest tag (#5245)
@dojutsu-user: Fix buttons problems in ‘Change Email’ section. (#5219)

Version 3.4.2

Date:: April 22, 2019

@ericholscher: Add explicit egg version to unicode-slugify (#5612)
@saadmk11: Update Environmental Variable character limit (#5597)
@davidfischer: Add meta descriptions to top documentation (#5593)
@stsewd: Ignore pytest-xdist from pyupdate (#5590)
@saadmk11: Note about admin page in the docs (#5585)
@pyup-bot: pyup: Scheduled weekly dependency update for week 14 (#5580)
@stsewd: Use downloads.html in template (#5579)
@ihnorton: Fix typo in conda.rst (#5576)
@davidfischer: Fix for Firefox to close the ad correctly (#5571)
@davidfischer: Non mobile fixed footer ads (#5567)
@ericholscher: Release 3.4.1 (#5566)
@dojutsu-user: Update readthedocs-environment.json file when env vars are added/deleted (#5540)
@stsewd: Allow build mkdocs outside root (#5539)
@saadmk11: Sitemap assumes that all versions are translated Fix. (#5535)
@saadmk11: Remove Header Login button from login page (#5534)
@davidfischer: Optimize database performance of the footer API (#5530)
@stsewd: Don’t depend of enabled pdf/epub to show downloads (#5502)
@saadmk11: Don’t allow to create subprojects with same alias (#5404)
@saadmk11: Improve project translation listing Design under admin tab (#5380)

Version 3.4.1

Date:: April 03, 2019

@pyup-bot: pyup: Scheduled weekly dependency update for week 13 (#5558)
@stsewd: Fix advanced settings form (#5544)
@stsewd: Call mkdocs using -m (#5542)
@stsewd: Allow build mkdocs outside root (#5539)
@stsewd: Use patch method to update has_valid_clone (#5538)
@pyup-bot: pyup: Scheduled weekly dependency update for week 12 (#5536)
@saadmk11: Sitemap assumes that all versions are translated Fix. (#5535)
@saadmk11: Remove Header Login button from login page (#5534)
@stevepiercy: Add pylons-sphinx-themes to list of supported themes (#5533)
@davidfischer: Optimize database performance of the footer API (#5530)
@stsewd: Fix extra origin in urls (#5523)
@davidjb: Update contributing docs for RTD’s own docs (#5522)
@davidjb: Use HTTPS for intersphinx mappings (#5521)
@davidjb: Fix formatting for CentOS/RHEL installs (#5520)
@davidfischer: Guide users to the YAML config from the build detail page (#5519)
@davidjb: Add to and reorder GitHub webhook docs (#5514)
@stsewd: Link to the docdir of the remote repo in non-rtd themes for mkdocs (#5513)
@stevepiercy: Tidy up grammar, promote Unicode characters (#5511)
@stsewd: Catch specific exception for config not found (#5510)
@dojutsu-user: Use ValueError instead of InvalidParamsException (#5509)
@humitos: Force Sphinx to not use xindy (#5507)
@stsewd: Update mkdocs (#5505)
@stsewd: Don’t depend of enabled pdf/epub to show downloads (#5502)
@ericholscher: Remove search & API from robots.txt (#5501)
@saadmk11: Make /random/ path work (#5496)
@humitos: Typo on conf.py.tmpl (#5495)
@rshrc: Added note warning about using sqlite 3.26.0 in development (#5491)
@stsewd: Regroup advanced settings (#5489)
@ericholscher: Fix bug that caused search objects not to delete (#5487)
@ericholscher: Release 3.4.0 (#5486)
@davidfischer: Promote the YAML config (#5485)
@pyup-bot: pyup: Scheduled weekly dependency update for week 11 (#5483)
@saadmk11: Dashboard screen performance fix (#5471)
@saadmk11: Build List Screen Performance Issue Fix. (#5470)
@saadmk11: Remove Haystack reference in Docs (#5469)
@davidfischer: Enable Django Debug Toolbar in development (#5464)
@davidfischer: Optimize the version list screen (#5460)
@stsewd: Regroup settings (#5459)
@humitos: Guide to build PDF for non-ASCII language (#5453)
@dojutsu-user: Remove asserts from code. (#5452)
@davidfischer: Optimize the repos API query (#5451)
@stsewd: Update version of setuptools (#5450)
@stsewd: Remove unused validator (#5442)
@humitos: Build PDF files using latexmk (#5437)
@stsewd: Always update the commit of the stable version (#5421)
@stsewd: Share doctree between builders (#5407)
@stsewd: Remove unused template (#5401)
@orlnub123: Fix pip installs (#5386)
@davidfischer: Add an application form for community ads (#5379)

Version 3.4.0

Date:: March 18, 2019

@davidfischer: Promote the YAML config (#5485)
@saadmk11: Dashboard screen performance fix (#5471)
@saadmk11: Build List Screen Performance Issue Fix. (#5470)
@saadmk11: Remove Haystack reference in Docs (#5469)
@mashrikt: gitignore dev.db-journal file #5463 (#5466)
@davidfischer: Enable Django Debug Toolbar in development (#5464)
@davidfischer: Optimize the version list screen (#5460)
@stsewd: Regroup settings (#5459)
@Mariatta: Fix typo: leave the field black -> blank (#5457)
@stsewd: Use Ubuntu xenial on travis (#5456)
@dojutsu-user: Update links to point to stable version. (#5455)
@dojutsu-user: Fix inconsistency in footer links (#5454)
@davidfischer: Optimize the repos API query (#5451)
@stsewd: Update version of setuptools (#5450)
@stsewd: Remove unused validator (#5442)
@humitos: Build PDF files using latexmk (#5437)
@pyup-bot: pyup: Scheduled weekly dependency update for week 10 (#5432)
@shivanshu1234: Remove invalid example from v2.rst (#5430)
@saadmk11: Removed unused constant from core.models (#5424)
@stsewd: Fix reraise of exception (#5423)
@stsewd: Always update the commit of the stable version (#5421)
@stsewd: Fix warnings in code (#5419)
@stsewd: Refactor move_files (#5418)
@agarwalrounak: Document that people can create a version named stable (#5417)
@agarwalrounak: Update installation guide to include submodules (#5416)
@stsewd: Update docs for building with markdown (#5415)
@stsewd: Share doctree between builders (#5407)
@humitos: Communicate the project slug can be changed by requesting it (#5403)
@stsewd: Remove unused template (#5401)
@stsewd: Remove view docs dropdown (#5400)
@humitos: Minimum upgrade of the builds docs (#5398)
@stsewd: Update internal requirements (#5396)
@pyup-bot: pyup: Scheduled weekly dependency update for week 09 (#5395)
@dojutsu-user: Trigger build on default branch when saving a project (#5393)
@Mike-Dai: Removed un-needed python dependencies (#5389)
@orlnub123: Fix pip installs (#5386)
@rshrc: Addressed Issue #5327 (#5383)
@ericholscher: Be extra explicit about the CNAME (#5382)
@stsewd: Better MkDocs integration as GSoC idea (#5378)
@ericholscher: Release 3.3.1 (#5376)
@ericholscher: Add a GSOC section for openAPI (#5375)
@dojutsu-user: Make ‘default_version` field as readonly if no active versions are found. (#5374)
@ericholscher: Be more defensive with our storage uploading (#5371)
@ericholscher: Check for two paths for each file (#5370)
@ericholscher: Don’t show projects in Sphinx Domain Admin sidebar (#5367)
@stsewd: Start building with sphinx 1.8 (#5366)
@saadmk11: Remove pytest warnings (#5346)
@davidfischer: Remove the v1 API (#5293)
@stsewd: Remove doctype from resolver (#5230)
@humitos: Implementation of APIv3 (#4863)

Version 3.3.1

Date:: February 28, 2019

@ericholscher: Be more defensive with our storage uploading (#5371)
@ericholscher: Check for two paths for each file (#5370)
@stsewd: Protect against anchors with # (#5369)
@ericholscher: Don’t show projects in Sphinx Domain Admin sidebar (#5367)
@ericholscher: Fix sphinx domain models and migrations (#5363)
@stsewd: Try to put back codecov integration (#5362)
@ericholscher: Release 3.3.0 (#5361)
@ericholscher: Fix search bug when an empty list of objects_id was passed (#5357)
@dojutsu-user: Add admin methods for reindexing versions from project and version admin. (#5343)
@stsewd: Cleanup a little of documentation_type from footer (#5315)
@ericholscher: Add modeling for intersphinx data (#5289)
@stsewd: Remove doctype from resolver (#5230)
@stsewd: Validate webhook’s payload (#4940)
@stsewd: Start testing config v2 on our project (#4838)
@ericholscher: Revert “Merge pull request #4636 from readthedocs/search_upgrade” (#4716)
@safwanrahman: [GSoC 2018] All Search Improvements (#4636)
@stsewd: Add schema for configuration file with yamale (#4084)
@stsewd: Add note about mercurial on tests (#3358)

Version 3.3.0

Date:: February 27, 2019

@ericholscher: Fix search bug when an empty list of objects_id was passed (#5357)
@agjohnson: Update UI translations (#5354)
@ericholscher: Update GSOC page to mention we’re accepted. (#5353)
@pyup-bot: pyup: Scheduled weekly dependency update for week 08 (#5352)
@dojutsu-user: Increase path’s max_length for ImportedFile model to 4096 (#5345)
@saadmk11: improvement on inserting mkdocs media (#5344)
@dojutsu-user: Add admin methods for reindexing versions from project and version admin. (#5343)
@stsewd: Initialize local variable before using it (#5342)
@dojutsu-user: Remove deprecated code (#5341)
@stsewd: Require conda.file when using conda in v1 (#5338)
@stsewd: Remove unused setting (#5336)
@stsewd: Fix comment (#5329)
@stsewd: Don’t depend on specific data when catching exception (#5326)
@regisb: Fix “clean_builds” command argument parsing (#5320)
@stsewd: Cleanup a little of documentation_type from footer (#5315)
@humitos: Warning note about running ES locally for tests (#5314)
@humitos: Update documentation on running test for python environment (#5313)
@ericholscher: Release 3.2.3 (#5312)
@ericholscher: Add basic auth to the generic webhook API. (#5311)
@ericholscher: Fix an issue where we were not properly filtering projects (#5309)
@stsewd: Rstrip repo url (#5308)
@rexzing: Incompatible dependency for prospector with pylint-django (#5306)
@davidfischer: Allow extensions to control URL structure (#5296)
@stsewd: Downgrade pytest-django (#5294)
@ericholscher: Add modeling for intersphinx data (#5289)
@ovc: Tweek css for sphinx_prompt (#5281)
@saadmk11: #4036 Updated build list to include an alert state (#5222)
@humitos: Use unicode-slugify to generate Version.slug (#5186)
@dojutsu-user: Add admin functions for wiping a version (#5140)
@humitos: Generate general sitemap.xml for projects (#5122)
@humitos: Logging exceptions rework (#5118)
@davidfischer: Store ePubs and PDFs in media storage (#4947)
@stsewd: Validate webhook’s payload (#4940)
@ericholscher: Revert “Merge pull request #4636 from readthedocs/search_upgrade” (#4716)
@safwanrahman: [GSoC 2018] All Search Improvements (#4636)

Version 3.2.3

Date:: February 19, 2019

@ericholscher: Add basic auth to the generic webhook API. (#5311)
@ericholscher: Fix an issue where we were not properly filtering projects (#5309)
@stsewd: Rstrip repo url (#5308)
@stsewd: Use autosectionlabel for docs in security (#5307)
@rexzing: Incompatible dependency for prospector with pylint-django (#5306)
@pyup-bot: pyup: Scheduled weekly dependency update for week 07 (#5305)
@davidfischer: Allow extensions to control URL structure (#5296)
@stsewd: Downgrade pytest-django (#5294)
@rexzing: Docs reformatting with :guilabel: (#5161)

Version 3.2.2

Date:: February 13, 2019

@ericholscher: Support old jquery where responseJSON doesn’t exist (#5285)
@humitos: pyup.yml syntax fixed (#5284)
@dojutsu-user: Fix error of travis (rename migration file) (#5282)
@humitos: pyup YAML configuration file (#5279)
@pyup-bot: Pin ipdb to latest version 0.11 (#5278)
@pyup-bot: Pin datadiff to latest version 2.0.0 (#5277)
@pyup-bot: Pin pytest-cov to latest version 2.6.1 (#5276)
@pyup-bot: Pin pillow to latest version 5.4.1 (#5275)
@pyup-bot: Update elasticsearch to 6.3.1 (#5274)
@discdiver: clarify github integration needs https:// prepended (#5273)
@humitos: Setup and configure pyup.io (#5272)
@humitos: Update all Python dependencies (#5269)
@davidfischer: Add note about security issue (#5263)
@ericholscher: Don’t delay search delete on project delete (#5262)
@agjohnson: Automate docs version from our setup.cfg (#5259)
@agjohnson: Add admin actions for building versions (#5255)
@ericholscher: Give the 404 page a title. (#5252)
@humitos: Make our SUFFIX default selection py2/3 compatible (#5251)
@ericholscher: Release 3.2.1 (#5248)
@ericholscher: Remove excluding files on search. (#5246)
@gorshunovr: Change version references to :latest tag (#5245)
@humitos: Remove py2 compatibility (#5241)
@stsewd: Allow to override trigger_build from demo project (#5236)
@ericholscher: Change some info logging to debug to clean up build output (#5233)
@stsewd: Fake auth middleware in tests (#5206)
@EJEP: Clarify ‘more info’ link in admin settings page (#5180)
@rexzing: Docs reformatting with :guilabel: (#5161)

Version 3.2.1

Date:: February 07, 2019

@ericholscher: Remove excluding files on search. (#5246)
@ericholscher: Don’t update search on HTMLFile save (#5244)
@ericholscher: Be more defensive in our 404 handler (#5243)
@humitos: Install sphinx-notfound-page for building 404.html custom page (#5242)
@humitos: Remove py2 compatibility (#5241)
@ericholscher: Release 3.2.0 (#5240)

Version 3.2.0

Date:: February 06, 2019

@ericholscher: Support passing an explicit index_name for search indexing (#5239)
@davidfischer: Tweak some ad styles (#5237)
@stsewd: Fix conda issue link (#5226)
@humitos: Add Santos to the development team (#5224)
@ericholscher: Update our GSOC page for 2019 (#5210)
@humitos: Do not allow to merge ‘Status: blocked’ PRs (#5205)
@stsewd: Inject user to middleware tests (#5203)
@ericholscher: Remove approvals requirement from mergeable (#5200)
@agjohnson: Update project notification copy to past tense (#5199)
@stsewd: Remove feature flag for v2 (#5198)
@ericholscher: Refactor search code (#5197)
@stsewd: Update mergeable settings to v2 (#5196)
@stsewd: Fix mergeable bot (#5195)
@stsewd: Fix broken links for badges (#5190)
@dojutsu-user: Change badge style (#5189)
@humitos: Allow source_suffix to be a dictionary (#5183)
@humitos: Upgrade all packages removing py2 compatibility (#5179)
@dojutsu-user: Small docs fix (#5176)
@stsewd: Sync all services even if one social accoun fails (#5171)
@ericholscher: Release 3.1.0 (#5170)
@rvmzes: SyntaxError caused by comma in python3 (#5156)
@humitos: Use latest docker images as default (#5155)
@stsewd: Remove logic for guessing slug from an unregistered domain (#5143)
@humitos: Allow custom 404.html on projects (#5130)
@dojutsu-user: Docs for feature flag (#5043)
@stsewd: Remove usage of project.documentation_type in tasks (#4896)
@ericholscher: Reapply the Elastic Search upgrade to master (#4722)
@stsewd: Config file v2 docs (#4451)
@stsewd: Set python3 as default interpreter (#3581)

Version 3.1.0

This version greatly improves our search capabilities, thanks to the Google Summer of Code. We’re hoping to have another version of search coming soon after this, but this is a large upgrade moving to the latest Elastic Search.

Date:: January 24, 2019

@ericholscher: Fix docs build (#5164)
@ericholscher: Release 3.0.0 (#5163)
@stsewd: Fix tests on master (#5162)
@dojutsu-user: Sort versions smartly everywhere (#5157)
@stsewd: Allow query params in redirects (#5081)
@dojutsu-user: Implement get objects or log (#4900)
@stsewd: Remove usage of project.documentation_type in tasks (#4896)
@ericholscher: Reapply the Elastic Search upgrade to master (#4722)

Version 3.0.0

Read the Docs now only supports Python 3.6+. This is for people running the software on their own servers, builds continue to work across all supported Python versions.

Date:: January 23, 2019

@stsewd: Fix tests on master (#5162)
@dojutsu-user: Sort versions smartly everywhere (#5157)
@rvmzes: SyntaxError caused by comma in python3 (#5156)
@ericholscher: Fix Sphinx conf.py inserts (#5150)
@ericholscher: Upgrade recommonmark to latest and fix integration (#5146)
@stsewd: Fix requirements for local installation (#5138)
@ericholscher: Fix local-docs-build requirements (#5136)
@humitos: Upgrade all dependencies (#5134)
@humitos: Configuration file for ProBot Mergeable Bot (#5132)
@xavfernandez: docs: fix integration typos (#5128)
@Hamdy722: Update LICENSE (#5125)
@stsewd: Remove doctype from search (#5121)
@humitos: Validate mkdocs.yml config on values that we manipulate (#5119)
@humitos: Use 2019 in our README (#5117)
@stsewd: Remove dead code from config module (#5116)
@ericholscher: Check that the repo exists before trying to get a git commit (#5115)
@ericholscher: Release 2.8.5 (#5111)
@stsewd: Use the python path from virtualenv in Conda (#5110)
@humitos: Feature flag to use readthedocs/build:testing image (#5109)
@stsewd: Use python from virtualenv’s bin directory when executing commands (#5107)
@dojutsu-user: Split requirements/pip.txt (#5100)
@humitos: Do not list banned projects under /projects/ (#5097)
@humitos: Do not build projects from banned users (#5096)
@humitos: Support custom robots.txt (#5086)
@stsewd: Allow query params in redirects (#5081)
@davidfischer: Fire a signal for domain verification (eg. for SSL) (#5071)
@humitos: Upgrade all code to be Python3 only (#5065)
@dojutsu-user: Use default settings for Config object (#5056)
@agjohnson: Allow large form posts via multipart encoded forms to command API (#5000)
@dojutsu-user: Validate url from webhook notification (#4983)
@dojutsu-user: Display error, using inbuilt notification system, if primary email is not verified (#4964)
@dojutsu-user: Implement get objects or log (#4900)
@humitos: CRUD for EnvironmentVariables from Project’s admin (#4899)
@stsewd: Remove usage of project.documentation_type in tasks (#4896)
@dojutsu-user: Fix the failing domain deletion task (#4891)
@stsewd: Remove unused validations from v1 config (#4883)
@humitos: Appropriate logging when a LockTimeout for VCS is reached (#4804)
@stsewd: Implement extended install option (#4740)
@bansalnitish: Added a link to open new issue with prefilled details (#3683)

Version 2.8.5

Date:: January 15, 2019

@stsewd: Use the python path from virtualenv in Conda (#5110)
@humitos: Feature flag to use readthedocs/build:testing image (#5109)
@stsewd: Use python from virtualenv’s bin directory when executing commands (#5107)
@humitos: Do not build projects from banned users (#5096)
@agjohnson: Fix common pieces (#5095)
@rainwoodman: Suppress progress bar of the conda command. (#5094)
@humitos: Remove unused suggestion block from 404 pages (#5087)
@humitos: Remove header nav (Login/Logout button) on 404 pages (#5085)
@stsewd: Fix little typo (#5084)
@agjohnson: Split up deprecated view notification to GitHub and other webhook endpoints (#5083)
@humitos: Install ProBot (#5082)
@stsewd: Update docs about contributing to docs (#5077)
@humitos: Declare and improve invoke tasks (#5075)
@davidfischer: Fire a signal for domain verification (eg. for SSL) (#5071)
@agjohnson: Update copy on notifications for github services deprecation (#5067)
@humitos: Upgrade all packages with pur (#5059)
@dojutsu-user: Reduce logging to sentry (#5054)
@discdiver: fixed missing apostrophe for possessive “project’s” (#5052)
@dojutsu-user: Template improvements in “gold/subscription_form.html” (#5049)
@merwok: Fix link in features page (#5048)
@stsewd: Update webhook docs (#5040)
@stsewd: Remove sphinx static and template dir (#5039)
@stephenfin: Add temporary method for disabling shallow cloning (#5031) (#5036)
@stsewd: Raise exception in failed checkout (#5035)
@dojutsu-user: Change default_branch value from Version.slug to Version.identifier (#5034)
@humitos: Make wipe view not CSRF exempt (#5025)
@humitos: Convert an IRI path to URI before setting as NGINX header (#5024)
@safwanrahman: index project asynchronously (#5023)
@stsewd: Keep command output when it’s killed (#5015)
@stsewd: More hints for invalid submodules (#5012)
@ericholscher: Release 2.8.4 (#5011)
@stsewd: Remove auto doctype (#5010)
@davidfischer: Tweak sidebar ad priority (#5005)
@stsewd: Replace git status and git submodules status for gitpython (#5002)
@davidfischer: Backport jquery 2432 to Read the Docs (#5001)
@stsewd: Refactor remove_dir (#4994)
@humitos: Skip builds when project is not active (#4991)
@dojutsu-user: Make $ unselectable in docs (#4990)
@dojutsu-user: Remove deprecated “models.permalink” (#4975)
@dojutsu-user: Add validation for tags of length greater than 100 characters (#4967)
@dojutsu-user: Add test case for send_notifications on VersionLockedError (#4958)
@dojutsu-user: Remove trailing slashes on svn checkout (#4951)
@stsewd: Safe symlink on version deletion (#4937)
@humitos: CRUD for EnvironmentVariables from Project’s admin (#4899)
@humitos: Notify users about the usage of deprecated webhooks (#4898)
@dojutsu-user: Disable django guardian warning (#4892)
@humitos: Handle 401, 403 and 404 status codes when hitting GitHub for webhook (#4805)

Version 2.8.4

Date:: December 17, 2018

@davidfischer: Tweak sidebar ad priority (#5005)
@davidfischer: Backport jquery 2432 to Read the Docs (#5001)
@ericholscher: Remove codecov comments and project coverage CI status (#4996)
@stsewd: Remove LOCAL_GIT_BRANCHES from settings (#4993)
@dojutsu-user: Link update on FAQ page (#4988)
@ericholscher: Only use remote branches for our syncing. (#4984)
@humitos: Sanitize output and chunk it at DATA_UPLOAD_MAX_MEMORY_SIZE (#4982)
@humitos: Modify DB field for container_time_limit to be an integer (#4979)
@dojutsu-user: Remove deprecated imports from “urlresolvers” (#4976)
@davidfischer: Workaround for a django-storages bug (#4963)
@ericholscher: Release 2.8.3 (#4961)
@monsij: Remove -e option (#4960)
@nutann3: Update “install Sphinx” URL (#4959)
@stsewd: Shallow git clone (#4939)
@dojutsu-user: Validate profile form fields (#4910)
@davidfischer: Calculate actual ad views (#4885)
@humitos: Allow all /api/v2/ CORS if the Domain is known (#4880)
@dojutsu-user: Disable django.security.DisallowedHost from logging (#4879)
@dojutsu-user: Remove ‘Sphinx Template Changes’ From Docs (#4878)
@dojutsu-user: Make form for adopting project a choice field (#4841)
@dojutsu-user: Add ‘Branding’ under the ‘Business Info’ section and ‘Guidelines’ on ‘Design Docs’ (#4830)
@dojutsu-user: Raise 404 at SubdomainMiddleware if the project does not exist. (#4795)
@dojutsu-user: Add help_text in the form for adopting a project (#4781)
@dojutsu-user: Remove /embed API endpoint (#4771)
@dojutsu-user: Improve unexpected error message when build fails (#4754)
@dojutsu-user: Change the way of using login_required decorator (#4723)
@dojutsu-user: Fix the form for adopting a project (#4721)

Version 2.8.3

Date:: December 05, 2018

@nutann3: Update “install Sphinx” URL (#4959)
@humitos: Pin redis to the current stable and compatible version (#4956)
@humitos: Properly set LANG environment variables (#4954)
@humitos: Adapt code to remove and ignore warnings (#4953)
@stsewd: Shallow git clone (#4939)
@stsewd: Install latest version of pip (#4938)
@stsewd: Fix svn update (#4933)
@ericholscher: Release 2.8.2 (#4931)
@stsewd: Remove repeated and dead code (#4929)
@stsewd: Remove deprecated sudo from travis (#4919)
@dojutsu-user: Validate profile form fields (#4910)
@davidfischer: Calculate actual ad views (#4885)
@stsewd: Sync versions when creating/deleting versions (#4876)
@dojutsu-user: Remove unused project model fields (#4870)
@humitos: All package updates (#4792)
@humitos: Support git unicode branches (#4433)

Version 2.8.2

Date:: November 28, 2018

@stsewd: Use .exists in queryset (#4927)
@stsewd: Don’t rmtree symlink (#4925)
@stsewd: Delete tags with same commit (#4915)
@safwanrahman: Tuning Elasticsearch for search improvements (#4909)
@edmondchuc: Fixed some typos. (#4906)
@humitos: Upgrade stripe Python package to the latest version (#4904)
@humitos: Retry on API failure when connecting from builders (#4902)
@stsewd: Separate update and checkout steps (#4901)
@humitos: Expose environment variables from database into build commands (#4894)
@ericholscher: Use python to expand the cwd instead of environment variables (#4882)
@humitos: Call Celery worker properly (#4881)
@dojutsu-user: Disable django.security.DisallowedHost from logging (#4879)
@dojutsu-user: Remove ‘Sphinx Template Changes’ From Docs (#4878)
@ericholscher: Unbreak the admin on ImportedFile by using raw_id_fields (#4874)
@stsewd: Check if latest exists before updating identifier (#4873)
@ericholscher: Release 2.8.1 (#4872)
@dojutsu-user: Update django-guardian settings (#4871)
@dojutsu-user: Change ‘VerisionLockedTimeout’ to ‘VersionLockedError’ in comment. (#4859)
@stsewd: Hide “edit on” when the version is a tag (#4851)
@stsewd: Delete untracked tags on fetch (#4811)
@humitos: Appropriate logging when a LockTimeout for VCS is reached (#4804)
@stsewd: Remove support for multiple configurations in one file (#4800)
@stsewd: Pipfile support (schema) (#4782)
@stsewd: Save config on build model (#4749)
@invinciblycool: Redirect to build detail post manual build (#4622)
@davidfischer: Enable timezone support and set timezone to UTC (#4545)
@chirathr: Webhook notification URL size validation check (#3680)

Version 2.8.1

Date:: November 06, 2018

@ericholscher: Fix migration name on modified date migration (#4867)
@dojutsu-user: Change ‘VerisionLockedTimeout’ to ‘VersionLockedError’ in comment. (#4859)
@stsewd: Fix rtd config file (#4857)
@ericholscher: Shorten project name to match slug length (#4856)
@stsewd: Generic message for parser error of config file (#4853)
@stsewd: Use $HOME as CWD for virtualenv creation (#4852)
@stsewd: Hide “edit on” when the version is a tag (#4851)
@ericholscher: Add modified_date to ImportedFile. (#4850)
@ericholscher: Use raw_id_fields so that the Feature admin loads (#4849)
@stsewd: Allow to change project’s VCS (#4845)
@benjaoming: Version compare warning text (#4842)
@dojutsu-user: Make form for adopting project a choice field (#4841)
@humitos: Do not send notification on VersionLockedError (#4839)
@stsewd: Start testing config v2 on our project (#4838)
@ericholscher: Add all migrations that are missing from model changes (#4837)
@ericholscher: Add docstring to DrfJsonSerializer so we know why it’s there (#4836)
@ericholscher: Show the project’s slug in the dashboard (#4834)
@humitos: Avoid infinite redirection (#4833)
@ericholscher: Allow filtering builds by commit. (#4831)
@dojutsu-user: Add ‘Branding’ under the ‘Business Info’ section and ‘Guidelines’ on ‘Design Docs’ (#4830)
@davidfischer: Migrate old passwords without “set_unusable_password” (#4829)
@humitos: Do not import the Celery worker when running the Django app (#4824)
@damianz5: Fix for jQuery in doc-embed call (#4819)
@invinciblycool: Add MkDocsYAMLParseError (#4814)
@stsewd: Delete untracked tags on fetch (#4811)
@stsewd: Don’t activate version on build (#4810)
@humitos: Feature flag to make readthedocs theme default on MkDocs docs (#4802)
@ericholscher: Allow use of file:// urls in repos during development. (#4801)
@ericholscher: Release 2.7.2 (#4796)
@dojutsu-user: Raise 404 at SubdomainMiddleware if the project does not exist. (#4795)
@dojutsu-user: Add help_text in the form for adopting a project (#4781)
@humitos: Add VAT ID field for Gold User (#4776)
@sriks123: Remove logic around finding config file inside directories (#4755)
@dojutsu-user: Improve unexpected error message when build fails (#4754)
@stsewd: Don’t build latest on webhook if it is deactivated (#4733)
@dojutsu-user: Change the way of using login_required decorator (#4723)
@invinciblycool: Remove unused views and their translations. (#4632)
@invinciblycool: Redirect to build detail post manual build (#4622)
@anubhavsinha98: Issue #4551 Changed mock docks to use sphinx (#4569)
@xrmx: search: mark more strings for translation (#4438)
@Alig1493: Fix for issue #4092: Remove unused field from Project model (#4431)
@mashrikt: Remove pytest _describe (#4429)
@xrmx: static: use modern getJSON callbacks (#4382)
@jaraco: Script for creating a project (#4370)
@xrmx: make it easier to use a different default theme (#4278)
@humitos: Document alternate domains for business site (#4271)
@xrmx: restapi/client: don’t use DRF parser for parsing (#4160)
@julienmalard: New languages (#3759)
@stsewd: Improve installation guide (#3631)
@stsewd: Allow to hide version warning (#3595)
@Alig1493: [Fixed #872] Filter Builds according to commit (#3544)
@stsewd: Make slug field a valid DNS label (#3464)

Version 2.8.0

Date:: October 30, 2018

Major change is an upgrade to Django 1.11.

@humitos: Cleanup old code (remove old_div) (#4817)
@humitos: Remove unnecessary migration (#4806)
@humitos: Feature flag to make readthedocs theme default on MkDocs docs (#4802)
@stsewd: Add codecov badge (#4799)
@humitos: Pin missing dependency for the MkDocs guide compatibility (#4798)
@ericholscher: Release 2.7.2 (#4796)
@humitos: Do not log as error a webhook with an invalid branch name (#4779)
@ericholscher: Run travis on release branches (#4763)
@ericholscher: Remove Eric & Anthony from ADMINS & MANAGERS settings (#4762)
@stsewd: Don’t use RequestsContext (#4759)
@davidfischer: Django 1.11 upgrade (#4750)
@stsewd: Dropdown to select Advanced Settings (#4710)
@stsewd: Remove hardcoded constant from config module (#4704)
@stsewd: Update tastypie (#4325)
@stsewd: Update to Django 1.10 (#4319)

Version 2.7.2

Date:: October 23, 2018

@humitos: Validate the slug generated is valid before importing a project (#4780)
@humitos: Do not log as error a webhook with an invalid branch name (#4779)
@ericholscher: Add an index page to our design docs. (#4775)
@dojutsu-user: Remove /embed API endpoint (#4771)
@stsewd: Upgrade logs from debug on middleware (#4769)
@humitos: Link to SSL for Custom Domains fixed (#4766)
@ericholscher: Remove Eric & Anthony from ADMINS & MANAGERS settings (#4762)
@humitos: Do not re-raise the exception if the one that we are checking (#4761)
@humitos: Do not fail when unlinking an non-existing path (#4760)
@humitos: Allow to extend the DomainForm from outside (#4752)
@davidfischer: Fixes an OSX issue with the test suite (#4748)
@humitos: Use Docker time limit for max lock age (#4747)
@xyNNN: Fixed link of PagerDuty (#4744)
@davidfischer: Make storage syncers extend from a base class (#4742)
@ericholscher: Revert “Upgrade theme media to 0.4.2” (#4735)
@ericholscher: Upgrade theme media to 0.4.2 (#4734)
@stsewd: Extend install option from config file (v2, schema only) (#4732)
@stsewd: Remove /cname endpoint (#4731)
@ericholscher: Fix get_vcs_repo by moving it to the Mixin (#4727)
@humitos: Guide explaining how to keep compatibility with mkdocs (#4726)
@ericholscher: Release 2.7.1 (#4725)
@dojutsu-user: Fix the form for adopting a project (#4721)
@ericholscher: Remove logging verbosity on syncer failure (#4717)
@humitos: Lint requirement file for py2 (#4712)
@davidfischer: Improve the getting started docs (#4676)
@stsewd: Strict validation in configuration file (v2 only) (#4607)
@stsewd: Run coverage on travis (#4605)

Version 2.7.1

Date:: October 04, 2018

@ericholscher: Revert “Merge pull request #4636 from readthedocs/search_upgrade” (#4716)
@ericholscher: Reduce the logging we do on CNAME 404 (#4715)
@davidfischer: Minor redirect admin improvements (#4709)
@humitos: Define the doc_search reverse URL from inside the __init__ on test (#4703)
@ericholscher: Revert “auto refresh false” (#4701)
@browniebroke: Remove unused package nilsimsa (#4697)
@stsewd: Fix broken url on sphinx projects (#4696)
@safwanrahman: Tuning elasticsearch shard and replica (#4689)
@ericholscher: Fix bug where we were not indexing Sphinx HTMLDir projects (#4685)
@ericholscher: Fix the queryset used in chunking (#4683)
@ericholscher: Fix python 2 syntax for getting first key in search index update (#4682)
@ericholscher: Release 2.7.0 (#4681)
@davidfischer: Increase footer ad text size (#4678)
@davidfischer: Fix broken docs links (#4677)
@ericholscher: Remove search autosync from tests so local tests work (#4675)
@stsewd: Refactor tasks into decorators (#4666)
@stsewd: Clean up logging (#4665)
@davidfischer: Ad customization docs (#4659)
@davidfischer: Fix a typo in the privacy policy (#4658)
@stsewd: Refactor PublicTask into a decorator task (#4656)
@stsewd: Remove -r option from update_repos command (#4653)
@davidfischer: Create an explicit ad placement (#4647)
@agjohnson: Use collectstatic on media/, without collecting user files (#4502)
@stsewd: Implement submodules key from v2 config (#4493)
@stsewd: Implement mkdocs key from v2 config (#4486)
@agjohnson: Add docs on our roadmap process (#4469)
@humitos: Send notifications when generic/unhandled failures (#3864)
@stsewd: Use relative path for docroot on mkdocs (#3525)

Version 2.7.0

Date:: September 29, 2018

Reverted, do not use

Version 2.6.6

Date:: September 25, 2018

@davidfischer: Fix a markdown test error (#4663)
@davidfischer: Ad customization docs (#4659)
@davidfischer: Fix a typo in the privacy policy (#4658)
@agjohnson: Put search step back into project build task (#4655)
@davidfischer: Create an explicit ad placement (#4647)
@stsewd: Fix some typos in docs and code (#4646)
@stsewd: Downgrade celery (#4644)
@stsewd: Downgrade django-taggit (#4639)
@safwanrahman: [Fix #4247] deleting old search code (#4635)
@stsewd: Add change versions slug to faq (#4633)
@stsewd: Pin sphinx to a compatible version (#4631)
@davidfischer: Make ads more obvious that they are ads (#4628)
@agjohnson: Change mentions of “CNAME” -> custom domain (#4627)
@invinciblycool: Use validate_dict for more accurate error messages (#4617)
@safwanrahman: fixing the indexing (#4615)
@humitos: Update our sponsors to mention Azure (#4614)
@agjohnson: Add cwd to subprocess calls (#4611)
@agjohnson: Make restapi URL additions conditional (#4609)
@agjohnson: Ability to use supervisor from python 2.7 and still run Python 3 (#4606)
@humitos: Return 404 for inactive versions and allow redirects on them (#4599)
@davidfischer: Fixes an issue with duplicate gold subscriptions (#4597)
@davidfischer: Fix ad block nag project issue (#4596)
@humitos: Run all our tests with Python 3.6 on Travis (#4592)
@humitos: Sanitize command output when running under DockerBuildEnvironment (#4591)
@humitos: Force resolver to use PUBLIC_DOMAIN over HTTPS if not Domain.https (#4579)
@davidfischer: Updates and simplification for mkdocs (#4556)
@humitos: Docs for hiding “On …” section from versions menu (#4547)
@stsewd: Implement sphinx key from v2 config (#4482)
@safwanrahman: [Fix #4268] Adding Documentation for upgraded Search (#4467)
@humitos: Upgrade all packages using pur (#4318)
@humitos: Clean CC sensible data on Gold subscriptions (#4291)
@stsewd: Update docs to match the new triague guidelines (#4260)
@xrmx: Make the STABLE and LATEST constants overridable (#4099)
@stsewd: Use str to get the exception message (#3912)

Version 2.6.5

Date:: August 29, 2018

@stsewd: Tests for yaml file regex (#4587)
@agjohnson: Respect user language when caching homepage (#4585)
@humitos: Add start and termination to YAML file regex (#4584)
@safwanrahman: [Fix #4576] Do not delete projects which have multiple users (#4577)

Version 2.6.4

Date:: August 29, 2018

@stsewd: Update tests failing on master (#4575)
@davidfischer: Add a flag to disable docsearch (#4570)
@stsewd: Fix nested syntax in docs (#4567)
@stsewd: Fix incorrect reraise (#4566)
@davidfischer: Add a note about specifying the version of build tools (#4562)
@davidfischer: Serve badges directly from local filesystem (#4561)
@humitos: Build JSON artifacts in HTML builder (#4554)
@humitos: Route task to proper queue (#4553)
@humitos: Sanitize BuildCommand.output by removing NULL characters (#4552)
@davidfischer: Fix changelog for 2.6.3 (#4548)
@ericholscher: Remove hiredis (#4542)
@davidfischer: Use the STATIC_URL for static files to avoid redirection (#4522)
@stsewd: Update docs about build process (#4515)
@StefanoChiodino: Allow for period as a prefix and yaml extension for config file (#4512)
@AumitLeon: Update information on mkdocs build process (#4508)
@humitos: Fix Exact Redirect to work properly when using $rest keyword (#4501)
@humitos: Mark some BuildEnvironmentError exceptions as Warning and do not log them (#4495)
@xrmx: projects: don’t explode trying to update UpdateDocsTaskStep state (#4485)
@humitos: Note with the developer flow to update our app translations (#4481)
@humitos: Add trimmed to all multilines blocktrans tags (#4480)
@humitos: Example and note with usage of trimmed option in blocktrans (#4479)
@humitos: Update Transifex resources for our documentation (#4478)
@humitos: Documentation for Manage Translations (#4470)
@stsewd: Port https://github.com/readthedocs/readthedocs-build/pull/38/ (#4461)
@stsewd: Match v1 config interface to new one (#4456)
@humitos: Skip tags that point to blob objects instead of commits (#4442)
@stsewd: Document python.use_system_site_packages option (#4422)
@humitos: More tips about how to reduce resources usage (#4419)
@xrmx: projects: user in ProjectQuerySetBase.for_admin_user is mandatory (#4417)

Version 2.6.3

Date:: August 18, 2018

Release to Azure!

@davidfischer: Add Sponsors list to footer (#4424)
@stsewd: Cache node_modules to speed up CI (#4484)
@xrmx: templates: mark missing string for translation on project edit (#4518)
@ericholscher: Performance improvement: cache version listing on the homepage (#4526)
@agjohnson: Remove mailgun from our dependencies (#4531)
@davidfischer: Improved ad block detection (#4532)
@agjohnson: Revert “Remove SelectiveFileSystemFolder finder workaround” (#4533)
@davidfischer: Slight clarification on turning off ads for a project (#4534)
@davidfischer: Fix the sponsor image paths (#4535)
@agjohnson: Update build assets (#4537)

Version 2.6.2

Date:: August 14, 2018

@davidfischer: Custom domain clarifications (#4514)
@trein: Use single quote throughout the file (#4513)
@davidfischer: Support ads on pallets themes (#4499)
@davidfischer: Only use HostHeaderSSLAdapter for SSL/HTTPS connections (#4498)
@keflavich: Very minor English correction (#4497)
@davidfischer: All static media is run through “collectstatic” (#4489)
@humitos: Fix reST structure (#4488)
@nijel: Document expected delay on CNAME change and need for CAA (#4487)
@davidfischer: Allow enforcing HTTPS for custom domains (#4483)
@davidfischer: Add some details around community ad qualifications (#4436)
@davidfischer: Updates to manifest storage (#4430)
@davidfischer: Update alt domains docs with SSL (#4425)
@agjohnson: Add SNI support for API HTTPS endpoint (#4423)
@davidfischer: API v1 cleanup (#4415)
@davidfischer: Allow filtering versions by active (#4414)
@mlncn: Fix broken link (#4410)
@safwanrahman: [Fix #4407] Port Project Search for Elasticsearch 6.x (#4408)
@davidfischer: Add client ID to Google Analytics requests (#4404)
@xrmx: projects: fix filtering in projects_tag_detail (#4398)
@davidfischer: Fix a proxy model bug related to ad-free (#4390)
@humitos: Release 2.6.1 (#4389)
@davidfischer: Do not access database from builds to check ad-free (#4387)
@humitos: Adapt YAML config integration tests (#4385)
@stsewd: Set full source_file path for default configuration (#4379)
@humitos: Make get_version usable from a specified path (#4376)
@humitos: More tags when logging errors to Sentry (#4375)
@humitos: Check for ‘options’ in update_repos command (#4373)
@safwanrahman: [Fix #4333] Implement asynchronous search reindex functionality using celery (#4368)
@stsewd: V2 of the configuration file (#4355)
@davidfischer: Remove the UID from the GA measurement protocol (#4347)
@humitos: Mount pip_cache_path in Docker container (#3556)
@agjohnson: Show subprojects in search results (#1866)

Version 2.6.1

Date:: July 17, 2018

@davidfischer: Do not access database from builds to check ad-free (#4387)
@humitos: Adapt YAML config integration tests (#4385)
@stsewd: Set full source_file path for default configuration (#4379)
@humitos: More tags when logging errors to Sentry (#4375)

Version 2.6.0

Date:: July 16, 2018

Adds initial support for HTTPS on custom domains
@stsewd: Revert “projects: serve badge with same protocol as site” (#4353)
@davidfischer: Do not overwrite sphinx context variables feature (#4349)
@stsewd: Calrify docs about how rtd select the stable version (#4348)
@davidfischer: Remove the UID from the GA measurement protocol (#4347)
@stsewd: Fix error in command (#4345)
@davidfischer: Improvements for the build/version admin (#4344)
@safwanrahman: [Fix #4265] Porting frontend docsearch to work with new API (#4340)
@ktdreyer: fix spelling of “demonstrating” (#4336)
@davidfischer: Warning about theme context implementation status (#4335)
@Blendify: Docs: Let Theme Choose Pygments Theme (#4331)
@davidfischer: Disable the ad block nag for ad-free projects (#4329)
@safwanrahman: [fix #4265] Port Document search API for Elasticsearch 6.x (#4309)
@stsewd: Refactor configuration object to class based (#4298)

Version 2.5.3

Date:: July 05, 2018

@xrmx: Do less work in querysets (#4322)
@stsewd: Fix deprecations in management commands (#4321)
@davidfischer: Add a flag for marking a project ad-free (#4313)
@davidfischer: Use “npm run lint” from tox (#4312)
@davidfischer: Fix issues building static assets (#4311)
@humitos: Use PATHs to call clear_artifacts (#4296)
@safwanrahman: [Fix #2457] Implement exact match search (#4292)
@davidfischer: API filtering improvements (#4285)
@annegentle: Remove self-referencing links for webhooks docs (#4283)
@safwanrahman: [Fix #2328 #2013] Refresh search index and test for case insensitive search (#4277)
@xrmx: doc_builder: clarify sphinx backend append_conf docstring (#4276)
@davidfischer: Add documentation for APIv2 (#4274)
@humitos: Wrap notifications HTML code into a block (#4273)
@stsewd: Move config.py from rtd build (#4272)
@ericholscher: Fix our use of --use-wheel in pip. (#4269)
@agjohnson: Revert “Merge pull request #4206 from FlorianKuckelkorn/fix/pip-breaking-change” (#4261)
@humitos: Fix triggering a build for a skipped project (#4255)
@stsewd: Update default sphinx version (#4250)
@stsewd: Move config module from rtd-build repo (#4242)
@davidfischer: Allow staying logged in for longer (#4236)
@safwanrahman: Upgrade Elasticsearch to version 6.x (#4211)
@humitos: Make tests extensible from corporate site (#4095)
@stsewd: stable version stuck on a specific commit (#3913)

Version 2.5.2

Date:: June 18, 2018

@davidfischer: Add a page detailing ad blocking (#4244)
@xrmx: projects: serve badge with same protocol as site (#4228)
@FlorianKuckelkorn: Fixed breaking change in pip 10.0.0b1 (2018-03-31) (#4206)
@StefanoChiodino: Document that readthedocs file can now have yaml extension (#4129)
@humitos: Downgrade docker to 3.1.3 because of timeouts in EXEC call (#4241)
@stsewd: Move parser tests from rtd-build repo (#4225)
@humitos: Handle revoked oauth permissions by the user (#4074)
@humitos: Allow to hook the initial build from outside (#4033)

Version 2.5.1

Date:: June 14, 2018

@stsewd: Add feature to build json with html in the same build (#4229)
@davidfischer: Prioritize ads based on content (#4224)
@mostaszewski: #4170 - Link the version in the footer to the changelog (#4217)
@Jmennius: Add provision_elasticsearch command (#4216)
@SuriyaaKudoIsc: Use the latest YouTube share URL (#4209)
@davidfischer: Allow staff to trigger project builds (#4207)
@davidfischer: Use autosectionlabel in the privacy policy (#4204)
@davidfischer: These links weren’t correct after #3632 (#4203)
@davidfischer: Release 2.5.0 (#4200)
@ericholscher: Fix Build: Convert md to rst in docs (#4199)
@ericholscher: Updates to #3850 to fix merge conflict (#4198)
@ericholscher: Build on top of #3881 and put docs in custom_installs. (#4196)
@davidfischer: Increase the max theme version (#4195)
@ericholscher: Remove maxcdn reqs (#4194)
@ericholscher: Add missing gitignore item for ES testing (#4193)
@xrmx: fabfile: update i18n helpers (#4189)
@xrmx: Update italian locale (#4188)
@xrmx: locale: update and build the english translation (#4187)
@humitos: Upgrade celery to avoid AtributeError:async (#4185)
@stsewd: Prepare code for custo mkdocs.yaml location (#4184)
@agjohnson: Updates to our triage guidelines (#4180)
@davidfischer: Server side analytics (#4131)
@humitos: Upgrade packages with pur (#4124)
@stsewd: Fix resync remote repos (#4113)
@stsewd: Add schema for configuration file with yamale (#4084)
@davidfischer: Ad block nag to urge people to whitelist (#4037)
@benjaoming: Add Mexican Spanish as a project language (#3588)

Version 2.5.0

Date:: June 06, 2018

@ericholscher: Fix Build: Convert md to rst in docs (#4199)
@ericholscher: Remove maxcdn reqs (#4194)
@ericholscher: Add missing gitignore item for ES testing (#4193)
@xrmx: fabfile: update i18n helpers (#4189)
@xrmx: Update italian locale (#4188)
@xrmx: locale: update and build the english translation (#4187)
@safwanrahman: Test for search functionality (#4116)
@davidfischer: Update mkdocs to the latest (#4041)
@davidfischer: Ad block nag to urge people to whitelist (#4037)
@davidfischer: Decouple the theme JS from readthedocs.org (#3968)
@xrmx: tests: fixup url tests in test_privacy_urls (#3966)
@fenilgandhi: Add support for different badge styles (#3632)
@benjaoming: Add Mexican Spanish as a project language (#3588)
@stsewd: Wrap versions’ list to look more consistent (#3445)
@agjohnson: Move CDN code to external abstraction (#2091)

Version 2.4.0

Date:: May 31, 2018

This fixes assets that were generated against old dependencies in 2.3.14
@agjohnson: Fix issues with search javascript (#4176)
@stsewd: Use anonymous refs in CHANGELOG (#4173)
@stsewd: Fix some warnings on docs (#4172)
@davidfischer: Update the privacy policy date (#4171)
@davidfischer: Note about state and metro ad targeting (#4169)
@ericholscher: Add another guide around fixing memory usage. (#4168)
@stsewd: Download raw build log (#3585)
@stsewd: Add “edit” and “view docs” buttons to subproject list (#3572)
@kennethlarsen: Remove outline reset to bring back outline (#3512)

Version 2.3.14

Date:: May 30, 2018

@ericholscher: Remove CSS override that doesn’t exist. (#4165)
@davidfischer: Include a DMCA request template (#4164)
@davidfischer: No CSRF cookie for docs pages (#4153)
@davidfischer: Small footer rework (#4150)
@stsewd: Fix prospector dependencies (#4149)
@ericholscher: Remove deploy directory which is unused. (#4147)
@stsewd: Use autosectionlabel extension (#4146)
@davidfischer: Add Intercom to the privacy policy (#4145)
@humitos: Minimum refactor to decide_if_cors (#4143)
@stsewd: Ignore migrations from coverage report (#4141)
@stsewd: 5xx status in old webhooks (#4139)
@davidfischer: Fix with Lato Bold font (#4138)
@davidfischer: Release 2.3.13 (#4137)
@davidfischer: Build static assets (#4136)
@xrmx: oauth/services: correct error handling in paginate (#4134)
@xrmx: oauth/services: don’t abuse log.exception (#4133)
@cedk: Use quiet mode to retrieve branches from mercurial (#4114)
@humitos: Add has_valid_clone and has_valid_webhook to ProjectAdminSerializer (#4107)
@stsewd: Put the rtd extension to the beginning of the list (#4054)
@stsewd: Use gitpython for tags (#4052)
@davidfischer: Do Not Track support (#4046)
@stsewd: Set urlconf to None after changing SUBDOMAIN setting (#4032)
@humitos: Fix /404/ testing page (#3976)
@xrmx: Fix some tests with postgres (#3958)
@xrmx: Fixup DJANGO_SETTINGS_SKIP_LOCAL in tests (#3899)
@xrmx: templates: mark a few more strings for translations (#3869)
@ze: Make search bar in dashboard have a more clear message. (#3844)
@varunotelli: Pointed users to Python3.6 (#3817)
@stsewd: [RDY] Fix tests for environment (#3764)
@ajatprabha: Ticket #3694: rename owners to maintainers (#3703)
@SanketDG: Refactor to replace old logging to avoid mangling (#3677)
@stsewd: Add rstcheck to CI (#3624)
@techtonik: Update Git on prod (#3615)
@stsewd: Allow to hide version warning (#3595)
@cclauss: Modernize Python 2 code to get ready for Python 3 (#3514)
@stsewd: Consistent version format (#3504)

Version 2.3.13

Date:: May 23, 2018

@davidfischer: Build static assets (#4136)
@stsewd: Don’t sync _static dir for search builder (#4120)
@davidfischer: Use the latest Lato release (#4093)
@davidfischer: Update Gold Member marketing (#4063)
@davidfischer: Fix missing fonts (#4060)
@stsewd: Additional validation when changing the project language (#3790)
@stsewd: Improve yaml config docs (#3685)

Version 2.3.12

Date:: May 21, 2018

@stsewd: Remove Django deprecation warning (#4112)
@davidfischer: Display feature flags in the admin (#4108)
@humitos: Set valid clone in project instance inside the version object also (#4105)
@davidfischer: Use the latest theme version in the default builder (#4096)
@humitos: Use next field to redirect user when login is done by social (#4083)
@humitos: Update the documentation_type when it’s set to ‘auto’ (#4080)
@brainwane: Update link to license in philosophy document (#4059)
@agjohnson: Update local assets for theme to 0.3.1 tag (#4047)
@stsewd: Fix unbalanced div (#4044)
@stsewd: Remove haystack from code base (#4039)
@davidfischer: Subdomains use HTTPS if settings specify (#3987)
@davidfischer: Draft Privacy Policy (#3978)
@humitos: Allow import Gitlab repo manually and set a webhook automatically (#3934)
@davidfischer: Enable ads on the readthedocs mkdocs theme (#3922)
@bansalnitish: Fixes #2953 - Url resolved with special characters (#3725)
@Jigar3: Deleted bookmarks app (#3663)

Version 2.3.11

Date:: May 01, 2018

@agjohnson: Update local assets for theme to 0.3.1 tag (#4047)
@stsewd: Fix unbalanced div (#4044)
@stsewd: Remove haystack from code base (#4039)
@stsewd: Remove dead code from api v1 (#4038)
@humitos: Bump sphinx default version to 1.7.4 (#4035)
@davidfischer: Detail where ads are shown (#4031)
@ericholscher: Make email verification optional for dev (#4024)
@davidfischer: Support sign in and sign up with GH/GL/BB (#4022)
@agjohnson: Remove old varnish purge utility function (#4019)
@agjohnson: Remove build queue length warning on build list page (#4018)
@stsewd: Don’t check order on assertQuerysetEqual on tests for subprojects (#4016)
@stsewd: Tests for view docs api response (#4014)
@davidfischer: MkDocs projects use RTD’s analytics privacy improvements (#4013)
@humitos: Release 2.3.10 (#4009)
@davidfischer: Remove typekit fonts (#3982)
@stsewd: Move dynamic-fixture to testing requirements (#3956)
@stsewd: Fix view docs link (#3882)
@stsewd: [WIP] Remove comments app (#3802)
@Jigar3: Deleted bookmarks app (#3663)

Version 2.3.10

Date:: April 24, 2018

@humitos: Downgrade docker to 3.1.3 (#4003)

Version 2.3.9

Date:: April 20, 2018

@agjohnson: Fix recursion problem more generally (#3989)

Version 2.3.8

Date:: April 20, 2018

@agjohnson: Give TaskStep class knowledge of the underlying task (#3983)
@humitos: Resolve domain when a project is a translation of itself (#3981)

Version 2.3.7

Date:: April 19, 2018

@humitos: Fix server_error_500 path on single version (#3975)
@davidfischer: Fix bookmark app lint failures (#3969)
@humitos: Use latest setuptools (39.0.1) by default on build process (#3967)
@ericholscher: Fix exact redirects. (#3965)
@humitos: Make resolve_domain work when a project is subproject of itself (#3962)
@humitos: Remove django-celery-beat and use the default scheduler (#3959)
@xrmx: Fix some tests with postgres (#3958)
@davidfischer: Add advertising details docs (#3955)
@humitos: Use pur to upgrade python packages (#3953)
@ze: Make adjustments to Projects page (#3948)
@davidfischer: Small change to Chinese language names (#3947)
@agjohnson: Don’t share state in build task (#3946)
@davidfischer: Fixed footer ad width fix (#3944)
@humitos: Allow extend Translation and Subproject form logic from corporate (#3937)
@humitos: Resync valid webhook for project manually imported (#3935)
@humitos: Resync webhooks from Admin (#3933)
@humitos: Fix attribute order call (#3930)
@humitos: Mention RTD in the Project URL of the issue template (#3928)
@davidfischer: Correctly report mkdocs theme name (#3920)
@xrmx: Fixup DJANGO_SETTINGS_SKIP_LOCAL in tests (#3899)
@davidfischer: Show an adblock admonition in the dev console (#3894)
@stsewd: Fix view docs link (#3882)
@xrmx: templates: mark a few more strings for translations (#3869)
@ze: Update quickstart from README (#3847)
@vidartf: Fix page redirect preview (#3811)
@stsewd: [RDY] Fix requirements file lookup (#3800)
@aasis21: Documentation for build notifications using webhooks. (#3671)
@mashrikt: [#2967] Scheduled tasks for cleaning up messages (#3604)
@stsewd: Show URLS for exact redirect (#3593)
@marcelstoer: Doc builder template should check for mkdocs_page_input_path before using it (#3536)
@Code0x58: Document creation of slumber user (#3461)

Version 2.3.6

Date:: April 05, 2018

@agjohnson: Drop readthedocs- prefix to submodule (#3916)
@agjohnson: This fixes two bugs apparent in nesting of translations in subprojects (#3909)
@humitos: Use new django celery beat scheduler (#3908)
@humitos: Use a proper default for docker attribute on UpdateDocsTask (#3907)
@davidfischer: Handle errors from publish_parts (#3905)
@agjohnson: Drop pdbpp from testing requirements (#3904)
@stsewd: Little improve on sync_versions (#3902)
@humitos: Save Docker image data in JSON file only for DockerBuildEnvironment (#3897)
@davidfischer: Single analytics file for all builders (#3896)
@humitos: Organize logging levels (#3893)

Version 2.3.5

Date:: April 05, 2018

@agjohnson: Drop pdbpp from testing requirements (#3904)
@agjohnson: Resolve subproject correctly in the case of single version (#3901)
@davidfischer: Fixed footer ads again (#3895)
@davidfischer: Fix an Alabaster ad positioning issue (#3889)
@humitos: Save Docker image hash in RTD environment.json file (#3880)
@agjohnson: Add ref links for easier intersphinx on yaml config page (#3877)
@rajujha373: Typo correction in docs/features.rst (#3872)
@gaborbernat: add description for tox tasks (#3868)
@davidfischer: Another CORS hotfix for the sustainability API (#3862)
@agjohnson: Fix up some of the logic around repo and submodule URLs (#3860)
@davidfischer: Fix linting errors in tests (#3855)
@agjohnson: Use gitpython to find a commit reference (#3843)
@davidfischer: Remove pinned CSS Select version (#3813)
@davidfischer: Use JSONP for sustainability API (#3789)
@rajujha373: #3718: Added date to changelog (#3788)
@xrmx: tests: mock test_conf_file_not_found filesystem access (#3740)

Version 2.3.4

Release for static assets

Version 2.3.3

@davidfischer: Fix linting errors in tests (#3855)
@humitos: Fix linting issues (#3838)
@humitos: Update instance and model when record_as_success (#3831)
@ericholscher: Reorder GSOC projects, and note priority order (#3823)
@agjohnson: Add temporary method for skipping submodule checkout (#3821)
@davidfischer: Remove pinned CSS Select version (#3813)
@humitos: Use readthedocs-common to share linting files across different repos (#3808)
@davidfischer: Use JSONP for sustainability API (#3789)
@humitos: Define useful celery beat task for development (#3762)
@humitos: Auto-generate conf.py compatible with Py2 and Py3 (#3745)
@humitos: Task to remove orphan symlinks (#3543)
@stsewd: Fix regex for public bitbucket repo (#3533)
@humitos: Documentation for RTD context sent to the Sphinx theme (#3490)
@stsewd: Show link to docs on a build (#3446)

Version 2.3.2

This version adds a hotfix branch that adds model validation to the repository URL to ensure strange URL patterns can’t be used.

Version 2.3.1

@humitos: Update instance and model when record_as_success (#3831)
@agjohnson: Bump docker -> 3.1.3 (#3828)
@Doug-AWS: Pip install note for Windows (#3827)
@himanshutejwani12: Update index.rst (#3824)
@ericholscher: Reorder GSOC projects, and note priority order (#3823)
@agjohnson: Autolint cleanup for #3821 (#3822)
@agjohnson: Add temporary method for skipping submodule checkout (#3821)
@stsewd: Pin astroid to fix linter issue on travis (#3816)
@varunotelli: Update install.rst dropped the Python 2.7 only part (#3814)
@xrmx: Update machine field when activating a version from project_version_detail (#3797)
@humitos: Allow members of “Admin” Team to wipe version envs (#3791)
@ericholscher: Add sustainability api to CORS (#3782)
@durwasa-chakraborty: Fixed a grammatical error (#3780)
@humitos: Trying to solve the end line character for a font file (#3776)
@stsewd: Fix tox env for coverage (#3772)
@bansalnitish: Added eslint rules (#3768)
@davidfischer: Use sustainability api for advertising (#3747)
@davidfischer: Add a sustainability API (#3672)
@humitos: Upgrade django-pagination to a “maintained” fork (#3666)
@humitos: Project updated when subproject modified (#3649)
@davidfischer: Anonymize IP addresses for Google Analytics (#3626)
@humitos: Improve “Sharing” docs (#3472)
@humitos: Upgrade docker-py to its latest version (docker==3.1.1) (#3243)
@humitos: Upgrade all packages using pur tool (#2916)
@rixx: Fix page redirect preview (#2711)

Version 2.3.0

Warning

Version 2.3.0 includes a security fix for project translations. See Release 2.3.0 for more information

@stsewd: Fix tox env for coverage (#3772)
@humitos: Try to fix end of file (#3761)
@berkerpeksag: Fix indentation in docs/faq.rst (#3758)
@stsewd: Check for http protocol before urlize (#3755)
@rajujha373: #3741: replaced Go Crazy text with Search (#3752)
@humitos: Log in the proper place and add the image name used (#3750)
@shubham76: Changed ‘Submit’ text on buttons with something more meaningful (#3749)
@agjohnson: Fix tests for Git submodule (#3737)
@bansalnitish: Add eslint rules and fix errors (#3726)
@davidfischer: Prevent bots indexing promos (#3719)
@agjohnson: Add argument to skip errorlist through knockout on common form (#3704)
@ajatprabha: Fixed #3701: added closing tag for div element (#3702)
@bansalnitish: Fixes internal reference (#3695)
@humitos: Always record the git branch command as success (#3693)
@ericholscher: Show the project slug in the project admin (to make it more explicit what project is what) (#3681)
@humitos: Upgrade django-taggit to 0.22.2 (#3667)
@stsewd: Check for submodules (#3661)
@agjohnson: Hotfix for adding logging call back into project sync task (#3657)
@agjohnson: Fix issue with missing setting in oauth SyncRepo task (#3656)
@ericholscher: Remove error logging that isn’t an error. (#3650)
@humitos: Project updated when subproject modified (#3649)
@aasis21: formatting buttons in edit project text editor (#3633)
@humitos: Filter by my own repositories at Import Remote Project (#3548)
@funkyHat: check for matching alias before subproject slug (#2787)

Version 2.2.1

Version 2.2.1 is a bug fix release for the several issues found in production during the 2.2.0 release.

@agjohnson: Hotfix for adding logging call back into project sync task (#3657)

@agjohnson: Fix issue with missing setting in oauth SyncRepo task (#3656)

@humitos: Tests for build notifications (#3654)

@humitos: Send proper context to celery email notification task (#3653)

@ericholscher: Remove error logging that isn’t an error. (#3650)

@davidfischer: Update RTD security docs (#3641)

@humitos: Ability to override the creation of the Celery App (#3623)

Version 2.2.0

@humitos: Tests for build notifications (#3654)

@humitos: Send proper context to celery email notification task (#3653)

@xrmx: Update django-formtools to 2.1 (#3648)

@xrmx: Update Django to 1.9.13 (#3647)

@davidfischer: Fix a 500 when searching for files with API v1 (#3645)

@davidfischer: Update RTD security docs (#3641)

@humitos: Fix SVN initialization for command logging (#3638)

@humitos: Ability to override the creation of the Celery App (#3623)

@humitos: Update the operations team (#3621)

@mohitkyadav: Add venv to .gitignore (#3620)

@stsewd: Remove hardcoded copyright year (#3616)

@stsewd: Improve installation steps (#3614)

@stsewd: Update GSOC (#3607)

@Jigar3: Updated AUTHORS.rst (#3601)

@stsewd: Pin less to latest compatible version (#3597)

@Angeles4four: Grammar correction (#3596)

@davidfischer: Fix an unclosed tag (#3592)

@aaksarin: add missed fontawesome-webfont.woff2 (#3589)

@davidfischer: Force a specific ad to be displayed (#3584)

@stsewd: Docs about preference for tags over branches (#3582)

@davidfischer: Rework homepage (#3579)

@stsewd: Don’t allow to create a subproject of a project itself (#3571)

@davidfischer: Fix for build screen in firefox (#3569)

@humitos: Style using pre-commit (#3560)

@humitos: Use DRF 3.1 pagination_class (#3559)

@davidfischer: Analytics fixes (#3558)

@davidfischer: Upgrade requests version (#3557)

@humitos: Mount pip_cache_path in Docker container (#3556)

@ericholscher: Add a number of new ideas for GSOC (#3552)

@humitos: Fix Travis lint issue (#3551)

@davidfischer: Send custom dimensions for mkdocs (#3550)

@davidfischer: Promo contrast improvements (#3549)

@humitos: Allow git tags with / in the name and properly slugify (#3545)

@humitos: Allow to import public repositories on corporate site (#3537)

@humitos: Log git checkout and expose to users (#3520)

@stsewd: Update docs (#3498)

@davidfischer: Switch to universal analytics (#3495)

@stsewd: Move Mercurial dependency to pip.txt (#3488)

@agjohnson: Add docs on removing edit button (#3479)

@davidfischer: Convert default dev cache to local memory (#3477)

@agjohnson: Fix lint error (#3402)

@techtonik: Fix Edit links if version is referenced by annotated tag (#3302)

@jaraco: Fixed build results page on firefox (part two) (#2630)

Version 2.1.6

@davidfischer: Promo contrast improvements (#3549)

@humitos: Refactor run command outside a Build and Environment (#3542)

@AnatoliyURL: Project in the local read the docs don’t see tags. (#3534)

@malarzm: searchtools.js missing init() call (#3532)

@johanneskoester: Build failed without details (#3531)

@danielmitterdorfer: “Edit on Github” points to non-existing commit (#3530)

@lk-geimfari: No such file or directory: ‘docs/requirements.txt’ (#3529)

@stsewd: Fix Good First Issue link (#3522)

@Blendify: Remove RTD Theme workaround (#3519)

@stsewd: Move project description to the top (#3510)

@davidfischer: Switch to universal analytics (#3495)

@davidfischer: Convert default dev cache to local memory (#3477)

@nlgranger: Github service: cannot unlink after deleting account (#3374)

@andrewgodwin: “stable” appearing to track future release branches (#3268)

@skddc: Add JSDoc to docs build environment (#3069)

@chummels: RTD building old “stable” docs instead of “latest” when auto-triggered from recent push (#2351)

@cajus: Builds get stuck in “Cloning” state (#2047)

@gossi: Cannot delete subproject (#1341)

@gigster99: extension problem (#1059)

Version 2.1.5

@ericholscher: Add GSOC 2018 page (#3518)

@stsewd: Move project description to the top (#3510)

@RichardLitt: Docs: Rename “Good First Bug” to “Good First Issue” (#3505)

@stsewd: Fix regex for getting project and user (#3501)

@ericholscher: Check to make sure changes exist in Bitbucket pushes (#3480)

@andrewgodwin: “stable” appearing to track future release branches (#3268)

@cdeil: No module named pip in conda build (#2827)

@Yaseenh: building project does not generate new pdf with changes in it (#2758)

@chummels: RTD building old “stable” docs instead of “latest” when auto-triggered from recent push (#2351)

@KeithWoods: GitHub edit link is aggressively stripped (#1788)

Version 2.1.4

@davidfischer: Add programming language to API/READTHEDOCS_DATA (#3499)

@ericholscher: Remove our mkdocs search override (#3496)

@humitos: Better style (#3494)

@humitos: Update README.rst (#3492)

@davidfischer: Small formatting change to the Alabaster footer (#3491)

@matsen: Fixing “resetting” misspelling. (#3487)

@ericholscher: Add David to dev team listing (#3485)

@ericholscher: Check to make sure changes exist in Bitbucket pushes (#3480)

@ericholscher: Use semvar for readthedocs-build to make bumping easier (#3475)

@davidfischer: Add programming languages (#3471)

@humitos: Remove TEMPLATE_LOADERS since it’s the default (#3469)

@Code0x58: Minor virtualenv upgrade (#3463)

@humitos: Remove invite only message (#3456)

@maxirus: Adding to Install Docs (#3455)

@stsewd: Fix a little typo (#3448)

@stsewd: Better autogenerated index file (#3447)

@stsewd: Better help text for privacy level (#3444)

@msyriac: Broken link URL changed fixes #3442 (#3443)

@ericholscher: Fix git (#3441)

@ericholscher: Properly slugify the alias on Project Relationships. (#3440)

@stsewd: Don’t show “build ideas” to unprivileged users (#3439)

@Blendify: Docs: Point Theme docs to new website (#3438)

@humitos: Do not use double quotes on git command with –format option (#3437)

@ericholscher: Hack in a fix for missing version slug deploy that went out a while back (#3433)

@humitos: Check versions used to create the venv and auto-wipe (#3432)

@ericholscher: Upgrade psycopg2 (#3429)

@humitos: Fix “Edit in Github” link (#3427)

@ericholscher: Add celery theme to supported ad options (#3425)

@humitos: Link to version detail page from build detail page (#3418)

@humitos: Move wipe button to version detail page (#3417)

@humitos: Show/Hide “See paid advertising” checkbox depending on USE_PROMOS (#3412)

@benjaoming: Strip well-known version component origin/ from remote version (#3377)

@humitos: Remove warnings from code (#3372)

@ericholscher: Add docker image from the YAML config integration (#3339)

@humitos: Show proper error to user when conf.py is not found (#3326)

@humitos: Simple task to finish inactive builds (#3312)

@techtonik: Fix Edit links if version is referenced by annotated tag (#3302)

@Riyuzakii: changed <strong> from html to css (#2699)

Version 2.1.3

date:

Dec 21, 2017

@ericholscher: Upgrade psycopg2 (#3429)
@humitos: Fix “Edit in Github” link (#3427)
@ericholscher: Add celery theme to supported ad options (#3425)
@ericholscher: Only build travis push builds on master. (#3421)
@ericholscher: Add concept of dashboard analytics code (#3420)
@humitos: Use default avatar for User/Orgs in OAuth services (#3419)
@humitos: Link to version detail page from build detail page (#3418)
@humitos: Move wipe button to version detail page (#3417)
@bieagrathara: 019 497 8360 (#3416)
@bieagrathara: rew (#3415)
@tony: lint prospector task failing (#3414)
@humitos: Remove extra ‘s’ (#3413)
@humitos: Show/Hide “See paid advertising” checkbox depending on USE_PROMOS (#3412)
@accraze: Removing talks about RTD page (#3410)
@humitos: Pin pylint to 1.7.5 and fix docstring styling (#3408)
@agjohnson: Update style and copy on abandonment docs (#3406)
@agjohnson: Update changelog more consistently (#3405)
@agjohnson: Update prerelease invoke command to call with explicit path (#3404)
@ericholscher: Fix changelog command (#3403)
@agjohnson: Fix lint error (#3402)
@julienmalard: Recent builds are missing translated languages links (#3401)
@stsewd: Remove copyright application (#3400)
@humitos: Show connect buttons for installed apps only (#3394)
@agjohnson: Fix display of build advice (#3390)
@agjohnson: Don’t display the build suggestions div if there are no suggestions (#3389)
@ericholscher: Pass more data into the redirects. (#3388)
@ericholscher: Fix issue where you couldn’t edit your canonical domain. (#3387)
@benjaoming: Strip well-known version component origin/ from remote version (#3377)
@humitos: Remove warnings from code (#3372)
@JavaDevVictoria: Updated python.setup_py_install to be true (#3357)
@humitos: Use default avatars for GitLab/GitHub/Bitbucket integrations (users/organizations) (#3353)
@jonrkarr: Error in YAML configuration docs: default value for python.setup_py_install should be true (#3334)
@humitos: Show proper error to user when conf.py is not found (#3326)
@MikeHart85: Badges aren’t updating due to being cached on GitHub. (#3323)
@humitos: Simple task to finish inactive builds (#3312)
@techtonik: Fix Edit links if version is referenced by annotated tag (#3302)
@humitos: Remove/Update talks about RTD page (#3283)
@gawel: Regain pyquery project ownership (#3281)
@dialex: Build passed but I can’t see the documentation (maze screen) (#3246)
@makixx: Account is inactive (#3241)
@agjohnson: Cleanup misreported failed builds (#3230)
@cokelaer: links to github are broken (#3203)
@agjohnson: Remove copyright application (#3199)
@shacharoo: Unable to register after deleting my account (#3189)
@gtalarico: 3 week old Build Stuck Cloning (#3126)
@agjohnson: Regressions with conf.py and error reporting (#2963)
@agjohnson: Can’t edit canonical domain (#2922)
@virtuald: Documentation stuck in ‘cloning’ state (#2795)
@Riyuzakii: changed <strong> from html to css (#2699)
@tjanez: Support specifying ‘python setup.py build_sphinx’ as an alternative build command (#1857)
@bdarnell: Broken edit links (#1637)

Version 2.1.2

@agjohnson: Update changelog more consistently (#3405)

@agjohnson: Update prerelease invoke command to call with explicit path (#3404)

@agjohnson: Fix lint error (#3402)

@stsewd: Remove copyright application (#3400)

@humitos: Show connect buttons for installed apps only (#3394)

@agjohnson: Don’t display the build suggestions div if there are no suggestions (#3389)

@jonrkarr: Error in YAML configuration docs: default value for python.setup_py_install should be true (#3334)

@humitos: Simple task to finish inactive builds (#3312)

@agjohnson: Cleanup misreported failed builds (#3230)

@agjohnson: Remove copyright application (#3199)

Version 2.1.1

Release information missing

Version 2.1.0

@ericholscher: Revert “Merge pull request #3336 from readthedocs/use-active-for-stable” (#3368)

@agjohnson: Revert “Do not split before first argument (#3333)” (#3366)

@ericholscher: Remove pitch from ethical ads page, point folks to actual pitch page. (#3365)

@agjohnson: Add changelog and changelog automation (#3364)

@ericholscher: Fix mkdocs search. (#3361)

@ericholscher: Email sending: Allow kwargs for other options (#3355)

@ericholscher: Try and get folks to put more tags. (#3350)

@ericholscher: Suggest wiping your environment to folks with bad build outcomes. (#3347)

@humitos: GitLab Integration (#3327)

@jimfulton: Draft policy for claiming existing project names. (#3314)

@agjohnson: More logic changes to error reporting, cleanup (#3310)

@safwanrahman: [Fix #3182] Better user deletion (#3214)

@ericholscher: Better User deletion (#3182)

@RichardLitt: Add Needed: replication label (#3138)

@josejrobles: Replaced usage of deprecated function get_fields_with_model with new … (#3052)

@ericholscher: Don’t delete the subprojects directory on sync of superproject (#3042)

@andrew: Pass query string when redirecting, fixes #2595 (#3001)

@saily: Add GitLab repo sync and webhook support (#1870)

@destroyerofbuilds: Setup GitLab Web Hook on Project Import (#1443)

@takotuesday: Add GitLab Provider from django-allauth (#1441)

Version 2.0

@ericholscher: Email sending: Allow kwargs for other options (#3355)

@ericholscher: Try and get folks to put more tags. (#3350)

@ericholscher: Small changes to email sending to enable from email (#3349)

@dplanella: Duplicate TOC entries (#3345)

@ericholscher: Small tweaks to ethical ads page (#3344)

@agjohnson: Fix python usage around oauth pagination (#3342)

@tony: Fix isort link (#3340)

@ericholscher: Change stable version switching to respect active (#3336)

@ericholscher: Allow superusers to pass admin & member tests for projects (#3335)

@humitos: Do not split before first argument (#3333)

@humitos: Update docs for pre-commit (auto linting) (#3332)

@humitos: Take preferece of tags over branches when selecting the stable version (#3331)

@humitos: Add prospector as a pre-commit hook (#3328)

@andrewgodwin: “stable” appearing to track future release branches (#3268)

@humitos: Config files for auto linting (#3264)

@mekrip: Build is not working (#3223)

@skddc: Add JSDoc to docs build environment (#3069)

@jakirkham: Specifying conda version used (#2076)

@agjohnson: Document code style guidelines (#1475)

Previous releases

Starting with version 2.0, we will be incrementing the Read the Docs version based on semantic versioning principles, and will be automating the update of our changelog.

Below are some historical changes from when we have tried to add information here in the past

July 23, 2015

Django 1.8 Support Merged

Code notes

Updated Django from 1.6.11 to 1.8.3.
Removed South and ported the South migrations to Django’s migration framework.
Updated django-celery from 3.0.23 to 3.1.26 as django-celery 3.0.x does not support Django 1.8.
Updated Celery from 3.0.24 to 3.1.18 because we had to update django-celery. We need to test this extensively and might need to think about using the new Celery API directly and dropping django-celery. See release notes: https://docs.celeryproject.org/en/3.1/whatsnew-3.1.html
Updated tastypie from 0.11.1 to current master (commit 1e1aff3dd4dcd21669e9c68bd7681253b286b856) as 0.11.x is not compatible with Django 1.8. No surprises expected but we should ask for a proper release, see release notes: https://github.com/django-tastypie/django-tastypie/blob/master/docs/release_notes/v0.12.0.rst
Updated django-oauth from 0.16.1 to 0.21.0. No surprises expected, see release notes in the docs and finer grained in the repo
Updated django-guardian from 1.2.0 to 1.3.0 to gain Django 1.8 support. No surprises expected, see release notes: https://github.com/lukaszb/django-guardian/blob/devel/CHANGES
Using django-formtools instead of removed django.contrib.formtools now. Based on the Django release notes, these modules are the same except of the package name.
Updated pytest-django from 2.6.2 to 2.8.0. No tests required, but running the testsuite :smile:
Updated psycopg2 from 2.4 to 2.4.6 as 2.4.5 is required by Django 1.8. No trouble expected as Django is the layer between us and psycopg2. Also it’s only a minor version upgrade. Release notes: http://initd.org/psycopg/docs/news.html#what-s-new-in-psycopg-2-4-6
Added django.setup() to conf.py to load django properly for doc builds.
Added migrations for all apps with models in the readthedocs/ directory

Deployment notes

After you have updated the code and installed the new dependencies, you need to run these commands on the server:

python manage.py migrate contenttypes
python manage.py migrate projects 0002 --fake
python manage.py migrate --fake-initial

Locally I had trouble in a test environment that pip did not update to the specified commit of tastypie. It might be required to use pip install -U -r requirements/deploy.txt during deployment.

Development update notes

The readthedocs developers need to execute these commands when switching to this branch (or when this got merged into main):

Before updating please make sure that all migrations are applied:
```
python manage.py syncdb
python manage.py migrate
```
Update the codebase: git pull
You need to update the requirements with pip install -r requirements.txt

Now you need to fake the initial migrations:

python manage.py migrate contenttypes
python manage.py migrate projects 0002 --fake
python manage.py migrate --fake-initial

About Read the Docs

Read the Docs is a C Corporation registered in Oregon. Our bootstrapped company is owned and fully controlled by the founders, and fully funded by our customers and advertisers. This allows us to focus 100% on our users.

We have two main sources of revenue:

Read the Docs for Business - where we provide a valuable paid service to companies.
Read the Docs Community - where we provide a free service to the open source community, funded via EthicalAds.

We believe that having both paying customers and ethical advertising is the best way to create a sustainable platform for our users. We have built something that we expect to last a long time, and we are able to make decisions based only on the best interest of our community and customers.

All of the source code for Read the Docs is open source. You are welcome to contribute the features you want or run your own instance. We should note that we generally only support our hosted versions as a matter of our philosophy.

We owe a great deal to the open source community that we are a part of, so we provide free ads via our community ads program. This allows us to give back to the communities and projects that we support and depend on.

We are proud about the way we manage our company and products, and are glad to have you on board with us in this great documentation journey.

If you want to dive more into more specific information and our policies, we’ve brought most of the most important ones below.

⏩ Business hosting: Learn more about how our company provides paid solutions
⏩ Policies and legal documents: Policies and legal documents used by Read the Docs Community and Read the Docs for Business.
⏩ Advertising: Information about how advertisement in Read the Docs
⏩ The story of Read the Docs: A brief throwback to how we were founded
⏩ Sponsors of Read the Docs: Read about who currently sponsors Read the Docs and who sponsored us in the past.
⏩ Read the Docs open source philosophy: Our philosophy is anchored in open source.
⏩ Read the Docs team: How we work and who we are.
⏩ Site support: Read this before asking for help: How to get support and where.
⏩ Glossary: A useful index of terms used in our docs

See also

Our website: Our primary website has general-purpose information about Read the Docs like pricing and feature overviews.

Policies and legal documents

Here is some of the fine print used by Read the Docs Community and Read the Docs for Business:

Abandoned projects policy

This policy describes the process by which a Read the Docs project slug may be changed.

Tip

If you want to de-list a project’s fork from search results, please see Unofficial and unmaintained projects policy.

Rationale

Conflict between the current use of the name and a different suggested use of the same name occasionally arise. This document aims to provide general guidelines for solving the most typical cases of such conflicts.

Specification

The main idea behind this policy is that Read the Docs serves the community. Every user is invited to upload content under the Terms of Use, understanding that it is at the sole risk of the user.

While Read the Docs is not a backup service, the core team of Read the Docs does their best to keep that content accessible indefinitely in its published form. However, in certain edge cases the greater community’s needs might outweigh the individual’s expectation of ownership of a project name.

The use cases covered by this policy are:

Abandoned projects: Renaming a project so that the original project name can be used by a different project
Active projects: Resolving disputes over a name

Implementation

Reachability

The user of Read the Docs is solely responsible for being reachable by the core team for matters concerning projects that the user owns. In every case where contacting the user is necessary, the core team will try to do so, using the following means of contact:

E-mail address on file in the user’s profile
E-mail addresses found in the given project’s documentation
E-mail address on the project’s home page

The core team will stop trying to reach the user after six weeks and the user will be considered unreachable.

Abandoned projects

A project is considered abandoned when ALL of the following are met:

Owner is unreachable (see Reachability)
The project has no proper documentation being served (no successful builds) or does not have any releases within the past twelve months
No activity from the owner on the project’s home page (or no home page found).

All other projects are considered active.

Renaming of an abandoned project

Projects are never renamed solely on the basis of abandonment.

An abandoned project can be renamed (by appending -abandoned and a uniquifying integer if needed) for purposes of reusing the name when ALL of the following are met:

The project has been determined abandoned by the rules described above
The candidate is able to demonstrate their own failed attempts to contact the existing owner
The candidate is able to demonstrate that the project suggested to reuse the name already exists and meets notability requirements
The candidate is able to demonstrate why a fork under a different name is not an acceptable workaround
The project has fewer than 100 monthly pageviews
The core team does not have any additional reservations.

Reporting an abandoned project

You can report an abandoned project according to this policy by contacting our Site support.

Please include the following information:

URL of abandoned documentation project: ...
URL of abandoned project's repository (if any): ...
URL of abandoned project's website (if any): ...

Are you suggesting that an alternative project should take over the
name (slug) abandoned project? (y/n)

URL of alternative documentation (if any): ...
URL of alternative website (if any): ...
URL of alternative repository (if any): ...

Describe attempts of reaching the owner(s) of the abandoned project:
...

Name conflict resolution for active projects

The core team of Read the Docs are not arbiters in disputes around active projects. The core team recommends users to get in touch with each other and solve the issue by respectful communication.

Prior art

The Python Package Index (PyPI) policy for claiming abandoned packages (PEP-0541) heavily influenced this policy.

Unofficial and unmaintained projects policy

This policy describes a process where we take actions against unmaintained and unofficial forks of project documentation.

Tip

If you want to free up a project’s slug and gain access over it, please see Abandoned projects policy.

Rationale

Documentation projects may be kept online indefinitely, even though a newer version of the same project exists elsewhere. There are many reasons this can happen, including forks, old official docs that are unmaintained, and many other situations.

The problem with old, outdated docs is that users will find them in search results, and get confused to the validity of them. Projects will then get support requests from people who are using an old and incorrect documentation version.

We have this policy to allow a reporter to request the delisting of forks that are old and outdated.

High level overview

The process at a high level looks like:

A reporter contacts us about a project they think is outdated and unofficial
A Read the Docs team member evaluates it to make sure it’s outdated and unofficial, according to this policy
We delist this project from search results and send an email to owners of the Read the Docs project
If a project owner objects, we evaluate their evidence and make a final decision

Definitions

Unofficial projects

A project is considered unofficial when it is not linked to or mentioned in any of these places:

Websites and domains associated with the project
The project’s primary repository – README files, repository description, or source code

Unmaintained projects

A project is considered unmaintained when any of the following are met:

The configured version control repository is unreadable. This can happen if the repository is deleted, credentials are broken or the Git host is permanently unresponsive.
The project is only serving content from releases and commits 6 months or older.
All builds have failed for more than 6 months.

Implementation

Requesting a project be delisted

You can request that we delist an outdated, unmaintained documentation by contacting our Site support.

Please include the following information:

URL of unofficial and unmaintained documentation project: ...
URL of official documentation (if any): ...
URL of official project website (if any): ...
URL of official project repository (if any): ...

Describe attempts of reaching the owner(s) of the documentation project:
...

Delisting

Projects that are determined to be unmaintained and unofficial will have a robots.txt file added that removes them from all search results:

# robots.txt
User-agent: *
# This project is delisted according to the Unofficial and Unmaintanied Project Policy
# https://docs.readthedocs.io/en/stable/unofficial-projects.html
Disallow: /

Projects will be delisted if they meet all of the following criteria:

The person who submits the report of the unmaintained and unofficial project also demonstrates failed attempts to contact the existing owners.
The project has been determined unmaintained and unofficial by the rules described above.
The core team does not have any additional reservations.

The Read the Docs team will do the following actions when a project is delisted:

Notify the Read the Docs project owners via email about the delisting.
Add the robots.txt file to be served on the project domain.

If any of the project owners respond, their response will be taken into account, and the delisting might be reversed.

Thinking behind the policy

The main idea behind this policy is that Read the Docs serves the community. Every user is invited to upload content under terms of service understanding that it is at the sole risk of the user.

While Read the Docs is not a backup service, the core team of Read the Docs does their best to keep content accessible indefinitely in its published form. However, in certain edge cases, the greater community’s needs might outweigh the individual’s expectation of continued publishing.

Prior art

This policy is inspired by our Abandoned projects policy. The Python Package Index (PyPI) policy for claiming abandoned packages (PEP-0541) heavily influenced this policy.

Privacy Policy

Effective date: February 21, 2023

Welcome to Read the Docs. At Read the Docs, we believe in protecting the privacy of our users, authors, and readers.

The short version

We collect your information only with your consent; we only collect the minimum amount of personal information that is necessary to fulfill the purpose of your interaction with us; we don’t sell it to third parties; and we only use it as this Privacy Policy describes.

Of course, the short version doesn’t tell you everything, so please read on for more details!

Our services

Read the Docs is made up of:

readthedocs.org (“Read the Docs Community”): This is a website aimed at documentation authors and project maintainers writing and distributing technical documentation. This Privacy Policy applies to this site in full without reservation.
readthedocs.com (“Read the Docs for Business”): This website is a commercial hosted offering for hosting private documentation for corporate clients. This Privacy Policy applies to this site in full without reservation.
readthedocs.io, readthedocs-hosted.com, and other domains (“Documentation Sites”): These websites are where Read the Docs hosts documentation (User-Generated Content) on behalf of documentation authors. A best effort is made to apply this Privacy Policy to these sites but the documentation may contain content and files created by documentation authors.

All use of Read the Docs is subject to this Privacy Policy, together with our Terms of Service.

What information Read the Docs collects and why

Information from website browsers

If you’re just browsing the website, we collect the same basic information that most websites collect. We use common internet technologies, such as cookies and web server logs. We collect this basic information from everybody, whether they have an account or not.

The information we collect about all visitors to our website includes:

the visitor’s browser type
language preference
referring site
the date and time of each visitor request

We also collect potentially personally-identifying information like Internet Protocol (IP) addresses.

Why do we collect this?

We collect this information to better understand how our website visitors use Read the Docs, and to monitor and protect the security of the website.

Information from users with accounts

If you create an account, we require some basic information at the time of account creation. You will create your own user name and password, and we will ask you for a valid email account. You also have the option to give us more information if you want to, and this may include “User Personal Information.”

“User Personal Information” is any information about one of our users which could, alone or together with other information, personally identify him or her. Information such as a user name and password, an email address, a real name, and a photograph are examples of “User Personal Information.”

User Personal Information does not include aggregated, non-personally identifying information. We may use aggregated, non-personally identifying information to operate, improve, and optimize our website and service.

Why do we collect this information?

We need your User Personal Information to create your account, and to provide the services you request.
We use your User Personal Information, specifically your user name, to identify you on Read the Docs.
We use it to fill out your profile and share that profile with other users.
We will use your email address to communicate with you but it is not shared publicly.
We limit our use of your User Personal Information to the purposes listed in this Privacy Statement. If we need to use your User Personal Information for other purposes, we will ask your permission first. You can always see what information we have in your user account.

What information Read the Docs does not collect

We do not intentionally collect sensitive personal information, such as social security numbers, genetic data, health information, or religious information.

Documentation Sites hosted on Read the Docs are public, anyone (including us) may view their contents. If you have included private or sensitive information in your Documentation Site, such as email addresses, that information may be indexed by search engines or used by third parties.

Read the Docs for Business may host private projects which we treat as confidential and we only access them for support reasons, with your consent, or if required to for security reasons

If you’re a child under the age of 13, you may not have an account on Read the Docs. Read the Docs does not knowingly collect information from or direct any of our content specifically to children under 13. If we learn or have reason to suspect that you are a user who is under the age of 13, we will unfortunately have to close your account. We don’t want to discourage you from writing software documentation, but those are the rules.

How we share the information we collect

We do not share, sell, rent, or trade User Personal Information with third parties for their commercial purposes.

We do not disclose User Personal Information outside Read the Docs, except in the situations listed in this section or in the section below on compelled disclosure.

We do share certain aggregated, non-personally identifying information with others about how our users, collectively, use Read the Docs. For example, we may compile statistics on the prevalence of different types of documentation across Read the Docs for a blog post or popularity of programming languages for advertising partners.

We do host advertising on Documentation Sites. This advertising is first-party advertising hosted by Read the Docs. We do not run any code from advertisers and all ad images are hosted on Read the Docs’ servers. For more details, see our document on Advertising details.

We may use User Personal Information with your permission, so we can perform services you have requested. For example, if you request service on commercially hosted docs, we will ask your permission to sync your private repositories.

We may share User Personal Information with a limited number of third party vendors who process it on our behalf to provide or improve our service, and who have agreed to privacy restrictions similar to our own Privacy Statement. For more details, see our next section on third parties.

Third party vendors

As we mentioned, we may share some information with third party vendors or it may be collected by them on our behalf. The information collected and stored by third parties is subject to their policies and practices. This list will be updated from time to time and we encourage you to check back periodically.

Payment processing

Should you choose to become a Supporter, purchase a Gold membership, or become a subscriber to Read the Docs’ commercial hosting product, your payment information and details will be processed by Stripe. Read the Docs does not store your payment information.

Site monitoring

Read the Docs uses Sentry and New Relic to diagnose errors and improve the performance of our site. Both companies take part in the EU-US Privacy Shield framework. We aim to minimize the amount of personal information shared, but the information may include your IP address.

Analytics

We go into detail on analytics in a separate section specific to analytics.

Support desk

Read the Docs uses Front to manage support requests. If you request support – typically via email – Front may process your contact information.

Public information on Read the Docs

Most of Read the Docs is public-facing including user names, project names, and Documentation Sites. If your content is public-facing, third parties may access it. We do not sell that content; it is yours.

Our use of cookies and tracking

Do Not Track

Read the Docs supports Do Not Track (DNT) and respects users’ tracking preferences. Specifically, we support the W3C’s tracking preference expression and the EFF’s DNT Policy.

For Read the Docs, this means:

We do not do behavioral ad targeting regardless of your DNT preference.
Regardless of DNT preference, our logs that contain IP addresses and user agent strings are deleted after 10 days unless a DNT exception applies.
Our full DNT policy is available here.

Our DNT policy applies without reservation to Read the Docs Community and Read the Docs for Business. A best effort is made to apply this to Documentation Sites, but we do not have complete control over the contents of these sites.

For more details about DNT, visit All About Do Not Track.

Important

Due to the nature of our environment where documentation is built as necessary, the DNT analytics opt-out for Documentation Sites only applies for those sites generated after May 1, 2018.

Cookies

Read the Docs uses cookies to make interactions with our service easy and meaningful. We use cookies to keep you logged in, remember your preferences, and provide information for future development of Read the Docs.

A cookie is a small piece of text that our web server stores on your computer or mobile device, which your browser sends to us when you return to our site. Cookies do not necessarily identify you if you are merely visiting Read the Docs; however, a cookie may store a unique identifier for each logged in user. The cookies Read the Docs sets are essential for the operation of the website, or are used for performance or functionality. By using our website, you agree that we can place these types of cookies on your computer or device. If you disable your browser or device’s ability to accept cookies, you will not be able to log in to Read the Docs.

Plausible

We use Plausible as a third party analytics service, but we don’t use it to track you individually or collect your User Personal Information. We use Plausible to collect information about how our website performs and how our users, in general, navigate through and use Read the Docs. This helps us evaluate our users’ use of Read the Docs; compile statistical reports on activity; and improve our content and website performance.

Plausible gathers certain simple, non-personally identifying information over time, such as browser type, internet service provider, referring and exit pages, time stamp, and similar data about your use of Read the Docs. We do not link this information to any of your personal information such as your user name.

Read the Docs will not, nor will we allow any third party to, use the Plausible tool to track our users individually or collect any User Personal Information.

How Read the Docs secures your information

Read the Docs takes all measures reasonably necessary to protect User Personal Information from unauthorized access, alteration, or destruction; maintain data accuracy; and help ensure the appropriate use of User Personal Information. We follow generally accepted industry standards to protect the personal information submitted to us, both during transmission and once we receive it.

No method of transmission, or method of electronic storage, is 100% secure. Therefore, we cannot guarantee its absolute security.

Read the Docs’ global privacy practices

Information that we collect will be stored and processed in the United States in accordance with this Privacy Policy. However, we understand that we have users from different countries and regions with different privacy expectations, and we try to meet those needs.

We provide the same standard of privacy protection to all our users around the world, regardless of their country of origin or location, Additionally, we require that if our vendors or affiliates have access to User Personal Information, they must comply with our privacy policies and with applicable data privacy laws.

In particular:

Read the Docs provides clear methods of unambiguous, informed consent at the time of data collection, when we do collect your personal data.
We collect only the minimum amount of personal data necessary, unless you choose to provide more. We encourage you to only give us the amount of data you are comfortable sharing.
We offer you simple methods of accessing, correcting, or deleting the data we have collected.
We also provide our users a method of recourse and enforcement.

Resolving complaints

If you have concerns about the way Read the Docs is handling your User Personal Information, please let us know immediately by emailing us at privacy@readthedocs.org.

How we respond to compelled disclosure

Read the Docs may disclose personally-identifying information or other information we collect about you to law enforcement in response to a valid subpoena, court order, warrant, or similar government order, or when we believe in good faith that disclosure is reasonably necessary to protect our property or rights, or those of third parties or the public at large.

In complying with court orders and similar legal processes, Read the Docs strives for transparency. When permitted, we will make a reasonable effort to notify users of any disclosure of their information, unless we are prohibited by law or court order from doing so, or in rare, exigent circumstances.

How you can access and control the information we collect

If you’re already a Read the Docs user, you may access, update, alter, or delete your basic user profile information by editing your user account.

Data retention and deletion

Read the Docs will retain User Personal Information for as long as your account is active or as needed to provide you services.

We may retain certain User Personal Information indefinitely, unless you delete it or request its deletion. For example, we don’t automatically delete inactive user accounts, so unless you choose to delete your account, we will retain your account information indefinitely.

If you would like to delete your User Personal Information, you may do so in your user account. We will retain and use your information as necessary to comply with our legal obligations, resolve disputes, and enforce our agreements, but barring legal requirements, we will delete your full profile.

Our web server logs for Read the Docs Community, Read the Docs for Business, and Documentation Sites are deleted after 10 days barring legal obligations.

Changes to our Privacy Policy

We reserve the right to revise this Privacy Policy at any time. If we change this Privacy Policy in the future, we will post the revised Privacy Policy and update the “Effective Date,” above, to reflect the date of the changes.

Contacting Read the Docs

Questions regarding Read the Docs’ Privacy Policy or information practices should be directed to privacy@readthedocs.org.

Security policy

Read the Docs adheres to the following security policies and procedures with regards to development, operations, and managing infrastructure. You can also find information on how we handle specific user data in our Privacy Policy.

Our engineering team monitors several sources for security threats and responds accordingly to security threats and notifications.

We monitor 3rd party software included in our application and in our infrastructure for security notifications. Any relevant security patches are applied and released immediately.
We monitor our infrastructure providers for signs of attacks or abuse and will respond accordingly to threats.

Infrastructure

Read the Docs infrastructure is hosted on Amazon Web Services (AWS). We also use Cloudflare services to mitigate attacks and abuse.

See also

Data and data center

All user data is stored in the USA in multi-tenant datastores in Amazon Web Services data centers. Physical access to these data centers is secured with a variety of controls to prevent unauthorized access.

Application

Encryption in transit: All documentation, application dashboard, and API access is transmitted using SSL encryption. We do not support unencrypted requests, even for public project documentation hosting.
Temporary repository storage: We do not store or cache user repository data, temporary storage is used for every project build on Read the Docs.
Authentication: Read the Docs supports SSO with GitHub, GitLab, Bitbucket, and Google Workspaces (formerly G Suite).
Payment security: We do not store or process any payment details. All payment information is stored with our payment provider, Stripe – a PCI-certified level 1 payment provider.

Engineering and operational practices

Immutable infrastructure: We don’t make live changes to production code or infrastructure. All changes to our application and our infrastructure go through the same code review process before being applied and released.
Continuous integration: We are constantly testing changes to our application code and operational changes to our infrastructure.
Incident response: Our engineering team is on a rotating on-call schedule to respond to security or availability incidents.

Account security

All traffic is encrypted in transit so your login is protected.
Read the Docs stores only one-way hashes of all passwords. Nobody at Read the Docs has access to your passwords.
Account login is protected from brute force attacks with rate limiting.
While most projects and docs on Read the Docs are public, we treat your private repositories and private documentation as confidential and Read the Docs employees may only view them with your explicit permission in response to your support requests, or when required for security purposes.
You can read more about account privacy in our Privacy Policy.

Security reports

Security is extremely important to us at Read the Docs. We follow generally accepted industry standards to protect the personal information submitted to us, both during transmission and once we receive it. In the spirit of transparency, we are committed to responsible reporting and disclosure of security issues.

See also

Security policy: Read our policy for security, which we base our security handling and reporting on.

Supported versions

Only the latest version of Read the Docs will receive security updates. We don’t support security updates for custom installations of Read the Docs.

Reporting a security issue

If you believe you’ve discovered a security issue at Read the Docs, please contact us at security@readthedocs.org (optionally using our PGP key). We request that you please not publicly disclose the issue until it has been addressed by us.

You can expect:

We will respond acknowledging your email typically within one business day.
We will follow up if and when we have confirmed the issue with a timetable for the fix.
We will notify you when the issue is fixed.
We will create a GitHub advisory and publish it when the issue has been fixed and deployed in our platforms.

PGP key

You may use this PGP key to securely communicate with us and to verify signed messages you receive from us.

Bug bounties

While we sincerely appreciate and encourage reports of suspected security problems, please note that the Read the Docs is an open source project, and does not run any bug bounty programs. But we will gladly give credit to you and/or your organization for responsibly reporting security issues.

Security issue archive

You can see all past reports at https://github.com/readthedocs/readthedocs.org/security/advisories.

Version 3.2.0

Version 3.2.0 resolved an issue where a specially crafted request could result in a DNS query to an arbitrary domain.

This issue was found by Cyber Smart Defence who reported it as part of a security audit to a firm running a local installation of Read the Docs.

Release 2.3.0

Version 2.3.0 resolves a security issue with translations on our community hosting site that allowed users to modify the hosted path of a target project by adding it as a translation project of their own project. A check was added to ensure project ownership before adding the project as a translation.

In order to add a project as a translation now, users must now first be granted ownership in the translation project.

DMCA takedown policy

These are the guidelines that Read the Docs follows when handling DMCA takedown requests and takedown counter requests. If you are a copyright holder wishing to submit a takedown request, or an author that has been notified of a takedown request, please familiarize yourself with our process. You will be asked to confirm that you have reviewed information if you submit a request or counter request.

We aim to keep this entire process as transparent as possible. Our process is modeled after GitHub’s DMCA takedown process, which we appreciate for its focus on transparency and fairness. All requests and counter requests will be posted to this page below, in the Request Archive. These requests will be redacted to remove all identifying information, except for Read the Docs user and project names.

Takedown process

Here are the steps the Read the Docs will follow in the takedown request process:

Copyright holder submits a request

This request, if valid, will be posted publicly on this page, down below. The author affected by the takedown request will be notified with a link to the takedown request.

For more information on submitting a takedown request, see: Submitting a Request

Author is contacted

The author of the content in question will be asked to make changes to the content specified in the takedown request. The author will have 24 hours to make these changes. The copyright holder will be notified if and when this process begins

Author acknowledges changes have been made

The author must notify Read the Docs that changes have been made within 24 hours of receiving a takedown request. If the author does not respond to this request, the default action will be to disable the Read the Docs project and remove any hosted versions

Copyright holder review

If the author has made changes, the copyright holder will be notified of these changes. If the changes are sufficient, no further action is required, though copyright holders are welcome to submit a formal retraction. If the changes are not sufficient, the author’s changes can be rejected. If the takedown request requires alteration, a new request must be submitted. If Read the Docs does not receive a review response from the copyright holder within 2 weeks, the default action at this step is to assume the takedown request has been retracted.

Content may be disabled

If the author does not respond to a request for changes, or if the copyright holder has rejected the author’s changes during the review process, the documentation project in question will be disabled.

Author submits a counter request

If the author believes their content was disabled as a result of a mistake, a counter request may be submitted. It would be advised that authors seek legal council before continuing. If the submitted counter request is sufficiently detailed, this counter will also be added to this page. The copyright holder will be notified, with a link to this counter request.

For more information on submitting a counter request, see: Submitting a Counter

Copyright holder may file legal action: At this point, if the copyright holder wishes to keep the offending content disabled, the copyright holder must file for legal action ordering the author refrain from infringing activities on Read the Docs. The copyright holder will have 2 weeks to supply Read the Docs with a copy of a valid legal complaint against the author. The default action here, if the copyright holder does not respond to this request, is to re-enable the author’s project.

Submitting a request

Your request must:

Acknowledge this process: You must first acknowledge you are familiar with our DMCA takedown request process. If you do not acknowledge that you are familiar with our process, you will be instructed to review this information.
Identify the infringing content: You should list URLs to each piece of infringing content. If you allege that the entire project is infringing on copyrights you hold, please specify the entire project as infringing.
Identify infringement resolution: You will need to specify what a user must do in order to avoid having the rest of their content disabled. Be as specific as possible with this. Specify if this means adding attribution, identify specific files or content that should be removed, or if you allege the entire project is infringing, your should be specific as to why it is infringing.
Include your contact information: Include your name, email, physical address, and phone number.
Include your signature: This can be a physical or electronic signature.

Please complete this takedown request template and send it to: support@readthedocs.com

Submitting a counter

Your counter request must:

Acknowledge this process: You must first acknowledge you are familiar with our DMCA takedown request process. If you do not acknowledge that you are familiar with our process, you will be instructed to review this information.
Identify the infringing content that was removed: Specify URLs in the original takedown request that you wish to challenge.
Include your contact information: Include your name, email, physical address, and phone number.
Include your signature: This can be a physical or electronic signature.

Requests can be submitted to: support@readthedocs.com

Request archive

For better transparency into copyright ownership and the DMCA takedown process, Read the Docs maintains this archive of previous DMCA takedown requests. This is modeled after GitHub’s DMCA archive.

The following DMCA takedown requests have been submitted:

2022-06-07

Note

The project maintainer was notified about this report and instructed to submit a counter if they believed this request was invalid. The user removed the project manually, and no further action was required.

Are you the copyright owner or authorized to act on the copyright owner’s behalf?: Yes
What work was allegedly infringed? If possible, please provide a URL:: https://www.dicomstandard.org/current
What files or project should be taken down? You should list URLs to each piece of infringing content. If you allege that the entire project is infringing on copyrights you hold, please specify the entire project as infringing:: https://dicom-standard.readthedocs.io/en/latest/index.html
Is the work licensed under an open source license?: No
What would be the best solution for the alleged infringement?: Complete Removal.
Do you have the alleged infringer’s contact information? Yes. If so, please provide it:: [private]
Type (or copy and paste) the following statement: “I have a good faith belief that use of the copyrighted materials described above on the infringing web pages is not authorized by the copyright owner, or its agent, or the law. I have taken fair use into consideration.”: I have a good faith belief that use of the copyrighted materials described above on the infringing web pages is not authorized by the copyright owner, or its agent, or the law. I have taken fair use into consideration.
Type (or copy and paste) the following statement: “I swear, under penalty of perjury, that the information in this notification is accurate and that I am the copyright owner, or am authorized to act on behalf of the owner, of an exclusive right that is allegedly infringed.”: I swear, under penalty of perjury, that the information in this notification is accurate and that I am the copyright owner, or am authorized to act on behalf of the owner, of an exclusive right that is allegedly infringed.
Please confirm that you have read our Takedown Policy: https://docs.readthedocs.io/en/latest/dmca/index.html: Yes
So that we can get back to you, please provide either your telephone number or physical address:: [private]
Please type your full legal name below to sign this request:: [private]

Data Processing Addendum (DPA)

Sub-processor list

Effective:: April 16, 2021
Last updated:: August 9, 2024

Read the Docs for Business uses services from the following sub-processors to provide documentation hosting services. This document supplements our Data Processing Addendum and may be separately updated on a periodic basis. A sub-processor is a third party data processor who has or potentially will have access to or will process personal data.

See also

Previous versions of this document, as well as the change history to this document, are available on GitHub

Infrastructure

Amazon Web Services, Inc.: Cloud infrastructure provider.

Services

Elasticsearch B.V.: Hosted ElasticSearch services for documentation search. Search indexes do not include user data.
Sendgrid, Inc.: Provides email delivery to dashboard and admin users for site notifications and other generated messages. The body of notification emails can include user information, including email address.
Plausible: Website analytics for dashboard and Read the Docs owned documentation sites.
Stripe Inc.: Subscription payment provider. Data collected can include user data necessary to process payment transactions, however this data is not processed directly by Read the Docs.

Monitoring

New Relic: Application performance analytics. Data collected can include user data and visitor data used within application code.
Sentry: Error analytics service used to log and track application errors. Error reports can include arguments passed to application code, which can include user and visitor data.

Support

FrontApp, Inc.: Customer email support service. Can have access to user data, including user email and IP address, and stores communications related to user data.

Read the Docs can execute a DPA with any customer that receives data from the EU. You can complete this by reviewing and accepting the following pre-signed agreement:

Review the Read the Docs Data Processing Addendum

See also

Read the Docs sub-processor list: An up-to-date list of the sub-processors we use for hosting services.

Abandoned projects policy: Our policy of taking action on abandoned projects.
Unofficial and unmaintained projects policy: Our policy of taking action on unofficial and unmaintained projects.
Terms of Service: The terms of service for using Read the Docs Community and Read the Docs for Business. You may instead have a master services agreement for your subscription if you have a custom or enterprise contract.
Privacy Policy: Our policy on collecting, storing, and protecting user and visitor data.
Security policy: Our policies around application and infrastructure security.
Security reports: How we respond to security incidents and how you report a security issue.
Data Processing Addendum (DPA): For GDPR and CCPA compliance, we provide a data processing addendum for Read the Docs for Business customers.
DMCA takedown policy: Our process for taking down content based on DMCA requests and how to submit requests.

Advertising

Advertising is the single largest source of funding for Read the Docs. It allows us to:

Serve over 35 million pages of documentation per month
Serve over 40 TB of documentation per month
Host over 80,000 open source projects and support over 100,000 users
Pay a small team of dedicated full-time staff

Many advertising models involve tracking users around the internet, selling their data, and privacy intrusion in general. Instead of doing that, we built an Ethical Advertising model that respects user privacy.

We recognize that advertising is not for everyone. You may opt out of paid advertising although you will still see community ads. Gold members may also remove advertising from their projects for all visitors.

For businesses looking to remove advertising, please consider Read the Docs for Business.

EthicalAds

Read the Docs is a large, free web service. There is one proven business model to support this kind of site: Advertising. We are building the advertising model we want to exist, and we’re calling it EthicalAds.

EthicalAds respect users while providing value to advertisers. We don’t track you, sell your data, or anything else. We simply show ads to users, based on the content of the pages you look at. We also give 10% of our ad space to community projects, as our way of saying thanks to the open source community.

We talk a bit below about our worldview on advertising, if you want to know more.

Are you a marketer?

We built a whole business around privacy-focused advertising. If you’re trying to reach developers, we have a network of hand-approved sites (including Read the Docs) where your ads are shown.

Feedback

We’re a community, and we value your feedback. If you ever want to reach out about this effort, feel free to shoot us an email.

You can opt out of having paid ads on your projects, or seeing paid ads if you want. You will still see community ads, which we run at no cost that promote community projects.

Our worldview

We’re building the advertising model we want to exist:

We don’t track you
We don’t sell your data
We host everything ourselves, no third-party scripts or images

We’re doing newspaper advertising, on the internet. For a hundred years, newspapers put an ad on the page, some folks would see it, and advertisers would pay for this. This is our model.

So much ad tech has been built to track users. Following them across the web, from site to site, showing the same ads and gathering data about them. Then retailers sell your purchase data to try and attribute sales to advertising. Now there is an industry in doing fake ad clicks and other scams, which leads the ad industry to track you even more intrusively to know more about you. The current advertising industry is in a vicious downward spiral.

As developers, we understand the massive downsides of the current advertising industry. This includes malware, slow site performance, and huge databases of your personal data being sold to the highest bidder.

The trend in advertising is to have larger and larger ads. They should run before your content, they should take over the page, the bigger, weirder, or flashier the better.

We opt out

We don’t store personal information about you.
We only keep track of views and clicks.
We don’t build a profile of your personality to sell ads against.
We only show high quality ads from companies that are of interest to developers.

We are running a single, small, unobtrusive ad on documentation pages. The products should be interesting to you. The ads won’t flash or move.

We run the ads we want to have on our site, in a way that makes us feel good.

Additional details

We have additional documentation on the technical details of our advertising including our Do Not Track policy and our use of analytics.
We have an advertising FAQ written for advertisers.
We have gone into more detail about our views in our blog post about this topic.
Eric Holscher, one of our co-founders talks a bit more about funding open source this way on his blog.
After proving our ad model as a way to fund open source and building our ad serving infrastructure, we launched the EthicalAds network to help other projects be sustainable.

Join us

We’re building the advertising model we want to exist. We hope that others will join us in this mission:

If you’re a developer, talk to your marketing folks about using advertising that respects your privacy.
If you’re a marketer, vote with your dollars and support us in building the ad model we want to exist. Get more information on what we offer.

Community Ads

There are a large number of projects, conferences, and initiatives that we care about in the software and open source ecosystems. A large number of them operate like we did in the past, with almost no income. Our Community Ads program will highlight some of these projects.

There are a few qualifications for our Community Ads program:

Your organization and the linked site should not be trying to entice visitors to buy a product or service. We make an exception for conferences around open source projects if they are run not for profit and soliciting donations for open source projects.
A software project should have an OSI approved license.
We will not run a community ad for an organization tied to one of our paid advertisers.

We’ll show 10% of our ad inventory each month to support initiatives that we care about. Please complete an application to be considered for our Community Ads program.

Opting out

We have added multiple ways to opt out of the advertising on Read the Docs.

Gold members may remove advertising from their projects for all visitors.
You can opt out of seeing paid advertisements on documentation pages:
- Go to the drop down user menu in the top right of the Read the Docs dashboard and clicking Settings (https://app.readthedocs.org/accounts/edit/).
- On the Advertising tab, you can deselect See paid advertising.
You will still see community ads for open source projects and conferences.
Project owners can also opt out of paid advertisements for their projects. You can change these options:
- Go to your project page (/projects/<slug>/)
- Go to Admin > Advertising
- Change your advertising settings
If you are part of a company that uses Read the Docs to host documentation for a commercial product, we offer Read the Docs for Business that offers a completely ad-free experience, additional build resources, and other great features like CDN support and private documentation.
If you would like to completely remove advertising from your open source project, but our commercial plans don’t seem like the right fit, please get in touch to discuss alternatives to advertising.

Advertising details

Read the Docs largely funds our operations and development through advertising. However, we aren’t willing to compromise our values, document authors, or site visitors simply to make a bit more money. That’s why we created our ethical advertising initiative.

We get a lot of inquiries about our approach to advertising which range from questions about our practices to requests to partner. The goal of this document is to shed light on the advertising industry, exactly what we do for advertising, and how what we do is different. If you have questions or comments, send us an email or open an issue on GitHub.

Other ad networks’ targeting

Some ad networks build a database of user data in order to predict the types of ads that are likely to be clicked. In the advertising industry, this is called behavioral targeting. This can include data such as:

sites a user has visited
a user’s search history
ads, pages, or stories a user has clicked on in the past
demographic information such as age, gender, or income level

Typically, getting a user’s page visit history is accomplished by the use of trackers (sometimes called beacons or pixels). For example, if a site uses a tracker from an ad network and a user visits that site, the site can now target future advertising to that user – a known past visitor – with that network. This is called retargeting.

Other ad predictions are made by grouping similar users together based on user data using machine learning. Frequently this involves an advertiser uploading personal data on users (often past customers of the advertiser) to an ad network and telling the network to target similar users. The idea is that two users with similar demographic information and similar interests would like the same products. In ad tech, this is known as lookalike audiences or similar audiences.

Understandably, many people have concerns about these targeting techniques. The modern advertising industry has built enormous value by centralizing massive amounts of data on as many people as possible.

Our targeting details

Read the Docs doesn’t use the above techniques. Instead, we target based solely upon:

Details of the page where the advertisement is shown including:
- The name, keywords, or programming language associated with the project being viewed
- Content of the page (eg. H1, title, theme, etc.)
- Whether the page is being viewed from a mobile device
General geography
- We allow advertisers to target ads to a list of countries or to exclude countries from their advertising. For ads targeting the USA, we also support targeting by state or by metro area (DMA specifically).
- We geolocate a user’s IP address to a country when a request is made.

Where ads are shown

We can place ads in:

the sidebar navigation
the footer of the page
on search result pages
a small footer fixed to the bottom of the viewport
on 404 pages (rare)

We never show more than 1 ad on a page.

Do Not Track Policy

Read the Docs supports Do Not Track (DNT) and respects users’ tracking preferences. For more details, see the Do Not Track section of our privacy policy.

Ad serving infrastructure

Our entire ad server is open source, so you can inspect how we’re doing things. We believe strongly in open source, and we practice what we preach.

Analytics

Analytics are a sensitive enough issue that they require their own section.

Google Analytics is a contentious issue inside Read the Docs and in our community. Some users are very sensitive and privacy conscious to usage of GA. Some authors want their own analytics on their docs to see the usage their docs get. The developers at Read the Docs understand that different users have different priorities and we try to respect the different viewpoints as much as possible while also accomplishing our own goals.

Why we use analytics

Advertisers ask us questions that are easily answered with an analytics solution like “how many users do you have in Switzerland browsing Python docs?”. We need to be able to easily get this data. We also use data from GA for some development decisions such as what browsers to support (or not) or how much usage a particular page or feature gets.

Alternatives

We are always exploring our options with respect to analytics. There are alternatives but none of them are without downsides. Some alternatives are:

Run a different cloud analytics solution from a provider other than Google (eg. Parse.ly, Matomo Cloud, Adobe Analytics). We priced a couple of these out based on our load and they are very expensive. They also just substitute one problem of data sharing with another.
Send data to GA (or another cloud analytics provider) on the server side and strip or anonymize personal data such as IPs before sending them. This would be a complex solution and involve additional infrastructure, but it would have many advantages. It would result in a loss of data on “sessions” and new vs. returning visitors which are of limited value to us.
Run a local JavaScript based analytics solution (eg. Matomo community). This involves additional infrastructure that needs to be always up. Frequently there are very large databases associated with this. Many of these solutions aren’t built to handle Read the Docs’ load.
Run a local analytics solution based on web server log parsing. This has the same infrastructure problems as above while also not capturing all the data we want (without additional engineering) like the programming language of the docs being shown or whether the docs are built with Sphinx or something else.

Ad blocking

Ad blockers fulfill a legitimate need to mitigate the significant downsides of advertising from tracking across the internet, security implications of third-party code, and impacting the UX and performance of sites.

At Read the Docs, we specifically didn’t want those things. That’s why we built the our Ethical Ad initiative with only relevant, unobtrusive ads that respect your privacy and don’t do creepy behavioral targeting.

Advertising is the single largest source of funding for Read the Docs. To keep our operations sustainable, we ask that you either allow our EthicalAds or go ad-free.

Allowing EthicalAds

If you use AdBlock or AdBlockPlus and you allow acceptable ads or privacy-friendly acceptable ads then you’re all set. Advertising on Read the Docs complies with both of these programs.

If you prefer not to allow acceptable ads but would consider allowing ads that benefit open source, please consider subscribing to either the wider Open Source Ads list or simply the Read the Docs Ads list.

Note

Because of the way Read the Docs is structured where docs are hosted on many different domains, adding a normal ad block exception will only allow that single domain not Read the Docs as a whole.

Going ad-free

Gold members may completely remove advertising for all visitors to their projects. Thank you for supporting Read the Docs.

Note

Previously, Gold members or Supporters were provided an ad-free reading experience across all projects on Read the Docs while logged-in. However, the cross-site cookies needed to make that work are no longer supported by major browsers outside of Chrome, and this feature has been removed.

Statistics and data

It can be really hard to find good data on ad blocking. In the spirit of transparency, here is the data we have on ad blocking at Read the Docs.

32% of Read the Docs users use an ad blocker
Of those, a little over 50% allow acceptable ads
Read the Docs users running ad blockers click on ads at about the same rate as those not running an ad blocker.
Comparing with our server logs, roughly 28% of our hits did not register a Google Analytics (GA) pageview due to an ad blocker, privacy plugin, disabling JavaScript, or another reason.
Of users who do not block GA, about 6% opt out of analytics on Read the Docs by enabling Do Not Track.

Customizing advertising

Warning

This document details features that are a work in progress. To discuss this document, please get in touch in the issue tracker.

In addition to allowing users and documentation authors to opt out of advertising, we allow some additional controls for documentation authors to control the positioning and styling of advertising. This can improve the performance of advertising or make sure the ad is in a place where it fits well with the documentation.

Controlling the placement of an ad

It is possible for a documentation author to instruct Read the Docs to position advertising in a specific location. This is done by adding a specific element to the generated body. The ad will be inserted into this container wherever this element is in the document body.

<div id="ethical-ad-placement"></div>

In Sphinx

In Sphinx, this is typically done by adding a new template (under templates_path) for inclusion in the HTML sidebar in your conf.py.

## In conf.py
html_sidebars = {
    "**": [
        "localtoc.html",
        "ethicalads.html",  # Put the ad below the navigation but above previous/next
        "relations.html",
        "sourcelink.html",
        "searchbox.html",
    ]
}

<!-- In _templates/ethicalads.html -->
<div id="ethical-ad-placement"></div>

The story of Read the Docs

Documenting projects is hard, hosting them shouldn’t be. Read the Docs was created to make hosting documentation simple.

Read the Docs was started with a couple main goals in mind. The first goal was to encourage people to write documentation, by removing the barrier of entry to hosting. The other goal was to create a central platform for people to find documentation. Having a shared platform for all documentation allows for innovation at the platform level, allowing work to be done once and benefit everyone.

Documentation matters, but its often overlooked. We think that we can help a documentation culture flourish. Great projects, such as Django and SQLAlchemy, and projects from companies like Mozilla, are already using Read the Docs to serve their documentation to the world.

The site has grown quite a bit over the past year. Our look back at 2013 shows some numbers that show our progress. The job isn’t anywhere near done yet, but it’s a great honor to be able to have such an impact already.

We plan to keep building a great experience for people hosting their docs with us, and for users of the documentation that we host.

Sponsors of Read the Docs

Running Read the Docs isn’t free, and the site wouldn’t be where it is today without generous support of our sponsors. Below is a list of all the folks who have helped the site financially, in order of the date they first started supporting us.

Current sponsors

AWS - They cover all of our hosting expenses every month. This is a pretty large sum of money, averaging around $5,000/mo.
Cloudflare - Cloudflare is providing us with an enterprise plan of their SSL for SaaS Providers product that enables us to provide SSL certificates for custom domains.
Chan Zuckerberg Initiative - Through their “Essential Open Source Software for Science” programme, they fund our ongoing efforts to improve scientific documentation and make Read the Docs a better service for scientific projects.
You? (Email us at hello@readthedocs.org for more info)

Past sponsors

Documentation in scientific and academic publishing

On this page, we explore some of the many tools and practices that software documentation and academic writing share. If you are working within the field of science or academia, this page can be used as an introduction.

Documentation and technical writing are broad fields. Their tools and practices have grown relevant to most scientific activities. This includes building publications, books, educational resources, interactive data science, resources for data journalism and full-scale websites for research projects and courses.

Here’s a brief overview of some features that people in science and academic writing love about Read the Docs:

We want science communities to use Read the Docs and to be part of the documentation community 💞

Getting started: Jupyter Book

Jupyter Book on Read the Docs brings you the rich experience of computed Jupyter documents built together with a modern documentation tool. The results are beautiful and automatically deployed websites, built with Sphinx and Executable Book + all the extensions available in this ecosystem.

Here are some popular activities that are well-supported by Jupyter Book:

Publications and books
Course and research websites
Interactive classroom activities
Data science software documentation

Visit the gallery of solutions built with Jupyter Book »

Ready to get started?

All new to this? Take the official Jupyter Book Tutorial »
Curious for practical code? See the list of example projects »
Familiar with Sphinx? Read How to use Jupyter notebooks in Sphinx »

Examples and users

Read the Docs community for science is already big and keeps growing. The Jupyter Project itself and the many sub-projects of Jupyter are built and published with Read the Docs.

Jupyter Project Documentation

https://docs.jupyter.org/

Chainladder - Property and Casualty Loss Reserving in Python

https://chainladder-python.readthedocs.io/

Feature-engine - A Python library for Feature Engineering and Selection

https://feature-engine.readthedocs.io/en/latest/

Read the Docs open source philosophy

Read the Docs is open source software. We have licensed the code base as MIT, which provides almost no restrictions on the use of the code.

However, as a project there are things that we care about more than others. We built Read the Docs to support documentation in the open source community. The code is open for people to contribute to, so that they may build features into https://app.readthedocs.org that they want. We also believe sharing the code openly is a valuable learning tool, especially for demonstrating how to collaborate and maintain an enormous website.

Official support

The time of the core developers of Read the Docs is limited. We provide official support for the following things:

Local development on the Python code base
Usage of https://app.readthedocs.org for open source projects
Bug fixes in the code base, as it applies to running it on https://app.readthedocs.org

Unsupported

There are use cases that we don’t support, because it doesn’t further our goal of promoting documentation in the open source community.

We do not support:

Specific usage of Sphinx and Mkdocs, that don’t affect our hosting
Custom installations of Read the Docs at your company
Installation of Read the Docs on other platforms
Any installation issues outside of the Read the Docs Python Code

Rationale

Read the Docs was founded to improve documentation in the open source community. We fully recognize and allow the code to be used for internal installs at companies, but we will not spend our time supporting it. Our time is limited, and we want to spend it on the mission that we set out to originally support.

If you feel strongly about installing Read the Docs internal to a company, we will happily link to third party resources on this topic. Please open an issue with a proposal if you want to take on this task.

Read the Docs team

readthedocs.org is the largest open source documentation hosting service. Today we:

Serve over 55 million pages of documentation a month
Serve over 40 TB of documentation a month
Host over 80,000 open source projects and support over 100,000 users

Read the Docs is provided as a free service to the open source community, and we hope to maintain a reliable and stable hosting platform for years to come.

See also

Our website: Who we are: More information about the staff and contributors of Read the Docs.

Teams

The Backend Team folks develop the Django code that powers the backend of the project.
The members of the Frontend Team care about UX, CSS, HTML, and JavaScript, and they maintain the project UI as well as the Sphinx theme.
As part of operating the site, members of the Operations Team maintain a 24/7 on-call rotation. This means that folks have to be available and have their phone in service.
The members of the Advocacy Team spread the word about all the work we do, and seek to understand the users priorities and feedback.
The Support Team helps our thousands of users using the service, addressing tasks like resetting passwords, enable experimental features, or troubleshooting build errors.

Note

Please don’t email us personally for support on Read the Docs. You can use our support form for any issues you may have.

Site support

Read the Docs offers support for projects on our Read the Docs for Business and Read the Docs Community platforms. We’re happy to assist with any questions or problems you have using either of our platforms.

Note

Read the Docs does not offer support for questions or problems with documentation tools or content. If you have a question or problem using a particular documentation tool, you should refer to external resources for help instead.

Some examples of requests that we support are:

“How do I transfer ownership of a Read the Docs project to another maintainer?”
“Why are my project builds being cancelled automatically?”
“How do I manage my subscription?”

You might also find the answers you are looking for in our documentation guides. These provide step-by-step solutions to common user requests.

Please fill out the form at https://app.readthedocs.com/support/.

Our team responds to support requests within 2 business days or earlier for most plans. Faster support response times and support SLAs are available with plan upgrades.

If you are unable to create or access your account, you can email us at support@readthedocs.com.

External resources

If you have questions about how to use a documentation tool or authoring content for your project, or have an issue that isn’t related to a bug with Read the Docs, Stack Overflow is the best place for your question.

Examples of good questions for Stack Overflow are:

“What is the best way to structure the table of contents across a project?”
“How do I structure translations inside of my project for easiest contribution from users?”
“How do I use Sphinx to use SVG images in HTML output but PNG in PDF output?”

Tip

Tag questions with read-the-docs so other folks can find them easily.

Bug reports

If you have an issue with the actual functioning of Read the Docs, you can file bug reports on our GitHub issue tracker. You can also contribute changes and fixes to Read the Docs, as the code is open source.

Glossary

This page includes a number of terms that we use in our documentation, so that you have a reference for how we’re using them.

CI/CD

CI/CD is a common way to write Continuous Integration and Continuous Deployment. In some scenarios, they exist as two separate platforms. Read the Docs is a combined CI/CD platform made for documentation.

configuration file

YAML configuration file (e.g. .readthedocs.yaml) that configures the build process of your project on Read the Docs.

See also

Configuration file overview: Practical steps to add a configuration file to your documentation project.

dashboard

The “admin” site where Read the Docs projects are managed and configured. This varies for our two properties:

Read the Docs for Business: https://app.readthedocs.com/dashboard/

Read the Docs Community: https://app.readthedocs.org/dashboard/

default version

Projects have a default version, usually the latest stable version of a project. The default version is the URL that is redirected to when a users loads the / URL for your project.

diff

A way to see the changes between two pieces of text, which shows the added and removed content with a green and red color respectively.

discoverability

A documentation page is said to be discoverable when a user that needs it can find it through various methods: Navigation, search, and links from other pages are the most typical ways of making content discoverable.

Docs as Code

A term used to describe the workflow of keeping documentation in a Git repository, along with source code. Popular in the open source software movement, and used by many technology companies.

flyout menu

Menu displayed on the documentation, readily accessible for readers, containing the list active versions, links to static downloads, and other useful links. Read more in our Flyout menu page.

GitOps

Denotes the use of code maintained in Git to automate building, testing, and deployment of infrastructure. In terms of documentation, GitOps is applicable for Read the Docs, as the configuration for building documentation is stored in .readthedocs.yaml, and rules for publication of documentation can be automated. Similar to Docs as Code.

maintainer

A maintainer is a special role that only exists on Read the Docs Community. The creator of a project on Read the Docs Community can invite other collaborators as maintainers with full ownership rights.

The maintainer role does not exist on Read the Docs for Business, which instead provides Organizations.

pinning

To pin a requirement means to explicitly specify which version should be used. Pinning software requirements is the most important technique to make a project reproducible.

When documentation builds, software dependencies are installed in their latest versions permitted by the pinning specification. Since software packages are frequently released, we are usually trying to avoid incompatibilities in a new release from suddenly breaking a documentation build.

Examples of Python dependencies:

# Exact pinning: Only allow Sphinx 5.3.0
sphinx==5.3.0

# Loose pinning: Lower and upper bounds result in the latest 5.3.x release
sphinx>=5.3,<5.4

# Very loose pinning: Lower and upper bounds result in the latest 5.x release
sphinx>=5,<6

Read the Docs recommends using exact pinning.

See: How to create reproducible builds.

pre-defined build jobs

Commands executed by Read the Docs when performing the build process. They cannot be overwritten by the user.

project home

Page where you can access all the features of Read the Docs, from having an overview to browsing the latest builds or administering your project.

project page

Another name for project home.

reproducible

A documentation project is said to be reproducible when its sources build correctly on Read the Docs over a period of many years. You can also think of being reproducible as being robust or resillient.

Being “reproducible” is an important positive quality goal of documentation.

When builds are not reproducible and break due to external factors, they need frequent troubleshooting and manual fixing.

The most common external factor is that new versions of software dependencies are released.

See: How to create reproducible builds.

root URL

Home URL of your documentation without the /<lang> and /<version> segments. For projects without custom domains, the one ending in .readthedocs.io/ (for example, https://docs.readthedocs.io as opposed to https://docs.readthedocs.io/en/latest).

slug

A unique identifier for a project or version. This value comes from the project or version name, which is reduced to lowercase letters, numbers, and hyphens. You can retrieve your project or version slugs from our API.

static website

A static site or static website is a collection of HTML files, images, CSS and JavaScript that are served statically, as opposed to dynamic websites that generate a unique response for each request, using databases and user sessions.

Static websites are highly portable, as they do not depend on the webserver. They can also be viewed offline.

Documentation projects served on Read the Docs are static websites.

Tools to manage and generate static websites are commonly known as static site generators and there is a big overlap with documentation tools. Some static site generators are also documentation tools, and some documentation tools are also used to generate normal websites.

For instance, Sphinx is made for documentation but also used for blogging.

subproject

Project A can be configured such that when requesting a URL /projects/<subproject-slug>, the root of project B is returned. In this case, project B is the subproject. Read more in Subprojects.

user-defined build jobs

Commands defined by the user that Read the Docs will execute when performing the build process.

virtualenv

The default way for Python projects to create an isolated environment. This ensures that a reproducible set of dependencies are installed so that you project builds the same way each time.

webhook

A webhook is a special URL that can be called from another service, usually with a secret token. It is commonly used to start a build or a deployment or to send a status update.

There are two important types of webhooks for Read the Docs:

Git providers have webhooks which are special URLs that Read the Docs can call in order to notify about documentation builds.
Read the Docs has a unique webhook for each project that the Git provider calls when changes happen in Git.

See also

How to manually configure a Git repository integration: Manually configuration for Git repositories.
Build failure notifications: Receive notifications when your documentation builds fail.

Read the Docs simplifies managing software documentation by building and hosting your docs automatically, using the Git workflow you already use for code. Treating documentation like code lets your team use tools they already know, and makes keeping your docs updated easier.

Up to date documentation: Whenever you push code to Git, Read the Docs will automatically build your docs so your code and documentation are always up-to-date. Get started with our tutorial.
Documentation for every version: Read the Docs can host multiple versions of your docs. Keep your 1.0 and 2.0 documentation online, pulled directly from Git. Start hosting all your versions.
Open source and user focused: Our company is bootstrapped and 100% user-focused, so our product gets better for our users instead of our investors. Read the Docs Community hosts documentation for over 100,000 large and small open source projects at no cost. Read the Docs for Business supports hundreds of organizations with product and internal documentation. Learn more about these differences on our pricing page.

First time here?

We have a few places for you to get started:

Read the Docs tutorial: Follow the Read the Docs tutorial.
Popular documentation tools: Quick start for MkDocs and Docusaurus.
Example projects: Start your journey with an example project to learn how to use Read the Docs.

Project setup and configuration

Start with the basics of setting up your project:

Configuration file overview: Learn how to configure your project with a .readthedocs.yaml file.
How to create reproducible builds: Keep your builds working by making them reproducible.

Build process

Build your documentation with ease:

Build process overview: Understand how documentation builds happen.
Pull request previews: Setup pull request builds and enjoy previews of each commit.

Hosting documentation

Learn more about our hosting features:

Versions: Give your readers multiple versions of your documentation.
Subprojects: Host multiple projects under a single domain.
Localization and Internationalization: Translate your documentation into multiple languages.
URL versioning schemes: Learn about different URL versioning schemes.
Custom domains: Brand your documentation on your own domain.

Maintaining projects

All the tools you need as your project matures:

Redirects: Redirect your old URLs to new ones.
Traffic analytics: Learn more about how users are interacting with your documentation.
Security logs: Keep track of security events in your project.

Business features

Our Business hosting has everything your business needs:

Organizations: Manage permissions across multiple teams.
Single sign-on (SSO): Stay secure with single sign-on.
Sharing private documentation: Share your private docs easily with contractors or customers.

How-to guides

Step-by-step guides for common tasks:

How to configure pull request builds: Setup pull request builds and enjoy previews of each commit.
How to use cross-references with Sphinx: Learn how to use cross-references in a Sphinx project.
All how-to guides: Browse all our how-to guides.

Reference

More detailed information about Read the Docs:

Public REST API: Integrate Read the Docs into your other workflows.
Changelog: See what’s new in Read the Docs.
About Read the Docs: Learn more about Read the Docs and our company.

Feature	Description	Supported
Search	Provides full-text search capabilities.	Not supported
Files changed	Ability to see what HTML files change in pull request previews.	Not supported

Read the Docs: documentation simplified

Read the Docs tutorial

Preparing your repository on GitHub

Creating a Read the Docs account

Importing the project to Read the Docs

Checking the first build

Configuring the project

Triggering builds from pull requests

Adding a configuration file

Using different Python versions

Making build warnings more visible

Installing Python dependencies

Enabling PDF and EPUB builds

Versioning documentation

Creating a new version of your documentation

Setting stable as the default

Modifying versions

Getting project insights

Understanding traffic analytics

Understanding search analytics

Where to go from here

Adding a documentation project

Automatically add your project

Manually add your project

What’s next

Popular documentation tools

Deploying Sphinx on Read the Docs

Quick start

Configuring Sphinx and Read the Docs Addons

Set the canonical URL

Configure Read the Docs search

Integrate the Read the Docs version menu into your site navigation

Using Markdown with Sphinx

Example repository and demo

Further reading

Deploying MkDocs on Read the Docs

Configuring Material for MkDocs on Read the Docs

Quick start

Configuring MkDocs and Read the Docs Addons

Set the canonical URL

Configuring Material for MkDocs and Read the Docs Addons

Configure Read the Docs search

Integrate the Read the Docs version menu into your site navigation

Example repository and demo

Further reading

Deploying Docusaurus on Read the Docs

Limitations

Quick start

Configuring Docusaurus and Read the Docs Addons

Configure trailing slashes

Set the canonical URL

Example repository and demo

Deploying Markdoc on Read the Docs

Example configuration

Limitations

Getting started

Example repository and demo

Further reading

Deploying mdBook on Read the Docs

Getting started

Example repository and demo

Further reading

Deploying VitePress on Read the Docs

Getting started

Using the proper base path

Example repository and demo

Further reading

Deploying Antora on Read the Docs

Getting Started

Example Repository and Demo

Further Reading

Deploying Zensical on Read the Docs

Quick start

Configuring Zensical and Read the Docs Addons

Set the canonical URL

Example repository and demo

Further reading

Deploying MyST Markdown on Read the Docs

Getting started

Example repository and demo

Adjust: `build.os`