Welcome to Read The Docs¶

Write Your Docs¶

You have two options for formatting your documentation:

• In reStructuredText
• In Markdown

$ pip install sphinx sphinx-autobuild

$ cd /path/to/project
$ mkdir docs

$ cd docs
$ sphinx-quickstart

$ make html

$ pip install recommonmark

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

Import Your Docs¶

Sign up for an account on RTD, then log in. Visit your dashboard and click Import to add your project to the site. Fill in the name and description, then specify where your repository is located. This is normally the URL or path name you’d use to checkout, clone, or branch your code. Some examples:

• Git: http://github.com/ericholscher/django-kong.git
• Subversion: http://varnish-cache.org/svn/trunk
• Mercurial: https://bitbucket.org/ianb/pip
• Bazaar: lp:pasta

Add an optional homepage URL and some tags, then click “Create”.

Within a few seconds your code will automatically be fetched from your public repository, and the documentation will be built. Check out our Build Process page to learn more about how we build your docs, and to troubleshoot any issues that arise.

If you want to keep your code updated as you commit, configure your code repository to hit our Post Commit Hooks. This will rebuild your docs every time you push your code.

We support multiple versions of your code. You can read more about how to use this well on our Versions page.

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

How we envision versions working¶

In the normal case, the latest version will always point to the most up to date development code. If you develop on a branch that is different than the default for your VCS, you should set the Default Branch to that branch.

You should push a tag for each version of your project. These tags should be numbered in a way that is consistent with semantic versioning. This will map to your stable branch by default.

If you have documentation changes on a long-lived branch, you can build those too. This will allow you to see how the new docs will be built in this branch of the code. Generally you won’t have more than 1 active branch over a long period of time. The main exception here would be release branches, which are branches that are maintained over time for a specific release number.

Redirects on root URLs¶

When a user hits the root URL for your documentation, for example http://pip.readthedocs.io/, they will be redirected to the Default version. This defaults to latest, but could also point to your latest released version.

How we build documentation¶

When we import your documentation, we look at two things first: your Repository URL and the Documentation Type. We will clone your repository, and then build your documentation using the Documentation Type specified.

Understanding what’s going on¶

Understanding how Read the Docs builds your project will help you with debugging the problems you have with the site. It should also allow you to take advantage of certain things that happen during the build process.

The first step of the process is that we check out your code from the repository you have given us. If the code is already checked out, we update the copy to the branch that you have specified in your projects configuration.

Then we build the proper backend code for the type of documentation you’ve selected.

If you have the Install Project option enabled, we will run setup.py install on your package, installing it into a virtual environment. You can also define additional packages to install with the Requirements File option.

When we build your documentation, we run sphinx-build -b html . _build/html, where html would be replaced with the correct backend. We also create man pages and pdf’s automatically based on your project.

Then these files are copied across to our application servers from the build server. Once on the application servers, they are served from nginx.

An example in code:

update_imported_docs(version)
if exists('setup.py'):
    run('python setup.py install')
if project.requirements_file:
    run('pip install -r %s' % project.requirements_file)
build_docs(version=version)
copy_files(artifact_dir)

Builder Responsibility¶

Builders have a very specific job. They take the updated source code and generate the correct artifacts. The code lives in self.version.project.checkout_path(self.version.slug). The artifacts should end up in self.version.project.artifact_path(version=self.version.slug, type=self.type) Where type is the name of your builder. All files that end up in the artifact directory should be in their final form.

Packages installed in the build environment¶

The build server does have a select number of C libraries installed, because they are used across a wide array of python projects. We can’t install every C library out there, but we try and support the major ones. We currently have the following libraries installed:

• doxygen
• LaTeX (texlive-full)
• libevent (libevent-dev)
• dvipng
• graphviz
• libxslt1.1
• libxml2-dev

Writing your own builder¶

The documentation build system in RTD is made pluggable, so that you can build out your own backend. If you have a documentation format that isn’t currently supported, you can add support by contributing a backend.

The readthedocs.doc_builder API explains the higher level parts of the API that you need to implement. A basic run goes something like this:

backend = get_backend(project.documentation_type)
if force:
    backend.force(version)
backend.clean(version)
backend.build(version)
if success:
    backend.move(version)

Deleting a stale or broken build environment¶

If you’re having trouble getting your version to build, try wiping out the existing build/environment files. On your version list page /projects/[project]/versions there is a “Wipe” button that will remove all of the files associated with your documentation build, but not the documentation itself.

GitHub and Bitbucket Integration¶

We now support linking by default in the sidebar. It links to the page on your host, which should help people quickly update typos and send pull requests to contribute to project documentation.

More information can be found in the VCS Integration page.

Auto-updating¶

The Webhooks page talks about the different ways you can ping RTD to let us know your project has been updated. We have official support for GitHub, and anywhere else we have a generic post-commit hook that allows you to POST to a URL to get your documentation built.

Internationalization¶

Read the Docs itself is localized, and we support documentation translated into multiple languages. Read more on the Localization of Documentation and Internationalization pages.

Canonical URLs¶

Canonical URLs give your docs better search performance, by pointing all URLs to one version. This also helps to solve the issues around users landing on outdated versions of documentation.

More information can be found in the Canonical URLs page.

Versions¶

We can build multiple versions of your documentation. Look on the “Versions” page of your project’s admin (using the nav on the left) to find a list of available versions that we’ve inferred from the tags and branches in your source control system (according to the support matrix below). On the Versions page you can tell us which versions you’d like us to build docs for, whether each should be public, protected, or private, and what the default version should be (we’ll redirect there when someone hits your main project page, e.g., http://my-project.rtfd.org/).

Version Control Support Matrix¶

PDF Generation¶

When you build your project on RTD, we automatically build a PDF of your project’s documentation. We also build them for every version that you upload, so we can host the PDFs of your latest documentation, as well as your latest stable releases as well.

Search¶

We provide full-text search across all of the pages of documentation hosted on our site. This uses the excellent Haystack project and Solr as the search backend. We hope to be integrating this into the site more fully in the future.

Alternate Domains¶

We provide support for CNAMEs, subdomains, and a shorturl for your project as well. This is outlined in the Alternate Domains section.

Usage Questions¶

If you have questions about how to use Read the Docs, or have an issue that isn’t related to a bug, Stack Overflow is the best place to ask. Tag questions with read-the-docs so other folks can find them easily.

Good questions for Stack Overflow would be:

• “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?”

Community Support¶

Read the Docs is a community supported site, nobody is paid to handle readthedocs.org support. We are hoping to bring in enough money with our Gold program to change that, so please sign up if you are able.

All people answering your questions are doing it with their own time, so please be kind and provide as much information as possible.

Commercial Support¶

We offer commercial support for Read the Docs, commercial hosting, as well as consulting around all documentation systems. You can contact us at hello@readthedocs.com to learn more, or read more at https://readthedocs.com/services/#open-source-support.

My project isn’t building with autodoc¶

First, you should check out the Builds tab of your project. That records all of the build attempts that RTD has made to build your project. If you see ImportError messages for custom Python modules, you should enable the virtualenv feature in the Admin page of your project, which will install your project into a virtualenv, and allow you to specify a requirements.txt file for your project.

If you are still seeing errors because of C library dependencies, please see the below section about that.

How do I change my 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 change behavior for Read the Docs?¶

When RTD 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 RTD:

{% if READTHEDOCS %}
Woo
{% endif %}

I get import errors on libraries that depend on C modules¶

This happens because our build system doesn’t have the dependencies for building your project. This happens with things like libevent and mysql, and other python things that depend on C libraries. We can’t support installing random C binaries on our system, so there is another way to fix these imports.

You can mock out the imports for these modules in your conf.py with the following snippet:

import sys
from unittest.mock import MagicMock

class Mock(MagicMock):
    @classmethod
    def __getattr__(cls, name):
            return MagicMock()

MOCK_MODULES = ['pygtk', 'gtk', 'gobject', 'argparse', 'numpy', 'pandas']
sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)

Of course, replacing MOCK_MODULES with the modules that you want to mock out.

from mock import Mock as MagicMock

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

Client Error 401 when building documentation¶

If you did not install the test_data fixture during the installation instructions, you will get the following error:

slumber.exceptions.HttpClientError: Client Error 401: http://localhost:8000/api/v1/version/

This is because the API admin user does not exist, and so cannot authenticate. You can fix this by loading the test_data:

./manage.py loaddata test_data

If you’d prefer not to install the test data, you’ll need to provide a database account for the builder to use. You can provide these credentials by editing the following settings:

SLUMBER_USERNAME = 'test'
SLUMBER_PASSWORD = 'test'

Deleting a stale or broken build environment¶

If you’re having trouble getting your version to build, try wiping out the existing build/environment files. On your version list page /projects/[project]/versions there is a “Wipe” button that will remove all of the files associated with your documentation build, but not the documentation itself.

How do I host multiple projects on one CNAME?¶

We support the concept of Subprojects. If you add a subproject to a project, that documentation will also be served under the parent project’s subdomain.

For example, Kombu is a subproject of celery, so you can access it on the celery.readthedocs.io domain:

http://celery.readthedocs.io/projects/kombu/en/latest/

This also works the same for CNAMEs:

http://docs.celeryproject.org/projects/kombu/en/latest/

You can add subprojects in the Admin section for your project.

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

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

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 html_style variable in your conf.py, it should default to using the default theme. The value of this doesn’t matter, and can be set to /default.css for default behavior.

I want to use the Read the Docs theme locally¶

There is a repository for that: https://github.com/snide/sphinx_rtd_theme. Simply follow the instructions in the README.

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.

I want comments in my docs¶

RTD doesn’t have explicit support for this. That said, a tool like Disqus can be used for this purpose on RTD.

How do I support multiple languages of documentation?¶

See the section on Localization of Documentation.

Do I need to be whitelisted?¶

No. Whitelisting has been removed as a concept in Read the Docs. You should have access to all of the features already.

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.

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 Install your project inside a virtualenv using ``setup.py install`` option in the admin panel of your project. However this assumes that your setup.py is in the root of your repository.

If you want to place your package in a different directory or have multiple python packages in the same project, then create a pip requirements file. You can specify the relative path to your package inside the file. For example you want to keep your python package in the src/python directory, then create a requirements.readthedocs.txt file with the following contents:

src/python/

Please note that the path must be relative to the file. So the example path above would work if the file is in the root of your repository. If you want to put the requirements in a file called requirements/readthedocs.txt, the contents would look like:

../python/

After adding the file to your repository, go to the Advanced Settings in your project’s admin panel and add the name of the file to the Requirements file field.

Supported Settings¶

# Don't build any extra formats
formats:
    - none

# Build PDF & ePub
formats:
    - epub
    - pdf

requirements_file: requirements/docs.txt

conda:
    file: environment.yml

python:
   version: 3

python:
   setup_py_install: true

python:
   pip_install: true

from setuptools import setup

setup(
    name="my_package",
    # (...)
    install_requires=[
        'requests',
        'simplejson'],
    extras_require={
        'tests': [
            'nose',
            'pycodestyle >= 2.1.0'],
        'docs': [
            'sphinx >= 1.4',
            'sphinx_rtd_theme']}
)

python:
    extra_requirements:
        - tests
        - docs

$ pip install -e .[tests,docs]

Contributing to development¶

If you want to deep dive and help out with development on Read the Docs, then first get the project installed locally according to the Installation Guide. After that is done we suggest you have a look at tickets in our issue tracker that are labelled Good First Bug. These are meant to be a great way to get a smooth start and won’t put you in front of the most complex parts of the system.

If you are up to more challenging tasks with a bigger scope, then there are a set of tickets with a Feature Overview tag. These tickets have a general overview and description of the work required to finish. If you want to start somewhere, this would be a good place to start. That said, these aren’t necessarily the easiest tickets. They are simply things that are explained. If you still didn’t find something to work on, search for the Sprintable label. Those tickets are meant to be standalone and can be worked on ad-hoc.

When contributing code, then please follow the standard Contribution Guidelines set forth at contribution-guide.org.

Triaging tickets¶

Here is a brief explanation on how we triage incoming tickets to get a better sense of what needs to be done on what end.

Helping on translations¶

If you wish to contribute translations, please do so on Transifex.

Support Team¶

Read the Docs has thousands of users who depend on it everyday. Every day at least one of them has an issue that needs to be addressed by a site admin. This might include tasks like:

• Resetting a password
• Asking for a project name to be released
• Troubleshooting build errors

Operations Team¶

readthedocs.org is a service that millions of people depend on each month. As part of operating the site, we maintain a 24/7 on-call rotation. This means that folks have to be available and have their phone in service.

Development Team¶

Also known as the “Core Team” in other projects. These folks have the ability to commit code to the project.

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

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 them 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 a vicious downward spiral.

As developers, we understand the massive downsides of the current advertising industry. From 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.

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

Advertise with us¶

If you like our vision, let’s work together to get your ad in front of the Read the Docs audience. We have over 5 million developers reading documentation each month, and provide a valuable service to the open source community.

We only work with people who sell products that would be of interest to our audience of programmers and users of open source.

Fill out your information and we’ll get in touch.

Current sponsors¶

• Rackspace - They cover all of our hosting expenses every month. This is a pretty large sum of money, averaging around $3,000/mo, and we are really grateful to have them as a sponsor.
• Mozilla - Mozilla has given us a MOSS grant for building specific features, and have funded Eric Holscher to work on Read the Docs at $1,000/mo for 2016.
• You? (Email us at rev@readthedocs.org for more info)

Past sponsors¶

• Python Software Foundation
• Revsys
• Mozilla Web Dev
• Django Software Foundation
• Lab305
• Twilio

Sponsorship Information¶

As part of increasing sustainability, Read the Docs is testing out promoting sponsors on documentation pages. We have more information about this in our blog post about this effort.

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://readthedocs.org for Open Source projects
• Bug fixes in the code base, as it applies to running it on https://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.

GitHub¶

If your project is hosted on GitHub, you can easily add a hook that will rebuild your docs whenever you push updates:

• Go to the “Settings” page for your project
• Click “Webhooks & Services”
• In the “Services” section, click “Add service”
• In the list of available services, click “ReadTheDocs”
• Check “Active”
• Click “Add service”

If you ever need to manually set the webhook on GitHub, you can point it at https://readthedocs.org/github.

Bitbucket¶

If your project is hosted on Bitbucket, you can easily add a hook that will rebuild your docs whenever you push updates:

• Go to the “admin” page for your project
• Click “Services”
• In the available service hooks, select “Read the Docs”
• Click “Add service”

If you ever need to manually set the webhook on Bitbucket, you can point it at https://readthedocs.org/bitbucket.

Others¶

Your ReadTheDocs project detail page has your post-commit hook on it; it will look something along the lines of http://readthedocs.org/build/<project_name>. Regardless of which revision control system you use, you can just hit this URL to kick off a rebuild.

You could make this part of a hook using Git, Subversion, Mercurial, or Bazaar, perhaps through a simple script that accesses the build URL using wget or curl.

Status Badges¶

They will display in green for passing, red for failing, and yellow for unknown states.

Here are a few examples:

You can see it in action in the Read the Docs README. They will link back to your project’s documentation page on Read the Docs.

Project Pages¶

You will now see badges embedded in your project page. The default badge will be pointed at the default version you have specified for your project. The badge URLs look like this:

https://readthedocs.org/projects/pip/badge/?version=latest

You can replace the version argument with any version that you want to show a badge for. If you click on the badge icon, you will be given snippets for RST, Markdown, and HTML; to make embedding it easier.

If you leave the version argument off, it will default to your latest version. This is probably best to include in your README, since it will stay up to date with your Read the Docs project:

https://readthedocs.org/projects/pip/badge/

Style¶

If you pass the style GET argument, we will pass it along to shields.io as is. This will allow you to have custom style badges.

Subdomain Support¶

Every project has a subdomain that is available to serve its documentation. If you go to <slug>.readthedocs.io, it should show you the latest version of documentation. A good example is http://pip.readthedocs.io

CNAME Support¶

If you have your own domain, you can still host with us. This requires two steps:

• Add a CNAME record in your DNS that point to our servers readthedocs.io
• Add a Domain object in the Project Admin > Domains page for your project.

Using pip as an example, http://www.pip-installer.org resolves, but is hosted on our infrastructure.

As an example, fabric’s dig record looks like this:

-> dig docs.fabfile.org
...
;; ANSWER SECTION:
docs.fabfile.org.   7200    IN  CNAME   readthedocs.io.

CNAME SSL¶

We don’t support SSL for CNAMEs on our side, but you can enable support if you have your own server. SSL requires having a secret key, and if we hosted the key for you, it would no longer be secret.

To enable SSL:

• Have a server listening on 443 that you control
• Add a domain that you wish to point at Read the Docs
• Enable proxying to us, with a custom X-RTD-SLUG header

An example nginx configuration for pip would look like:

 server {
     server_name docs.pip-installer.org;
     location / {
         proxy_pass https://pip.readthedocs.io:443;
         proxy_set_header Host $http_host;
         proxy_set_header X-Forwarded-Proto https;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Scheme $scheme;
         proxy_set_header X-RTD-SLUG pip;
         proxy_connect_timeout 10s;
         proxy_read_timeout 20s;
     }
 }

rtfd.org¶

You can also use rtfd.io and rtfd.org for short URLs for Read the Docs. For example, http://pip.rtfd.io redirects to its documentation page. Any use of rtfd.io or rtfd.org will simply be redirected to readthedocs.io.

Single project in another language¶

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

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

Project with multiple translations¶

This situation is a bit more complicated. To support this, you will have one parent project and a number of projects marked as translations of that parent. Let’s use phpmyadmin as an example.

The main phpmyadmin project is the parent for all translations. Then you must create a project for each translation, for example phpmyadmin-spanish. You will set the Language for phpmyadmin-spanish to Spanish. In the parent projects Translations page, you will say that phpmyadmin-spanish is a translation for your project.

This has the results of serving:

• phpmyadmin at http://phpmyadmin.readthedocs.io/en/latest/
• phpmyadmin-spanish at http://phpmyadmin.readthedocs.io/es/latest/

It also gets included in the Read the Docs flyout:

GitHub¶

If you want to integrate GitHub editing into your own theme, the following variables are available in your custom templates:

• github_user - GitHub username
• github_repo - GitHub repo name
• github_version - GitHub blob
• conf_py_path - Path in the checkout to the docs root
• pagename - Sphinx variable representing the name of the page you’re on.
• display_github

It 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 editing into your own theme, the following variables are available in your custom templates:

• bitbucket_user - Bitbucket username
• bitbucket_repo - Bitbucket repo name
• bitbucket_version - BitBucket version
• conf_py_path - Path in the checkout to the docs root
• pagename - Sphinx variable representing the name of the page you’re on.
• display_bitbucket

It 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 %}

Activating Conda¶

Conda Support is the first feature enabled with Read the Docs YAML Config. You can enable it by creating a readthedocs.yml file in the root of your repository with the contents:

conda:
    file: environment.yml

This Conda environment will also have Sphinx and other build time dependencies installed. It will use the same order of operations that we support currently:

• Environment Creation (conda create)
• Dependency Installation (Sphinx)
• User Package Installation (conda env update)

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.

Example¶

Fabric hosts their docs on Read the Docs. They mostly use their own domain for them http://docs.fabfile.org. This means that Google will index both http://fabric-docs.readthedocs.io and http://docs.fabfile.org for their documentation.

Fabric will want to set http://docs.fabfile.org as their canonical URL. This means that when Google indexes http://fabric-docs.readthedocs.io, it will know that it should really point at http://docs.fabfile.org.

Enabling¶

You can set the canonical URL for your project in the Project Admin page. Check your Domains tab for the domains that we know about.

Implementation¶

If you look at the source code for documentation built after you set your canonical URL, you should see a bit of HTML like this:

<link rel="canonical" href="http://pip.readthedocs.io/en/latest/installing.html">

Links¶

This is a good explanation of the usage of canonical URLs in search engines:

http://www.mattcutts.com/blog/seo-advice-url-canonicalization/

This is a good explanation for why canonical pages are good for SEO:

http://moz.com/blog/canonical-url-tag-the-most-important-advancement-in-seo-practices-since-sitemaps

Enabling¶

You can toggle the “Single Version” option on or off for your project in the Project Admin page. Check your dashboard for a list of your projects.

Effects¶

Links generated on Read the Docs will now point to the proper URL. For example, if pip was set as a “Single Version” project, then links to its documentation would point to http://pip.readthedocs.io/ rather than the default http://pip.readthedocs.io/en/latest/.

Documentation at /<language>/<default_version>/ will still be served for backwards compatibility reasons. However, our usage of Canonical URLs should stop these from being indexed by Google.

Understanding the Privacy Levels¶

Project Objects¶

Version Objects¶

Prefix Redirects¶

The most useful and requested feature of redirects was when migrating to Read the Docs from an old host. You would have your docs served at a previous URL, but that URL would break once you moved them. Read the Docs includes a language and version slug in your documentation, but not all documentation is hosted this way.

Say that you previously had your docs hosted at http://docs.example.com/dev/, you move docs.example.com to point at Read the Docs. So users will have a bookmark saved to a page at http://docs.example.com/dev/install.html.

You can now set a Prefix Redirect that will redirect all 404’s with a prefix to a new place. The example configuration would be:

Type: Prefix Redirect
From URL: /dev/

Your users query would now redirect in the following manner:

docs.example.com/dev/install.html ->
docs.example.com/en/latest/install.html

Where en and latest are the default language and version values for your project.

Page Redirects¶

A more specific case is when you move a page around in your docs. The old page will start 404’ing, and your users will be confused. Page Redirects let you redirect a specific page.

Say you move the example.html page into a subdirectory of examples: examples/intro.html. You would set the following configuration:

Type: Page Redirect
From URL: /example.html
To URL: /examples/intro.html

Note that the / at the start doesn’t count the /en/latest, but just the user-controlled section of the URL.

Exact Redirects¶

If you’re redirecting from an old host AND you aren’t maintaining old paths for your documents, a Prefix Redirect won’t suffice and you’ll need to create Exact Redirects to redirect from a specific URL, to a specific page.

Say you’re moving docs.example.com to Read the Docs and want to redirect traffic from an old page at http://docs.example.com/dev/install.html to a new URL of http://docs.example.com/en/latest/installing-your-site.html.

The example configuration would be:

Type: Exact Redirect
From URL: /dev/install.html
To URL:   /en/latest/installing-your-site.html

Your users query would now redirect in the following manner:

docs.example.com/dev/install.html ->
docs.example.com/en/latest/installing-your-site.html

Note that you should insert the desired language for “en” and version for “latest” to achieve the desired redirect.

Sphinx Redirects¶

We also support redirects for changing the type of documentation Sphinx is building. If you switch between HTMLDir and HTML, your URL’s will change. A page at /en/latest/install.html will be served at /en/latest/install/, or vice versa. The built in redirects for this will handle redirecting users appropriately.

Implementation¶

Since we serve documentation in a highly available way, we do not run any logic when we’re serving documentation. This means that redirects will only happen in the case of a 404 File Not Found.

In the future we might implement redirect logic in Javascript, but this first version is only implemented in the 404 handlers.

Feature Requests

Root URL¶

A link to the root of your documentation will redirect to the default version, as set in your project settings. For example:

pip.readthedocs.io -> pip.readthedocs.io/en/latest/
www.pip-installer.org -> www.pip-installer.org/en/latest

This only works for the root url, not for internal pages. It’s designed to redirect people from http://pip.readthedocs.io/ to the default version of your documentation, since serving up a 404 here would be a pretty terrible user experience. (If your “develop” branch was designated as your default version, then it would redirect to http://pip.readthedocs.io/en/develop.) But, it’s not a universal redirecting solution. So, for example, a link to an internal page like http://pip.readthedocs.io/usage.html doesn’t redirect to http://pip.readthedocs.io/en/latest/usage.html.

The reasoning behind this is that RTD organizes the URLs for docs so that multiple translations and multiple versions of your docs can be organized logically and consistently for all projects that RTD hosts. For the way that RTD views docs, http://pip.readthedocs.io/en/latest/ is the root directory for your default documentation in English, not http://pip.readthedocs.io/. Just like http://pip.readthedocs.io/en/develop/ is the root for your development documentation in English.

Among all the multiple versions of docs, you can choose which is the “default” version for RTD to display, which usually corresponds to the git branch of the most recent official release from your project.

Supported Top-Level Redirects¶

The main challenge of URL routing in Read the Docs is handling redirects correctly. Both in the interest of redirecting older URLs that are now obsolete, and in the interest of handling “logical-looking” URLs (leaving out the lang_slug or version_slug shouldn’t result in a 404), the following redirects are supported:

/          -> /en/latest/
/en/       -> /en/latest/
/latest/   -> /en/latest/

The language redirect will work for any of the defined LANGUAGE_CODES we support. The version redirect will work for supported versions.

Redirecting to a Page¶

You can link to a specific page and have it redirect to your default version. This is done with the /page/ URL. For example:

pip.readthedocs.io/page/quickstart.html -> pip.readthedocs.io/en/latest/quickstart.html
www.pip-installer.org/page/quickstart.html -> www.pip-installer.org/en/latest/quickstart.html

This allows you to create links that are always up to date.

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.

What’s available¶

After registering with the site (or creating yourself a superuser account), you will be able to log in and view the dashboard.

From the dashboard you can import your existing docs provided that they are in a git or mercurial repo.

July 23, 2015¶

• Django 1.8 Support Merged

python manage.py migrate contenttypes
python manage.py migrate projects 0002 --fake
python manage.py migrate --fake-initial

python manage.py syncdb
python manage.py migrate

python manage.py migrate contenttypes
python manage.py migrate projects 0002 --fake
python manage.py migrate --fake-initial

Continuous Integration¶

The RTD test suite is exercised by Travis CI on every push to our repo at GitHub. You can check out the current build status: https://travis-ci.org/rtfd/readthedocs.org

Diagram¶

                               +-----------+
                               | Rackspace |
                         +-----| Load Bal  |------+
                         |     +-----------+      |
                         |                        |
                    +---------+              +---------+
+-------------+     |         |              |         |    +--------------+
|             |-----| Nginx   |              | Nginx   |----|              |
|  File       |     +---------+              +---------+    |  File        |
|  System     |          |                        |         |  System      |
+-------------+     +---------+  +--------+  +---------+    +--------------+
       |  |         |Gunicorn |  |        |  |Gunicorn |        |   |
       |  +---------|(Django) |--|Postgres|--|(Django) |--------+   |
       |            +---------+  +--------+  +---------+            |
       |                 |                        |                 |
       |                 |                        |                 |
       |                 -----------API------------                 |
       |                             |                              |
       |                             |                              |
       |                     +------------------+                   |
       |                     |                  |                   |
       +---------------------|  Build Server    |-------------------+
                             |                  |
                             +------------------+

Front End Development¶

npm install

bower install

gulp dev

gulp build

gulp vendor

Setup¶

Build environments use Docker to handle container virtualization. To perform any development on the Docker build system, you will need to set up Docker on your host system. Setup of Docker will vary by system, and so is out of the scope of this documentation.

Once you have Docker set up, you will need to create the base image used for container creation. The base image is found in our container images repo. It is the basic container image supported by our community site.

To get started, create the image using the docker command line tool. You can name the image whatever you like here, rtfd-build is the default name, but can be configured in your settings – see Configuration:

docker build -t rtfd-build base/

When this process has completed, you should have a working image that Read the Docs can use to start containers.

Configuration¶

There are several settings used to configure usage of virtual machines:

DOCKER_ENABLED

True/False value used to enable the Docker build environment. Default: False

DOCKER_LIMITS

A dictionary of limits to virtual machines. These limits include:

time

An integer representing the total allowed time limit (in seconds) of build processes. This time limit affects the parent process to the virtual machine and will force a virtual machine to die if a build is still running after the allotted time expires.

memory

The maximum memory allocated to the virtual machine. If this limit is hit, build processes will be automatically killed. Examples: ‘200m’ for 200MB of total memory, or ‘2g’ for 2GB of total memory.

DOCKER_IMAGE

Tag of a Docker image to use as a base image.

DOCKER_SOCKET

URI of the socket to connect to the Docker daemon. Examples include: unix:///var/run/docker.sock and tcp://127.0.0.1:2375

DOCKER_VERSION

Version of the API to use for the Docker API client.

Nginx¶

We handle a couple of different types of requests in nginx:

• Requests to a readthedocs.org subdomain
• Requests to a CNAME

Subdomains¶

For subdomains this is a simple lookup. This doesn’t require symlinks, but it shows the basic logic that we need to replicate.

When a user navigates to http://pip.readthedocs.org/en/latest/, we know that they want the pip documentation. So we simply serve them the documentation:

location ~ ^/en/(.+)/(.*) {
    alias /home/docs/checkouts/readthedocs.org/user_builds/$domain/rtd-builds/$1/$2;
    error_page 404 = @fallback;
    error_page 500 = @fallback;
}

location @fallback {
    proxy_pass http://127.0.0.1:8888;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    add_header X-Deity Asgard;
}

CNAMEs¶

CNAMEs add a bit of difficulty, because at the nginx layer we don’t know what documentation to serve. When someone requests http://docs.fabfile.org/en/latest/, we can’t look at the URL to know to serve the fabric docs.

This is where symlinks come in. When someone requests http://docs.fabfile.org/en/latest/ the first time, it hits the Python layer. In that Python layer we record that docs.fabfile.org points at fabric. When we build the fabric docs, we create a symlink for all domains that have pointed at fabric before.

So, when we get a request for docs.fabfile.org in the future, we will be able to serve it directly from nginx. In this example, $host would be docs.fabfile.org:

location ~ ^/en/(?P<doc_version>.+)/(?P<path>.*) {
    alias /home/docs/checkouts/readthedocs.org/cnames/$host/$doc_version/$path;
    error_page 404 = @fallback;
    error_page 500 = @fallback;
}

Notice that nowhere in the above path is the project’s slug mentioned. It is simply there in the symlink in the cnames directory, and the docs are served from there.

SLUMBER_USERNAME¶

Default: test

The username to use when connecting to the Read the Docs API. Used for hitting the API while building the docs.

SLUMBER_PASSWORD¶

Default: test

The password to use when connecting to the Read the Docs API. Used for hitting the API while building the docs.

USE_SUBDOMAIN¶

Default: False

Whether to use subdomains in URLs on the site, or the Django-served content. When used in production, this should be True, as Nginx will serve this content. During development and other possible deployments, this might be False.

PRODUCTION_DOMAIN¶

Default: readthedocs.org

This is the domain that gets linked to throughout the site when used in production. It depends on USE_SUBDOMAIN, otherwise it isn’t used.

MULTIPLE_APP_SERVERS¶

Default: undefined

This is a list of application servers that built documentation is copied to. This allows you to run an independent build server, and then have it rsync your built documentation across multiple front end documentation/app servers.

DEFAULT_PRIVACY_LEVEL¶

Default: public

What privacy projects default to having. Generally set to public. Also acts as a proxy setting for blocking certain historically insecure options, like serving generated artifacts directly from the media server.

INDEX_ONLY_LATEST¶

Default: False

In search, only index the latest version of a Project.

DOCUMENT_PYQUERY_PATH¶

Default: div.document

The Pyquery path to an HTML element that is the root of your document. This is used for making sure we are only searching the main content of a document.

USE_PIP_INSTALL¶

Default: False

Whether to use pip install . or python setup.py install when installing packages into the Virtualenv. Default is to use python setup.py install.

PUBLIC_DOMAIN¶

Default: settings.PRODUCTION_DOMAIN

A special domain for serving public documentation. If set, public docs will be linked here instead of the PRODUCTION_DOMAIN.

ALLOW_ADMIN¶

Default: True

Whether to include django.contrib.admin in the URL’s.

Making Strings Localizable¶

Making strings in templates localizable is exceptionally easy. Making strings in Python localizable is a little more complicated. The short answer, though, is to just wrap the string in _().

_('Welcome, ') + username

_('Welcome, {name}').format(name=username)

DEFAULT_THEME_CHOICES = (
    # Translators: This is a name of a Sphinx theme.
    (THEME_DEFAULT, _('Default')),
    # Translators: This is a name of a Sphinx theme.
    (THEME_SPHINX, _('Sphinx Docs')),
    # Translators: This is a name of a Sphinx theme.
    (THEME_TRADITIONAL, _('Traditional')),
    # Translators: This is a name of a Sphinx theme.
    (THEME_NATURE, _('Nature')),
    # Translators: This is a name of a Sphinx theme.
    (THEME_HAIKU, _('Haiku')),
)

from django.utils.translation import pgettext

month = pgettext("text for the search button on the form", "Search")

ngettext('singular sentence', 'plural sentence', count)

ngettext('Found {count} result.',
         'Found {count} results',
         len(results)).format(count=len(results))

Strings in Templates¶

When putting new text into a template, all you need to do is wrap it in a {% trans %} template tag:

<h1>{% trans "Heading" %}</h1>

Context can be added, too:

<h1>{% trans "Heading" context "section name" %}</h1>

Comments for translators need to precede the internationalized text and must start with the Translators: keyword.:

{# Translators: This heading is displayed in the user's profile page #}
<h1>{% trans "Heading" %}</h1>

To interpolate, you need to use the alternative and more verbose {% blocktrans %} template tag — it’s actually a block:

{% blocktrans %}Welcome, {{ name }}!{% endblocktrans %}

Note that the {{ name }} variable needs to exist in the template context.

In some situations, it’s desirable to evaluate template expressions such as filters or accessing object attributes. You can’t do that within the {% blocktrans %} block, so you need to bind the expression to a local variable first:

{% blocktrans with revision.created_date|timesince as timesince %}
{{ revision }} {{ timesince }} ago
{% endblocktrans %}

{% blocktrans with project.name as name %}Delete {{ name }}?{% endblocktrans %}

{% blocktrans %} also provides pluralization. For that you need to bind a counter with the name count and provide a plural translation after the {% plural %} tag:

{% blocktrans with amount=article.price count years=i.length %}
That will cost $ {{ amount }} per year.
{% plural %}
That will cost $ {{ amount }} per {{ years }} years.
{% endblocktrans %}

Strings in Python¶

Strings in Python are more complex for two reasons:

1. We need to make sure we’re always using Unicode strings and the Unicode-friendly versions of the functions.
2. If you use the ugettext() function in the wrong place, the string may end up in the wrong locale!

Here’s how you might localize a string in a view:

from django.utils.translation import ugettext as _

def my_view(request):
    if request.user.is_superuser:
        msg = _(u'Oh hi, staff!')
    else:
        msg = _(u'You are not staff!')

Interpolation is done through normal Python string formatting:

msg = _(u'Oh, hi, {user}').format(user=request.user.username)

Context information can be supplied by using the pgettext() function:

msg = pgettext('the context', 'Search')

Translator comments are normal one-line Python comments:

# Translators: A message to users.
msg = _(u'Oh, hi there!')

If you need to use plurals, import the ungettext() function:

from django.utils.translation import ungettext

n = len(results)
msg = ungettext('Found {0} result', 'Found {0} results', n).format(n)

from django.utils.translation import ugettext_lazy as _

class UserProfileForm(forms.ModelForm):
    first_name = CharField(label=_('First name'), required=False)
    last_name = CharField(label=_('Last name'), required=False)

Updating Localization Files¶

To update the translation source files (eg if you changed or added translatable strings in the templates or Python code) you should run python manage.py makemessages -l <language> in the project’s root directory (substitute <language> with a valid language code).

The updated files can now be localized in a PO editor or crowd-sourced online translation tool.

Compiling to MO¶

Gettext doesn’t parse any text files, it reads a binary format for faster performance. To compile the latest PO files in the repository, Django provides the compilemessages management command. For example, to compile all the available localizations, just run:

$ python manage.py compilemessages -a

You will need to do this every time you want to push updated translations to the live site.

Also, note that it’s not a good idea to track MO files in version control, since they would need to be updated at the same pace PO files are updated, so it’s silly and not worth it. They are ignored by .gitignore, but please make sure you don’t forcibly add them to the repository.

Transifex Integration¶

To push updated translation source files to Transifex, run tx push -s (for English) or tx push -t <language> (for non-English).

To pull changes from Transifex, run tx pull -a. Note that Transifex does not compile the translation files, so you have to do this after the pull (see the Compiling to MO section).

For more information about the tx command, read the Transifex client’s help pages.

Style Catalog¶

Once you have RTD running locally, you can open http://localhost:8000/style-catalog/ for a quick overview of the currently available styles.

This way you can quickly get started writing HTML – or if you’re modifying existing styles you can get a quick idea of how things will change site-wide.

Typekit Fonts¶

RTD uses FF Meta via TypeKit to render most display and body text.

To make this work locally, you can register a free TypeKit account and create a site profile for localhost:8000 that includes the linked font.

Readthedocs.org Changes¶

Styles for the primary RTD site are located in media/css directory.

These styles only affect the primary site – not any of the generated documentation using the default RTD style.

Sphinx Template Changes¶

Styles for generated documentation are located in readthedocs/templates/sphinx/_static/rtd.css

Of note, projects will retain the version of that file they were last built with – so if you’re editing that file and not seeing any changes to your local built documentation, you need to rebuild your example project.

Contributing¶

Contributions should follow the Contributing to Read the Docs guidelines where applicable – ideally you’ll create a pull request against the Read the Docs GitHub project from your forked repo and include a brief description of what you added / removed / changed, as well as an attached image (you can just take a screenshot and drop it into the PR creation form) of the effects of your changes.

There’s not a hard browser range, but your design changes should work reasonably well across all major browsers, IE8+ – that’s not to say it needs to be pixel-perfect in older browsers! Just avoid making changes that render older browsers utterly unusable (or provide a sane fallback).

Contributing to the theme¶

If you have issues or feedback, please open an issue on the theme’s GitHub repository which itself is a submodule within the larger RTD codebase. That means any changes to the theme or the Read the Docs badge styling should be made there. The code is separate so that it can be used independent of Read the Docs as a regular Sphinx theme.

How the Table of Contents builds¶

Currently the left menu will build based upon any toctree(s) defined in your index.rst file. It outputs 2 levels of depth, which should give your visitors a high level of access to your docs. If no toctrees are set in your index.rst file the theme reverts to sphinx’s usual local toctree which is based upon the heading set on your current page.

It’s important to note that if you don’t follow the same styling for your rST headers across your documents, the toctree will misbuild, and the resulting menu might not show the correct depth when it renders.

Other style notes¶

• As a responsive style, you should not set a height and width to your images.
• Wide tables will add a horizontal scroll bar to maintain the responsive layout.

Elastic Search Setup¶

You need to install the ICU plugin to make ES work:

# Use the correct path to the plugin executable that ships with ES.
/usr/share/elasticsearch/bin/plugin -install elasticsearch/elasticsearch-analysis-icu/2.3.0

from search.indexes import Index, PageIndex, ProjectIndex, SectionIndex

# Create the index.
index = Index()
index_name = index.timestamped_index()
index.create_index(index_name)
index.update_aliases(index_name)
# Update mapping
proj = ProjectIndex()
proj.put_mapping()
page = PageIndex()
page.put_mapping()
sec = SectionIndex()
sec.put_mapping()