Read the Docs Blog - Posts from Cuenca, Ecuador

Deprecation of the git:// protocol on GitHub

2022-03-01T00:00:00Z

Last year, GitHub announced the deprecation of the unsecured Git protocol due to security reasons. This change will be made permanent on March 15, 2022.

At Read the Docs we found around 900 projects using a Git protocol URL (git://github.com/user/project) to clone their projects. To save time for our users, we have migrated those to use the HTTPS cloning URL instead (https://github.com/user/project).

But there are other places where projects may be using a Git protocol URL, like in submodules or dependencies. You’ll need to migrate those to use a supported protocol in order for your builds to keep working after March 15, 2022. In most cases, this means changing URLs that start with git:// to start with https:// instead. If you have doubts, please check the documentation of the tools you are using, for example:

Note that this applies only to repositories hosted on GitHub, repositories using providers that support the Git protocol won’t be affected.

Read the Docs tries to keep users informed about deprecations and breaking changes that may impact projects. To receive future updates like this, subscribe to our newsletter.

Automation Rules

2020-05-04T00:00:00Z

A time ago we introduced a new feature to help users to automate some tasks on Read the Docs. Automation rules.

If you manage a project with several versions, you may have noticed that Read the Docs doesn’t always activate your new versions [1]. If you require to do any action over a new version, you’ll need to log in your Read the Docs account and manually do so.

With automation rules, you can choose what do to after a new version is created. To add a rule, you only need to choose a pattern and an action. After that, every new tag or branch that matches the pattern will trigger the action.

Currently, we only have two actions available:

Activate version
Set version as default

For the pattern, you can select:

All versions
The ones that match SemVer
Or you can write your own using a regular expression

With automation rules you can do things like:

Activate new tags only
Activate only branches that start with v
Activate tags and branches that belong to the 1.x release
Set as default tags that have the -stable or -release suffix
Activate all tags except those containing the --nightly suffix

Find more information and examples in our documentation.

What other tasks you would like to automate? Let us know on a GitHub issue!

[1]	We activate and build new versions automatically only if you follow PEP 440, and the new version is greater than the current stable version.

New Configuration File

2019-02-20T00:00:00Z

We are happy to announce the new version of the Read the Docs configuration file (v2).

version: 2
python:
  version: 3.7
  install:
    - requirements: docs/requirements.txt
sphinx:
  configuration: docs/conf.py
formats: all

If you are a recurrent Read the Docs user, chances are that you’ve configured your projects using a .readthedocs.yml file.

Using the web interface is quick, but the main advantages of using a configuration file over the web interface are:

Some settings are only available using a configuration file. We are moving away from using the web interface.
The settings are per version rather than per project. This would allow different versions of docs to be built with different versions of Python or different requirements.
The settings live in your VCS.
Reproducible build environments over time.

What did we change in the new version?

All the configurations from the web interface. In the past not all options from the web interface were available in the configuration file, now they are! We also reorganized and renamed some options to make them more clear.

New defaults, we don’t merge the values from the web interface, because this was confusing our users. This also allows us to change defaults without breaking existing projects.

More flexible installations, users can install their projects in a more flexible way, like multiple requirements and packages from different locations.

Strict validation for invalid options in the configuration file, to avoid typos and provide more feedback on invalid configurations.

New features

MkDocs support (previously it was only supported from the web interface).

version: 2
mkdocs:
  configuration: mkdocs.yml
  fail_on_warning: true

More control over Sphinx.

version: 2
sphinx:
   builder: html
   configuration: docs/source/conf.py
   fail_on_warning: true

Control over submodules, we don’t always need them all to build our docs.

version: 2
submodules:
  include:
    - third-party/dependency
  recursive: true

Support for multiple packages/requirements installations.

version: 2
python:
  version: 3.7
  install:
    - requirements: docs/requirements.txt
    - requirements: requirements.txt
    - method: pip
      path: package

Future improvements

We are already planning new features to support more projects and use cases.

Pipfile support, this is one of our more requested features, and we are going to ship it soon. Keep an eye in #3181.

Show the configuration used in each build. We want to make more explicit to the users how we are building their docs.

Redirects per version of your docs. Currently users can define global redirects only from the web interface, this is hard to maintain and review. One use case is when you change your docs structure between versions. Keep track of this upcoming feature in #4221.

Start using it

The full docs about the new version are available here.

If you are using the v1, you can update to v2 following our migration docs.

If you have a problem using the configuration file, feel free to file an issue.

Summer internship

This project was part of my summer internship in Read the Docs, it was held at the same time as the Google Summer of Code (GSoC) project.

Thanks to the core team (Anthony, David, Eric, and Manuel) for helping me in the process. Thanks to all contributors, sponsors, donors and users of Read the Docs to make the project sustainable.