Welcome to Read The Docs¶

Write Your Docs¶

Install Sphinx, and create a directory inside your project to hold your docs:

$ cd /path/to/project
$ mkdir docs

Run sphinx-quickstart in there:

$ cd docs
$ sphinx-quickstart

This will walk you through creating the basic configuration; in most cases, you can just accept the defaults. When it’s done, you’ll have an index.rst, a conf.py and some other files. Add these to revision control.

Now, edit your index.rst and add some information about your project. Include as much detail as you like (refer to the reStructuredText syntax or this template if you need help). Build them to see how they look:

$ make html

Edit your files and rebuild until you like what you see, then commit your changes and push to your public repository. Once you have Sphinx documentation in a public repository, you can start using Read the Docs.

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

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

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 Use Virtualenv 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(project, version)
if project.use_virtualenv:
    run('python setup.py install')
    if project.requirements_file:
        run('pip install -r %s' % project.requirements_file)
build_docs(version=version, pdf=pdf, man=man, epub=epub, dash=dash)
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:

• 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 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¶

RTD doesn’t expose this in the UI, but it is possible to remove the build directory of your project. If you want to remove a build environment for your project, hit http://readthedocs.org/wipe/<project_slug>/<version_slug>/. You must be logged in to do this.

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.

Getting Help¶

The easiest way to get help with the project is to join the #readthedocs channel on Freenode. We hang out there and you can get real-time help with your projects. The other good way is to open an issue on Github.

The mailing list at https://groups.google.com/forum/#!forum/read-the-docs is also available for support.

Backwards Incompatible Changes¶

Backwards Incompatible Changes will be emailed to the mailing list. They will be prefixed with “Backwards Incompatible Changes”. We are thinking about having some kind of Backwards Incompatible Changes policy, much like the 1.0 of a code base, once we define the redirects and interfaces that we wish to expose permanently.

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 behavior for Read the Docs?¶

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

import os
on_rtd = os.environ.get('READTHEDOCS', None) == '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 Mock()

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

Can I make search engines only see one version of my docs?¶

You can do this for Google at least with a canonical link tag. It should look like:

<link rel="canonical" href="http://ericholscher.com/
{%- for word in pagename.split('/') -%}
    {%- if word != 'index' -%}
        {%- if word != '' -%}
            {{ word }}/
        {%- endif -%}
    {%- endif -%}
{%- endfor -%}
{% if builder == "dirhtml" %}/{% else %}.html{% endif %}
">

Deleting a stale or broken build environment¶

RTD doesn’t expose this in the UI, but it is possible to remove the build directory of your project. If you want to remove a build environment for your project, hit http://readthedocs.org/wipe/<project_slug>/<version_slug>/. You must be logged in to do this.

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.org domain:

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

This also works the same for CNAME’s:

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.

Solr (Search) Setup¶

Apache Solr is used to index and search documents. This is an optional requirement, and only necessary if you want to develop or use search.

Additional python requirements necessary to use Solr:

pip install pysolr
pip install pyquery

Fetch and unpack Solr:

curl -O http://archive.apache.org/dist/lucene/solr/3.5.0/apache-solr-3.5.0.tgz
tar xvzf apache-solr-3.5.0.tgz && SOLR_PATH=`pwd`/apache-solr-3.5.0/example

Generate the schema.xml file:

./manage.py build_solr_schema > $SOLR_PATH/solr/conf/schema.xml

Start the server:

cd $SOLR_PATH && java -jar start.jar

Index the data:

./manage.py build_files # creates database objects referencing project files
./manage.py update_index

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.

Installation with Vagrant¶

It is also possible to run RTD using Vagrant, using Vagrant v1.1+ and the Salt plugin for Vagrant, by running the following commands:

vagrant plugin install vagrant-salt
vagrant up

The Vagrant virtual machine will take a while to create and provision, and will leave a virtual machine running an instance of RTD with the following settings:

The repository is shared with the host file system, so edits can be made outside the virtual environment.

Tickets¶

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.

Translations¶

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

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¶

                               +-----------+
                               |           |
                         +-----|  Nginx    |------+
                         |     +-----------+      |
                         |                        |
                    +---------+              +---------+
+-------------+     |         |              |         |    +--------------+
|             |-----| Nginx   |              | Nginx   |----|              |
|  File       |     +---------+              +---------+    |  File        |
|  System     |          |                        |         |  System      |
+-------------+     +---------+  +--------+  +---------+    +--------------+
       |  |         |         |  |        |  |         |        |   |
       |  +---------|Gunicorn |--|Postgres|--|Gunicorn |--------+   |
       |            +---------+  +--------+  +---------+            |
       |                             |                              |
       |                             |                              |
       |                     +------------------+                   |
       |                     |                  |                   |
       +---------------------|  Build Server    |-------------------+
                             |                  |
                             +------------------+

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

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.

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

A basic API client using slumber¶

You can use Slumber to build basic API wrappers in python. Here is a simple example of using slumber to interact with the RTD API:

import slumber
import json

show_objs = True
api = slumber.API(base_url='http://readthedocs.org/api/v1/')

val = api.project.get(slug='pip')
#val = api.project('pip').get()

#val = api.build(49252).get()
#val = api.build.get(project__slug='read-the-docs')

#val = api.user.get(username='eric')

#val = api.version('pip').get()
#val = api.version('pip').get(slug='1.0.1')

#val = api.version('pip').highest.get()
#val = api.version('pip').highest('0.8').get()

if show_objs:
    for obj in val['objects']:
        print json.dumps(obj, indent=4)
else:
    print json.dumps(val, indent=4)

Example of adding a user to a project¶

import slumber

USERNAME = 'eric'
PASSWORD = 'test'

user_to_add = 'coleifer'
project_slug = 'read-the-docs'

api = slumber.API(base_url='http://readthedocs.org/api/v1/', authentication={'name': USERNAME, 'password': PASSWORD})

project = api.project.get(slug=project_slug)
user = api.user.get(username=user_to_add)
project_objects = project['objects'][0]
user_objects = user['objects'][0]

data = {'users': project_objects['users'][:]}
data['users'].append(user_objects['resource_uri'])

print "Adding %s to %s" % (user_objects['username'], project_objects['slug'])
api.project(project_objects['id']).put(data)

project2 = api.project.get(slug=project_slug)
project2_objects = project2['objects'][0]
print "Before users: %s" % project_objects['users']
print "After users: %s" % project2_objects['users']

API Endpoints¶

Feel free to use cURL and python to look at formatted json examples. You can also look at them in your browser, if it handles returned json.

curl http://readthedocs.org/api/v1/project/pip/?format=json | python -m json.tool

Root¶

GET /api/v1/¶

Retrieve a list of resources.¶

{
    "build": {
        "list_endpoint": "/api/v1/build/",
        "schema": "/api/v1/build/schema/"
    },
    "file": {
        "list_endpoint": "/api/v1/file/",
        "schema": "/api/v1/file/schema/"
    },
    "project": {
        "list_endpoint": "/api/v1/project/",
        "schema": "/api/v1/project/schema/"
    },
    "user": {
        "list_endpoint": "/api/v1/user/",
        "schema": "/api/v1/user/schema/"
    },
    "version": {
        "list_endpoint": "/api/v1/version/",
        "schema": "/api/v1/version/schema/"
    }
}

Data:	list_endpoint (string) – API endpoint for resource. schema (string) – API endpoint for schema of resource.

Builds¶

GET /api/v1/build/¶

Retrieve a list of Builds.¶

{
    "meta": {
        "limit": 20,
        "next": "/api/v1/build/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 86684
    },
    "objects": [BUILDS]
}

Data:	limit (integer) – Number of Builds returned. next (string) – URI for next set of Builds. offset (integer) – Current offset used for pagination. previous (string) – URI for previous set of Builds. total_count (integer) – Total number of Builds. objects (array) – Array of Build objects.

Build¶

GET /api/v1/build/{id}/¶

Path arguments:	id – A Build id.

Retrieve a single Build.¶

{
    "date": "2012-03-12T19:58:29.307403",
    "error": "SPHINX ERROR",
    "id": "91207",
    "output": "SPHINX OUTPUT",
    "project": "/api/v1/project/2599/",
    "resource_uri": "/api/v1/build/91207/",
    "setup": "HEAD is now at cd00d00 Merge pull request #181 from Nagyman/solr_setup\n",
    "setup_error": "",
    "state": "finished",
    "success": true,
    "type": "html",
    "version": "/api/v1/version/37405/"
}

Data:

date (string) – Date of Build. error (string) – Error from Sphinx build process. id (string) – Build id. output (string) – Output from Sphinx build process. project (string) – URI for Project of Build. resource_uri (string) – URI for Build. setup (string) – Setup output from Sphinx build process. setup_error (string) – Setup error from Sphinx build process. state (string) – “triggered”, “building”, or “finished” success (boolean) – Was build successful? type (string) – Build type (“html”, “pdf”, “man”, or “epub”) version (string) – URI for Version of Build.

Files¶

GET /api/v1/file/¶

Retrieve a list of Files.¶

{
    "meta": {
        "limit": 20,
        "next": "/api/v1/file/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 32084
    },
    "objects": [FILES]
}

Data:	limit (integer) – Number of Files returned. next (string) – URI for next set of Files. offset (integer) – Current offset used for pagination. previous (string) – URI for previous set of Files. total_count (integer) – Total number of Files. objects (array) – Array of File objects.

File¶

GET /api/v1/file/{id}/¶

Path arguments:	id – A File id.

Retrieve a single File.¶

{
    "absolute_url": "/docs/keystone/en/latest/search.html",
    "id": "332692",
    "name": "search.html",
    "path": "search.html",
    "project": {PROJECT},
    "resource_uri": "/api/v1/file/332692/"
  }

Data:	absolute_url (string) – URI for actual file (not the File object from the API.) id (string) – File id. name (string) – Name of File. path (string) – Name of Path. project (object) – A Project object for the file’s project. resource_uri (string) – URI for File object.

Projects¶

GET /api/v1/project/¶

Retrieve a list of Projects.¶

{
    "meta": {
        "limit": 20,
        "next": "/api/v1/project/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 2067
    },
    "objects": [PROJECTS]
}

Data:	limit (integer) – Number of Projects returned. next (string) – URI for next set of Projects. offset (integer) – Current offset used for pagination. previous (string) – URI for previous set of Projects. total_count (integer) – Total number of Projects. objects (array) – Array of Project objects.

Project¶

GET /api/v1/project/{id}¶

Path arguments:	id – A Project id.

Retrieve a single Project.¶

{
    "absolute_url": "/projects/docs/",
    "analytics_code": "",
    "copyright": "",
    "crate_url": "",
    "default_branch": "",
    "default_version": "latest",
    "description": "Make docs.readthedocs.org work :D",
    "django_packages_url": "",
    "documentation_type": "sphinx",
    "id": "2599",
    "modified_date": "2012-03-12T19:59:09.130773",
    "name": "docs",
    "project_url": "",
    "pub_date": "2012-02-19T18:10:56.582780",
    "repo": "git://github.com/rtfd/readthedocs.org",
    "repo_type": "git",
    "requirements_file": "",
    "resource_uri": "/api/v1/project/2599/",
    "slug": "docs",
    "subdomain": "http://docs.readthedocs.org/",
    "suffix": ".rst",
    "theme": "default",
    "use_virtualenv": false,
    "users": [
        "/api/v1/user/1/"
    ],
    "version": ""
}

Data:

absolute_url (string) – URI for project (not the Project object from the API.) analytics_code (string) – Analytics tracking code. copyright (string) – Copyright crate_url (string) – Crate.io URI. default_branch (string) – Default branch. default_version (string) – Default version. description (string) – Description of project. django_packages_url (string) – Djangopackages.com URI. documentation_type (string) – Either “sphinx” or “sphinx_html”. id (string) – Project id. modified_date (string) – Last modified date. name (string) – Project name. project_url (string) – Project homepage. pub_date (string) – Last published date. repo (string) – URI for VCS repository. repo_type (string) – Type of VCS repository. requirements_file (string) – Pip requirements file for packages needed for building docs. resource_uri (string) – URI for Project. slug (string) – Slug. subdomain (string) – Subdomain. suffix (string) – File suffix of docfiles. (Usually ”.rst”.) theme (string) – Sphinx theme. use_virtualenv (boolean) – Build project in a virtualenv? (True or False) users (array) – Array of readthedocs.org user URIs for administrators of Project. version (string) – DEPRECATED.

Users¶

GET /api/v1/user/¶

Retrieve List of Users¶

{
    "meta": {
        "limit": 20,
        "next": "/api/v1/user/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 3200
    },
    "objects": [USERS]
}

Data:	limit (integer) – Number of Users returned. next (string) – URI for next set of Users. offset (integer) – Current offset used for pagination. previous (string) – URI for previous set of Users. total_count (integer) – Total number of Users. USERS (array) – Array of User objects.

User¶

GET /api/v1/user/{id}/¶

Path arguments:	id – A User id.

Retrieve a single User¶

{
    "first_name": "",
    "id": "1",
    "last_login": "2010-10-28T13:38:13.022687",
    "last_name": "",
    "resource_uri": "/api/v1/user/1/",
    "username": "testuser"
}

Data:	first_name (string) – First name. id (string) – User id. last_login (string) – Timestamp of last login. last_name (string) – Last name. resource_uri (string) – URI for this user. username (string) – User name.

Versions¶

GET /api/v1/version/¶

Retrieve a list of Versions.¶

{
    "meta": {
        "limit": 20,
        "next": "/api/v1/version/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 16437
    },
    "objects": [VERSIONS]
}

Data:	limit (integer) – Number of Versions returned. next (string) – URI for next set of Versions. offset (integer) – Current offset used for pagination. previous (string) – URI for previous set of Versions. total_count (integer) – Total number of Versions. objects (array) – Array of Version objects.

Version¶

GET /api/v1/version/{id}¶

Path arguments:	id – A Version id.

Retrieve a single Version.¶

{
    "active": false,
    "built": false,
    "id": "12095",
    "identifier": "remotes/origin/zip_importing",
    "project": {PROJECT},
    "resource_uri": "/api/v1/version/12095/",
    "slug": "zip_importing",
    "uploaded": false,
    "verbose_name": "zip_importing"
}

Data:

active (boolean) – Are we continuing to build docs for this version? built (boolean) – Have docs been built for this version? id (string) – Version id. identifier (string) – Identifier of Version. project (object) – A Project object for the version’s project. resource_uri (string) – URI for Version object. slug (string) – String that uniquely identifies a project uploaded (boolean) – Were docs uploaded? (As opposed to being build by Read the Docs.) verbose_name (string) – Usually the same as Slug.

Filtering Examples¶

http://readthedocs.org/api/v1/version/pip/highest/?format=json

http://readthedocs.org/api/v1/version/pip/highest/0.8/?format=json

http://readthedocs.org/api/v1/file/search/?format=json&q=virtualenvwrapper

http://readthedocs.org/api/v1/file/anchor/?format=json&q=virtualenv

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.

How do I use this locally, and on Read the Docs?¶

Unfortunately, at the moment Read the Docs can’t handle importing sphinx_rtd_theme, so if you try to use that theme for building on both Read the Docs and locally, it will fail. To build it locally, and on Read the Docs:

# on_rtd is whether we are on readthedocs.org
import os
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

if not on_rtd:  # only import and set the theme if we're building docs locally
    import sphinx_rtd_theme
    html_theme = 'sphinx_rtd_theme'
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

# otherwise, readthedocs.org uses their theme by default, so no need to specify it

Current sponsors¶

• Rackspace
• You? (Gittip)

All of the development of Read the Docs is funded on Gittip. If you appreciate the service, please consider helping support development on Gittip.

Past sponsors¶

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

Deploying Code¶

This uses the fabfile.py located in the root of project.

Pushing code to servers. This updates code & media:

fab push

Restart the webs:

fab restart

Restart the build servers celery:

fab celery

Deploying Nginx¶

This uses the fabfile located in deploy/fab/fabfile.py to deploy the nginx configs in deploy/nginx/.

To update the nginx configs:

fab nginx_configs

To reload nginx after the configs have been updated:

fab nginx_reload

Elastic Search Setup¶

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()

Servers¶

The servers are themed somewhere between Norse mythology and Final Fantasy Aeons. I tried to keep them topical, and have some sense of their historical meaning and their purpose in the infrastructure.

Site Checkout¶

/home/docs/sites/readthedocs.org/checkouts/readthedocs