readthedocs · ericholscher · May 24, 2018 · Feb 16, 2018 · Feb 16, 2018 · Feb 16, 2018
diff --git a/.travis.yml b/.travis.yml
@@ -7,6 +7,8 @@ matrix:
   include:
     - python: 2.7
       env: TOXENV=docs
+    - python: 3.6
+      env: TOXENV=docs-lint
     - python: 2.7
       env: TOXENV=lint
     - python: 2.7

diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg
@@ -0,0 +1,4 @@
+[rstcheck]
+ignore_directives=automodule,http:get
+ignore_roles=djangosetting,setting
+ignore_messages=(Duplicate implicit target name: ".*")|(Hyperlink target ".*" is not referenced)
diff --git a/docs/automatic-redirects.rst b/docs/automatic-redirects.rst
@@ -33,7 +33,7 @@ Supported Top-Level Redirects
 .. note:: These "implicit" redirects are supported for legacy reasons.
           We will not be adding support for any more magic redirects.
           If you want additional redirects,
-          they should live at a prefix like :ref:`page-redirect`
+          they should live at a prefix like `Redirecting to a Page`_
 
 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::
 
@@ -44,8 +44,6 @@ The main challenge of URL routing in Read the Docs is handling redirects correct
 The language redirect will work for any of the defined ``LANGUAGE_CODES`` we support.
 The version redirect will work for supported versions.
 
-.. _page-redirect:
-
 Redirecting to a Page
 ---------------------
 

diff --git a/docs/business/index.rst b/docs/business/index.rst
@@ -1,15 +1,18 @@
 Read the Docs Business Features
 -------------------------------
 
-.. note:: These features are for our new business offering, `readthedocs.com <https://readthedocs.com/>`_.
+.. note:: These features are for our new business offering, `readthedocs.com`_.
+
 
 All of the other features outlined in these docs work on both sites.
 Things inside this section are specific to our business offering.
 
-The largest feature that is different is that documentation on `readthedocs.com <https://readthedocs.com/>`_ is **private**.
+The largest feature that is different is that documentation on `readthedocs.com`_ is **private**.
 If you have private code that you want documentation for,
 this is our solution.
 
+.. _readthedocs.com: https://readthedocs.com
+
 .. toctree:: 
 
    organizations

diff --git a/docs/canonical.rst b/docs/canonical.rst
@@ -45,5 +45,3 @@ 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
-
-.. _dashboard: https://readthedocs.org/dashboard/
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -26,7 +26,7 @@ Code Notes
 - Updated django-celery from `3.0.23` to `3.1.26` as django-celery 3.0.x does not support Django 1.8.
 - Updated Celery from `3.0.24` to `3.1.18` because we had to update django-celery. We need to test this extensively and might need to think about using the new Celery API directly and dropping django-celery. See release notes: http://docs.celeryproject.org/en/latest/whatsnew-3.1.html
 - Updated tastypie from `0.11.1` to current master (commit `1e1aff3dd4dcd21669e9c68bd7681253b286b856`) as 0.11.x is not compatible with Django 1.8. No surprises expected but we should ask for a proper release, see release notes: https://github.com/django-tastypie/django-tastypie/blob/master/docs/release_notes/v0.12.0.rst
-- Updated django-oauth from `0.16.1` to `0.21.0`. No surprises expected, see release notes [in the docs](https://django-allauth.readthedocs.org/en/latest/changelog.html) and [finer grained in the repo](https://github.com/pennersr/django-allauth/blob/9123223f167959e4e5c4074408db068f725559d1/ChangeLog#L1-169)
+- Updated django-oauth from `0.16.1` to `0.21.0`. No surprises expected, see release notes `in the docs <https://django-allauth.readthedocs.org/en/latest/changelog.html>`_ and `finer grained in the repo <https://github.com/pennersr/django-allauth/blob/9123223f167959e4e5c4074408db068f725559d1/ChangeLog#L1-169>`_
 - Updated django-guardian from `1.2.0` to `1.3.0` to gain Django 1.8 support. No surprises expected, see release notes: https://github.com/lukaszb/django-guardian/blob/devel/CHANGES
 - Using `django-formtools` instead of removed `django.contrib.formtools` now. Based on the Django release notes, these modules are the same except of the package name.
 - Updated pytest-django from `2.6.2` to `2.8.0`. No tests required, but running the testsuite :smile: 

diff --git a/docs/contribute.rst b/docs/contribute.rst
@@ -1,5 +1,3 @@
-.. _contributing-to-read-the-docs:
-
 Contributing to Read the Docs
 =============================
 
@@ -10,7 +8,6 @@ get stuck at any point you can create a `ticket on GitHub`_.
 All members of our community are expected to follow our :doc:`/code-of-conduct`.
 Please make sure you are welcoming and friendly in all of our spaces.
 
-.. _#readthedocs: irc://irc.freenode.net/readthedocs
 .. _ticket on GitHub: https://github.com/rtfd/readthedocs.org/issues
 
 Contributing to development

diff --git a/docs/custom_installs/local_rtd_vm.rst b/docs/custom_installs/local_rtd_vm.rst
@@ -28,8 +28,8 @@ Assumptions and Prerequisites
 Local RTD Setup
 ---------------
 
-1. Install RTD.
-~~~~~~~~~~~~~~~
+Install RTD
+~~~~~~~~~~~
 
 To host your documentation on a local RTD installation, set it up in your VM. ::
 
@@ -60,8 +60,8 @@ Also don't forget to re-run the dependency installation ::
 
     $ sudo pip install -r requirements.txt
 
-2. Configure the RTD Server and Superuser.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Configure the RTD Server and Superuser
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 1. Run the following commands. ::
 
@@ -74,8 +74,8 @@ Also don't forget to re-run the dependency installation ::
     Email address: monami.b@email.com
     Password: pa$$word
 
-3. RTD Server Administration.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+RTD Server Administration
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Navigate to the ``../checkouts/readthedocs.org`` folder in your VM and run the following command. ::
 
@@ -86,9 +86,8 @@ You should now be able to log into the admin interface from any PC in your LAN a
 
 Go to the dashboard at  ``http://[VM IP ADDRESS]:8000/dashboard`` and follow these steps:
 
-1. Point the repository to your corporate Git project where the documentation source is checked in. Example:
-git.corp.company.com:/git/docs/documentation.git
-
+1. Point the repository to your corporate Git project where the documentation source is checked in.
+   Example: ``git.corp.company.com:/git/docs/documentation.git``.
 2. Clone the documentation sources from Git in the VM.
 3. Navigate to the root path for documentation.
 4. Run the following Sphinx commands. ::
@@ -127,8 +126,8 @@ SSH to the VM using the ``-A`` directive. ::
 
 This provides all permissions for that particular remote session, which are revoked when you logout.
 
-4. Build Documentation on Local RTD Instance.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Build Documentation on Local RTD Instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Log into ``http://[VM IP ADDRESS]:[PORT]`` using the django superuser creds and follow these steps.	
 

diff --git a/docs/design.rst b/docs/design.rst
@@ -1,5 +1,3 @@
-.. _designing-read-the-docs:
-
 Designing Read the Docs
 =======================
 
@@ -44,7 +42,7 @@ your example project.
 Contributing
 ------------
 
-Contributions should follow the :ref:`contributing-to-read-the-docs` guidelines where applicable -- ideally you'll
+Contributions should follow the :doc:`contribute` 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.
@@ -54,7 +52,3 @@ browsers, IE8+ -- that's not to say it needs to be pixel-perfect in older browse
 making changes that render older browsers utterly unusable (or provide a sane fallback).
 
 .. _Read the Docs GitHub project: https://github.com/rtfd/readthedocs.org/pulls
-
-
-
-
diff --git a/docs/design/theme-context.rst b/docs/design/theme-context.rst
@@ -25,74 +25,76 @@ Note that this dictionary is injected under the main key `readthedocs`:
 
 .. code:: python
 
-    'readthedocs': {
-        'v1': {
-            'version': {
-                'id': int,
-                'slug': str,
-                'verbose_name': str,
-                'identifier': str,
-                'type': str,
-                'build_date': str,
-                'downloads': {
-                    'pdf: str,
-                    'htmlzip': str,
-                    'epub': str
-                },
-                'links': [{
-                    'href': 'https://readthedocs.org/api/v2/version/{id}/',
-                    'rel': 'self
-                }]
-            },
-            'project': {
-                'id': int
-                'name': str,
-                'slug': str,
-                'description': str,
-                'language': str,
-                'canonical_url': str,
-                'subprojects': [{
-                    'id': int
-                    'name': str,
-                    'slug': str,
-                    'description': str,
-                    'language': str,
-                    'canonical_url': str,
-                    'links': [{
-                        'href': 'https://readthedocs.org/api/v2/project/{id}/',
-                        'rel': 'self
-                    }]
-                }],
-                'links': [{
-                    'href': 'https://readthedocs.org/api/v2/project/{id}/',
-                    'rel': 'self
-                }]
-            },
-            'sphinx': {
-                'html_theme': str,
-                'source_suffix': str
-            },
-            'analytics': {
-                'user_analytics_code': str,
-                'global_analytics_code': str
-            },
-            'vcs': {
-                'type': str,  # 'bitbucket', 'github', 'gitlab' or 'svn'
-                'user': str,
-                'repo': str,
-                'commit': str,
-                'version': str,
-                'display': bool,
-                'conf_py_path': str
-            },
-            'meta': {
-                'API_HOST': str,
-                'MEDIA_URL': str,
-                'PRODUCTION_DOMAIN': str,
-                'READTHEDOCS': True
-            }
-        }
-    }
+   {
+       'readthedocs': {
+           'v1': {
+               'version': {
+                   'id': int,
+                   'slug': str,
+                   'verbose_name': str,
+                   'identifier': str,
+                   'type': str,
+                   'build_date': str,
+                   'downloads': {
+                       'pdf': str,
+                       'htmlzip': str,
+                       'epub': str
+                   },
+                   'links': [{
+                       'href': 'https://readthedocs.org/api/v2/version/{id}/',
+                       'rel': 'self'
+                   }],
+               },
+               'project': {
+                   'id': int,
+                   'name': str,
+                   'slug': str,
+                   'description': str,
+                   'language': str,
+                   'canonical_url': str,
+                   'subprojects': [{
+                       'id': int,
+                       'name': str,
+                       'slug': str,
+                       'description': str,
+                       'language': str,
+                       'canonical_url': str,
+                       'links': [{
+                           'href': 'https://readthedocs.org/api/v2/project/{id}/',
+                           'rel': 'self'
+                       }]
+                   }],
+                   'links': [{
+                       'href': 'https://readthedocs.org/api/v2/project/{id}/',
+                       'rel': 'self'
+                   }]
+               },
+               'sphinx': {
+                   'html_theme': str,
+                   'source_suffix': str
+               },
+               'analytics': {
+                   'user_analytics_code': str,
+                   'global_analytics_code': str
+               },
+               'vcs': {
+                   'type': str,  # 'bitbucket', 'github', 'gitlab' or 'svn'
+                   'user': str,
+                   'repo': str,
+                   'commit': str,
+                   'version': str,
+                   'display': bool,
+                   'conf_py_path': str
+               },
+               'meta': {
+                   'API_HOST': str,
+                   'MEDIA_URL': str,
+                   'PRODUCTION_DOMAIN': str,
+                   'READTHEDOCS': True
+               }
+           }
+       }
+   }
 
 
 .. warning::

diff --git a/docs/dmca/index.rst b/docs/dmca/index.rst
@@ -4,32 +4,36 @@ DMCA Takedown Policy
 These are the guidelines that Read the Docs follows when handling DMCA takedown
 requests and takedown counter requests. If you are a copyright holder wishing to
 submit a takedown request, or an author that has been notified of a takedown
-request, please familiarize yourself with `our process <Takedown Process_>`_.
+request, please familiarize yourself with `our process`__.
 You will be asked to confirm that you have reviewed information if you submit a
 request or counter request.
 
+__ `Takedown Process`_
+
 We aim to keep this entire process as transparent as possible. Our process is
-modeled after `GitHub's DMCA takedown process <github-dmca_>`_, which we
+modeled after `GitHub's DMCA takedown process`__, which we
 appreciate for its focus on transparency and fairness. All requests and counter
 requests will be posted to this page below, in the `Request Archive`_. These
 requests will be redacted to remove all identifying information, except for Read
 the Docs user and project names.
 
-.. _github-dmca: https://help.github.com/articles/dmca-takedown-policy/
+__ https://help.github.com/articles/dmca-takedown-policy/
 
 Takedown Process
 ----------------
 
 Here are the steps the Read the Docs will follow in the takedown request process:
 
 Copyright holder submits a request
-    This request, if valid, will be posted publicly on this page, `down below
-    <Request Archive_>`_. The author affected by the takedown request will be
+    This request, if valid, will be posted publicly on this page, `down below`__.
+    The author affected by the takedown request will be
     notified with a link to the takedown request.
 
     For more information on submitting a takedown request, see: `Submitting a
     Request`_
 
+__ `Request Archive`_
+
 Author is contacted
     The author of the content in question will be asked to make changes to the
     content specified in the takedown request. The author will have 24 hours to
@@ -61,13 +65,15 @@ Author submits a counter request
     If the author believes their content was disabled as a result of a mistake,
     a counter request may be submitted. It would be advised that authors seek
     legal council before continuing. If the submitted counter request is
-    sufficiently detailed, this counter will also be added to `this page
-    <Request Archive_>`_. The copyright holder will be notified, with a link to
+    sufficiently detailed, this counter will also be added to `this page`__.
+    The copyright holder will be notified, with a link to
     this counter request.
 
     For more information on submitting a counter request, see: `Submitting a
     Counter`_
 
+__ `Request Archive`_
+
 Copyright holder may file legal action
     At this point, if the copyright holder wishes to keep the offending content
     disabled, the copyright holder must file for legal action ordering the

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -164,7 +164,7 @@ RTD doesn't have explicit support for this. That said, a tool like `Disqus`_ (an
 How do I support multiple languages of documentation?
 -----------------------------------------------------
 
-See the section on :ref:`Localization of Documentation`.
+See the section on :doc:`localization`.
 
 Does Read The Docs work well with "legible" docstrings?
 -------------------------------------------------------

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -13,10 +13,8 @@ Write Your Docs
 
 You have two options for formatting your documentation:
 
-* :ref:`in-rst`
-* :ref:`in-markdown`
-
-.. _in-rst:
+* `In reStructuredText`_
+* `In Markdown`_
 
 In reStructuredText
 ~~~~~~~~~~~~~~~~~~~
@@ -53,8 +51,6 @@ or `this template`_ if you need help). Build them to see how they look::
 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.
 
-.. _in-markdown:
-
 In Markdown
 ~~~~~~~~~~~