EbookFoundation
/
readthedocs.org
mirror of https://github.com/EbookFoundation/readthedocs.org.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docs 🎆

simple-symlink-serving
Anthony Johnson 2016-04-27 16:14:36 -07:00
parent fb583bf354
commit 4d6b328a51
12 changed files with 35 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
README.rst
View File

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

8
docs/alternate_domains.rst
View File

@ -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
View File

@ -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",
...
]
}

8
docs/automatic-redirects.rst
View File

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

6
docs/canonical.rst
View File

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

6
docs/conf.py
View File

@ -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']

6
docs/faq.rst
View File

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

2
docs/i18n.rst
View File

@ -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/>`_.

4
docs/localization.rst
View File

@ -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:

2
docs/single_version.rst
View File

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

6
docs/tests.rst
View File

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

2
docs/versions.rst
View File

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