Update docs 🎆
parent
fb583bf354
commit
4d6b328a51
|
@ -24,12 +24,12 @@ Documentation for RTD
|
|||
You will find complete documentation for setting up your project at `the Read
|
||||
the Docs site`_.
|
||||
|
||||
.. _the Read the Docs site: https://docs.readthedocs.org/
|
||||
.. _the Read the Docs site: https://docs.readthedocs.io/
|
||||
|
||||
Contributing
|
||||
------------
|
||||
|
||||
You can find information about contributing to Read the Docs at our `Contribution page <http://docs.readthedocs.org/en/latest/contribute.html#contributing-to-development>`_
|
||||
You can find information about contributing to Read the Docs at our `Contribution page <http://docs.readthedocs.io/en/latest/contribute.html#contributing-to-development>`_
|
||||
|
||||
Quickstart for GitHub-Hosted Projects
|
||||
-------------------------------------
|
||||
|
@ -65,4 +65,4 @@ when you push to GitHub.
|
|||
.. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest
|
||||
:alt: Documentation Status
|
||||
:scale: 100%
|
||||
:target: https://docs.readthedocs.org/en/latest/?badge=latest
|
||||
:target: https://docs.readthedocs.io/en/latest/?badge=latest
|
||||
|
|
|
@ -6,7 +6,7 @@ Read the Docs supports a number of custom domains for your convenience. Shorter
|
|||
Subdomain Support
|
||||
------------------
|
||||
|
||||
Every project has a subdomain that is available to serve its documentation. If you go to <slug>.readthedocs.org, it should show you the latest version of documentation. A good example is http://pip.readthedocs.org
|
||||
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
|
||||
|
||||
.. note:: If you have an old project that has an underscore (_) in the name, it will use a subdomain with a hypen (-).
|
||||
`RFC 1035 <http://tools.ietf.org/html/rfc1035>`_ has more information on valid subdomains.
|
||||
|
@ -27,7 +27,7 @@ As an example, fabric's dig record looks like this::
|
|||
-> dig docs.fabfile.org
|
||||
...
|
||||
;; ANSWER SECTION:
|
||||
docs.fabfile.org. 7200 IN CNAME readthedocs.org.
|
||||
docs.fabfile.org. 7200 IN CNAME readthedocs.io.
|
||||
|
||||
.. note:: We used to map your projects documentation from the subdomain that you pointed your CNAME to.
|
||||
This wasn't workable at scale,
|
||||
|
@ -56,7 +56,7 @@ An example nginx configuration for pip would look like:
|
|||
server {
|
||||
server_name docs.pip-installer.org;
|
||||
location / {
|
||||
proxy_pass https://pip.readthedocs.org:443;
|
||||
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;
|
||||
|
@ -70,4 +70,4 @@ An example nginx configuration for pip would look like:
|
|||
rtfd.org
|
||||
---------
|
||||
|
||||
You can also use `rtfd.org` as a short URL for Read the Docs. For example, http://pip.rtfd.org redirects to its documentation page. Any use of `rtfd.org` will simply be redirected to `readthedocs.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`.
|
||||
|
|
14
docs/api.rst
14
docs/api.rst
|
@ -10,7 +10,7 @@ The API is written in Tastypie, which provides a nice ability to browse the API
|
|||
A basic API client using slumber
|
||||
--------------------------------
|
||||
|
||||
You can use `Slumber <http://slumber.readthedocs.org/>`_ to build basic API wrappers in python. Here is a simple example of using slumber to interact with the RTD API::
|
||||
You can use `Slumber <http://slumber.readthedocs.io/>`_ to build basic API wrappers in python. Here is a simple example of using slumber to interact with the RTD API::
|
||||
|
||||
from __future__ import print_function
|
||||
import slumber
|
||||
|
@ -296,7 +296,7 @@ Project
|
|||
"crate_url": "",
|
||||
"default_branch": "",
|
||||
"default_version": "latest",
|
||||
"description": "Make docs.readthedocs.org work :D",
|
||||
"description": "Make docs.readthedocs.io work :D",
|
||||
"django_packages_url": "",
|
||||
"documentation_type": "sphinx",
|
||||
"id": "2599",
|
||||
|
@ -309,7 +309,7 @@ Project
|
|||
"requirements_file": "",
|
||||
"resource_uri": "/api/v1/project/2599/",
|
||||
"slug": "docs",
|
||||
"subdomain": "http://docs.readthedocs.org/",
|
||||
"subdomain": "http://docs.readthedocs.io/",
|
||||
"suffix": ".rst",
|
||||
"theme": "default",
|
||||
"use_virtualenv": false,
|
||||
|
@ -561,7 +561,7 @@ File Search
|
|||
"requirements_file": "",
|
||||
"resource_uri": "/api/v1/project/530/",
|
||||
"slug": "python-guide",
|
||||
"subdomain": "http://python-guide.readthedocs.org/",
|
||||
"subdomain": "http://python-guide.readthedocs.io/",
|
||||
"suffix": ".rst",
|
||||
"theme": "kr",
|
||||
"use_virtualenv": false,
|
||||
|
@ -593,9 +593,9 @@ Anchor Search
|
|||
|
||||
{
|
||||
"objects": [
|
||||
"http//django-fab-deploy.readthedocs.org/en/latest/...",
|
||||
"http//dimagi-deployment-tools.readthedocs.org/en/...",
|
||||
"http//openblock.readthedocs.org/en/latest/install/base_install.html#virtualenv",
|
||||
"http//django-fab-deploy.readthedocs.io/en/latest/...",
|
||||
"http//dimagi-deployment-tools.readthedocs.io/en/...",
|
||||
"http//openblock.readthedocs.io/en/latest/install/base_install.html#virtualenv",
|
||||
...
|
||||
]
|
||||
}
|
||||
|
|
|
@ -11,12 +11,12 @@ A link to the root of your documentation will redirect to the *default version*,
|
|||
as set in your project settings.
|
||||
For example::
|
||||
|
||||
pip.readthedocs.org -> pip.readthedocs.org/en/latest/
|
||||
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.org/ 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.org/en/develop.) But, it's not a universal redirecting solution. So, for example, a link to an internal page like http://pip.readthedocs.org/usage.html doesn't redirect to http://pip.readthedocs.org/en/latest/usage.html.
|
||||
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.org/en/latest/ is the root directory for your default documentation in English, not http://pip.readthedocs.org/. Just like http://pip.readthedocs.org/en/develop/ is the root for your development documentation in English.
|
||||
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.
|
||||
|
||||
|
@ -53,7 +53,7 @@ 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.org/page/quickstart.html -> pip.readthedocs.org/en/latest/quickstart.html
|
||||
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.
|
||||
|
|
|
@ -15,10 +15,10 @@ 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.org`` and ``http://docs.fabfile.org`` for their documentation.
|
||||
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.org``, it will know that it should really point at ``http://docs.fabfile.org``.
|
||||
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
|
||||
--------
|
||||
|
@ -33,7 +33,7 @@ you should see a bit of HTML like this:
|
|||
|
||||
.. code-block:: html
|
||||
|
||||
<link rel="canonical" href="http://pip.readthedocs.org/en/latest/installing.html">
|
||||
<link rel="canonical" href="http://pip.readthedocs.io/en/latest/installing.html">
|
||||
|
||||
Links
|
||||
-----
|
||||
|
|
|
@ -37,9 +37,9 @@ exclude_patterns = ['_build']
|
|||
default_role = 'obj'
|
||||
pygments_style = 'sphinx'
|
||||
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),
|
||||
'python': ('http://python.readthedocs.io/en/latest/', None),
|
||||
'django': ('http://django.readthedocs.io/en/latest/', None),
|
||||
'sphinx': ('http://sphinx.readthedocs.io/en/latest/', None),
|
||||
}
|
||||
# This doesn't exist since we aren't shipping any static files ourselves.
|
||||
#html_static_path = ['_static']
|
||||
|
|
|
@ -107,9 +107,9 @@ 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:
|
||||
so you can access it on the `celery.readthedocs.io` domain:
|
||||
|
||||
http://celery.readthedocs.org/projects/kombu/en/latest/
|
||||
http://celery.readthedocs.io/projects/kombu/en/latest/
|
||||
|
||||
This also works the same for CNAMEs:
|
||||
|
||||
|
@ -170,7 +170,7 @@ 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 <https://github.com/numpy/numpydoc>`_ and
|
||||
`napoleon <http://sphinxcontrib-napoleon.readthedocs.org>`_. Only
|
||||
`napoleon <http://sphinxcontrib-napoleon.readthedocs.io>`_. 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.
|
||||
|
|
|
@ -7,7 +7,7 @@ Internationalization
|
|||
This document covers the details regarding internationalization and
|
||||
localization that are applied in Read the Docs. The guidelines described are
|
||||
mostly based on `Kitsune's localization documentation
|
||||
<http://kitsune.readthedocs.org/en/latest/localization.html>`_.
|
||||
<http://kitsune.readthedocs.io/en/latest/localization.html>`_.
|
||||
|
||||
As with most of the Django applications out there, Read the Docs' i18n/l10n
|
||||
framework is based on `GNU gettext <http://www.gnu.org/software/gettext/>`_.
|
||||
|
|
|
@ -43,8 +43,8 @@ you will say that ``phpmyadmin-spanish`` is a translation for your project.
|
|||
|
||||
This has the results of serving:
|
||||
|
||||
* ``phpmyadmin`` at ``http://phpmyadmin.readthedocs.org/en/latest/``
|
||||
* ``phpmyadmin-spanish`` at ``http://phpmyadmin.readthedocs.org/es/latest/``
|
||||
* ``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:
|
||||
|
||||
|
|
|
@ -17,7 +17,7 @@ You can toggle the "Single Version" option on or off for your project in the Pro
|
|||
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.org/`` rather than the default ``http://pip.readthedocs.org/en/latest/``.
|
||||
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 :doc:`canonical` should stop these from being indexed by Google.
|
||||
|
||||
|
|
|
@ -34,11 +34,11 @@ target a single environment to limit the test suite::
|
|||
docs
|
||||
Test documentation compilation with Sphinx.
|
||||
|
||||
.. _`Tox`: http://tox.readthedocs.org/en/latest/index.html
|
||||
.. _`Prospector`: http://prospector.readthedocs.org/en/master/
|
||||
.. _`Tox`: http://tox.readthedocs.io/en/latest/index.html
|
||||
.. _`Prospector`: http://prospector.readthedocs.io/en/master/
|
||||
.. _`pylint`: http://docs.pylint.org/
|
||||
.. _`pyflakes`: https://github.com/pyflakes/pyflakes
|
||||
.. _`pep8`: http://pep8.readthedocs.org/en/latest/index.html
|
||||
.. _`pep8`: http://pep8.readthedocs.io/en/latest/index.html
|
||||
|
||||
Continuous Integration
|
||||
----------------------
|
||||
|
|
|
@ -44,7 +44,7 @@ Redirects on root URLs
|
|||
----------------------
|
||||
|
||||
When a user hits the root URL for your documentation,
|
||||
for example ``http://pip.readthedocs.org/``,
|
||||
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.
|
||||
|
|
Loading…
Reference in New Issue