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.