Cache doesn’t work when the project is not in the root of the repository. #476

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.

Why does my project have status “passed” but I get a 404 page?

This often happens because you don’t have an file being generated.

• (MkDocs or Sphinx with MyST)

Why do I get import errors from libraries depending on C modules?

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.
or ). 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 , you also will need to remove all
the C-dependent libraries from your in the RTD environment.

Where do I need to put my docs for RTD to find it?

Read the Docs will crawl your project looking for a . Where it finds the ,
it will run in that directory.
So as long as you only have one set of sphinx documentation in your project, it should Just Work.

You can specify an exact path to your documentation using a Read the Docs Using a configuration file.

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 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 .

How do I change the version slug of my project?

What commit of Read the Docs is in production?

We deploy readthedocs.org from the 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 .

How do I add additional software dependencies for my documentation?

For most Python dependencies,
you can 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.

Can I have access to additional features or settings?

If this is just a dependency issue,
see How do I add additional software dependencies for my documentation?.

How do I change behavior when building with Read the Docs?

When RTD builds your project, it sets the environment
variable to the string . So within your Sphinx file, you
can vary the behavior based on this. For example:

The variable is also available in the Sphinx build
environment, and will be set to when building on RTD:

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.

How do I host multiple projects on one custom domain?

For example,
Kombu is a subproject of Celery,
so you can access it on the domain:

This also works the same for custom domains:

For details on custom domains, see our documentation on .

How do I support multiple languages of documentation?

Read the Docs supports multiple languages.
See the section on Localization of documentation.

I want to use the Blue/Default Sphinx theme

We think that our theme is badass,
and better than the default for many reasons.
Some people don’t like change though 😄,
so there is a hack that will let you keep using the default theme.
If you set the variable in your ,
it should default to using the default theme.
The value of this doesn’t matter, and can be set to for default behavior.

I want to use the Read the Docs theme locally

Read the Docs automatically applies the sphinx-rtd-theme to projects that do not have a defined theme.
If you build a Sphinx project locally,
you should specify that you are using sphinx-rtd-theme.

Image scaling doesn’t work in my documentation

Image scaling in docutils depends on PIL. PIL is installed in the system that RTD runs on. However, if you are using the virtualenv building option, you will likely need to include PIL in your requirements for your project.

Can I document a Python package that is not at the root of my repository?

Please note that the path must be relative to the working directory where is launched,
rather than the directory where the requirements file is located.
Therefore, even if you want to move the requirements file to a directory,
the example path above would work.

You can customize the path to your requirements file and any other installed dependency
using a Read the Docs Using a configuration file.

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 specifies an appropriate Sphinx extension that
knows how to convert your customized docstrings. Two such extensions
are numpydoc and
napoleon. Only
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.

I need to install a package in a environment with pinned versions

To ensure proper installation of a Python package, the will automatically upgrade every dependency to its most recent version in case they aren’t:term: by the package definition.
If instead 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 file:

# path to the directory containing setup.py relative to the project root
 

In your Conda environment file ():

# path to the directory containing setup.py relative to the environment file
 

Can I use Anaconda Project and ?

Yes. With you can use the Anaconda Project configuration
file (or ) directly in place of a
Conda environment file by using as an alias for .

I.e., your file can be used as a config
in the config file if it contains:

How can I deploy Jupyter Book projects on Read the Docs?

According to its own documentation,

Jupyter Book is an open source project for building beautiful,
publication-quality books and documents from computational material.

 
     
         
         # Generate the Sphinx configuration for this Jupyter Book so it builds.