功能

This will serve as a list of all of the features that Read the Docs currently has. Some features are important enough to have their own page in the docs, others will simply be listed here.

整合Github

We now support linking to GitHub by default in the sidebar. It links to the page on GitHub, and directly links to the edit view as well. This should help people quickly update typos and send pull requests to contribute to project documentation.

If you want to integrate this 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>
  <li><a href="https://github.com/{{ github_user }}/{{ github_repo }}/edit/{{ github_version }}{{ conf_py_path }}{{ pagename }}.rst">
    Edit on GitHub</a></li>
{% endif %}

截图

_images/edit_on_github.png

自更新

The 网络挂钩 page talks about the different way 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.

重缓存

We run Varnish in front of RTD, so a lot of the docs you look at will be served out of memory. This is really great for the “Look up and link” that happens a lot on IRC channels. The person who looks up the link will cache the page, and the person they link it to will get it served really quickly.

We also bust caches on all documentation on the RTD domain (not CNAMEs, yet) when you build your docs, so you shouldn’t have problems with stale caches.

版本

Versions are supported at the Version Control level. We support tags and branches that map to versions in RTD parlance. Not all version control systems are equally supported. We would love to accept patches from users of other VCS systems to gain equivalent features across systems.

版本控制支持矩阵

  Git hg bzr svn
Updating Yes Yes Yes Yes
Tags Yes Yes No No
Branches Yes No Yes No
Default master default   trunk

PDF 生成

When you build your project on RTD, we automatically build a PDF of your projects 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.

搜索

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.

备用域名

We provide support for CNAMEs, Subdomains, and a shorturl for your project as well. This is outlined in the 备用域名 section.

Intersphinx 支持

We host intersphinx catalogs for all projects built on Read the Docs. For more info on this support, read the Sphinx docs on Intersphinx. Your configuration should look something like this:

intersphinx_mapping = {
  'python': ('http://python.readthedocs.org/en/latest/', None),
  'django': ('http://django.readthedocs.org/en/latest/', None),
  'sphinx': ('http://sphinx.readthedocs.org/en/latest/', None),
    }

Then usage is pretty similar. You reference something using normal sphinx syntax, but can use the namespace of the project you want to reference, like so:

:mod:`Intersphinx <sphinx.ext.intersphinx>`
:mod:`Intersphinx <sphinx:sphinx.ext.intersphinx>`

This will create a link to the official Sphinx documentation for intersphinx.

More information can be found on Reinout van Rees’ blog: http://reinout.vanrees.org/weblog/2012/12/01/django-intersphinx.html

Read the Docs v: latest
Versions
latest
Downloads
PDF
HTML
Epub
On Read the Docs
Project Home
Builds

Free document hosting provided by Read the Docs.