Use autosectionlabel extension

docs/conf.py

@@ -21,6 +21,7 @@
 
 sys.path.append(os.path.abspath('_ext'))
 extensions = [
+    'sphinx.ext.autosectionlabel',
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinxcontrib.httpdomain',
@@ -79,6 +80,9 @@
     'display_version': False,
 }
 
+# Activate autosectionlabel plugin
+autosectionlabel_prefix_document = True
+
 
 def setup(app):
     app.add_stylesheet('custom.css')

docs/contribute.rst

@@ -15,7 +15,7 @@ Contributing to development
 
 If you want to deep dive and help out with development on Read the Docs, then
 first get the project installed locally according to the
-:ref:`Installation Guide <installing-read-the-docs>`. After that is done we
+:doc:`Installation Guide <install>`. After that is done we
 suggest you have a look at tickets in our issue tracker that are labelled `Good
 First Issue`_. These are meant to be a great way to get a smooth start and
 won't put you in front of the most complex parts of the system.
@@ -224,7 +224,7 @@ few more at hand to further categorize issues.
 .. _milestone: https://github.com/rtfd/readthedocs.org/milestones
 
 For a full list of available labels and their meanings, see
-:ref:`issue-label-overview`.
+:doc:`issue-labels`.
 
 Helpful links for triaging
 ~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/design.rst

@@ -7,7 +7,7 @@ time and design skills to Read the Docs? That's
 a few features available to ease the process of
 working with Read the Doc's CSS and static assets.
 
-To start, you should follow the :ref:`installing-read-the-docs` instructions
+To start, you should follow the :doc:`install` instructions
 to get a working copy of the Read the Docs repository locally.
 
 Style Catalog

docs/ethical-advertising.rst

@@ -9,10 +9,10 @@ and we're calling it **Ethical Ads**.
 **Ethical Ads respect users while providing value to advertisers.**
 We don't track you, sell your data, or anything else.
 We simply show ads to users, based on the content of the pages you look at.
-We also give 10% of our ad space to :ref:`community projects <community-ads>`,
+We also give 10% of our ad space to :ref:`community projects <ethical-advertising:Community Ads>`,
 as our way of saying thanks to the open source community.
 
-We talk a bit below about :ref:`our worldview on advertising <ethical-info>`,
+We talk a bit below about :ref:`our worldview on advertising <ethical-advertising:Our Worldview>`,
 if you want to know more.
 
 .. important::
@@ -28,14 +28,12 @@ and we value your feedback.
 If you ever want to reach out about this effort,
 feel free to `shoot us an email <mailto:[email protected]>`_.
 
-You can :ref:`opt out <opt-out>` of having paid ads on your projects,
+You can :ref:`opt out <ethical-advertising:Opting out>` of having paid ads on your projects,
 or seeing paid ads if you want.
-You will still see :ref:`community ads <community-ads>`,
+You will still see :ref:`community ads <ethical-advertising:Community Ads>`,
 which we run for free that promote community projects. 
 
-.. _ethical-info:
-
-Our worldview
+Our Worldview
 -------------
 
 We're building the advertising model we want to exist:
@@ -72,8 +70,8 @@ They should run before your content,
 they should take over the page,
 the bigger, weirder, or flashier the better.
 
-We opt out.
-~~~~~~~~~~~
+We opt out
+~~~~~~~~~~
 
 * We don't store personal information about you.
 * We only keep track of views and clicks.
@@ -128,8 +126,6 @@ There are a large number of projects that we care about in the software ecosyste
 We'll show 10% of our ad inventory each month to support an open source project that we care about.
 `Send us an email <mailto:[email protected]>`_ to be considered for our Community Ads program.
 
-.. _opt-out:
-
 Opting Out
 ----------
 
@@ -156,4 +152,3 @@ Project opt out options include:
 * Supporting us with `your time <http://docs.readthedocs.org/en/latest/contribute.html?>`_ by contributing to the project.
 * Moving to our `paid product <https://readthedocs.com/pricing/?>`_ over at readthedocs.com.
 * Opting out without doing any of the above. This will make us a little sad, but we understand not everyone has the means to contribute back.
-

docs/faq.rst

@@ -6,7 +6,8 @@ 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 :ref:`mock-c-extensions`.
+If you are still seeing errors because of C library dependencies,
+please see :ref:`faq:I get import errors on libraries that depend on C modules`.
 
 How do I change my slug (the URL your docs are served at)?
 ----------------------------------------------------------
@@ -56,8 +57,6 @@ environment, and will be set to ``True`` when building on RTD::
     Woo
     {% endif %}
 
-.. _mock-c-extensions:
-
 I get import errors on libraries that depend on C modules
 ---------------------------------------------------------
 

docs/getting_started.rst

@@ -6,7 +6,7 @@ You will have your docs imported on Read the Docs in 5 minutes,
 displayed beautifully for the world.
 
 If you are already using Sphinx or Markdown for your docs, skip ahead to
-:ref:`import-docs`.
+:ref:`getting_started:Import Your Docs`.
 
 Write Your Docs
 ---------------
@@ -79,8 +79,6 @@ Then in your ``conf.py``:
 
 .. _this blog post: http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
 
-.. _connect-account:
-
 Sign Up and Connect an External Account
 ---------------------------------------
 
@@ -94,8 +92,6 @@ Services*. From here, you'll be able to connect to your GitHub, Bitbucket or Git
 account. This process will ask you to authorize a connection to Read the Docs,
 that allows us to read information about and clone your repositories.
 
-.. _import-docs:
-
 Import Your Docs
 ----------------
 
@@ -127,8 +123,8 @@ Add an optional homepage URL and some tags, and then click **Next**.
 Once your project is created, you'll need to manually configure the repository
 webhook if you would like to have new changesets to trigger builds for your
 project on Read the Docs. Go to your project's **Integrations** page to
-configure a new webhook, or see :ref:`our steps for webhook creation
-<webhook-creation>` for more information on this process.
+configure a new webhook, or see :ref:`our steps for webhook creation <webhooks:Webhook Creation>`
+for more information on this process.
 
 Within a few seconds your code will automatically be fetched from your public repository,
 and the documentation will be built.

docs/install.rst

@@ -1,5 +1,3 @@
-.. _installing-read-the-docs:
-
 Installation
 ============
 

docs/issue-labels.rst

@@ -1,5 +1,3 @@
-.. _issue-label-overview:
-
 Overview of issue labels
 ========================
 

docs/privacy-policy.rst

@@ -151,10 +151,7 @@ We may share User Personal Information with a limited number of third party vend
 who process it on our behalf to provide or improve our service,
 and who have agreed to privacy restrictions similar to our own Privacy Statement.
 For more details, see our next section on
-:ref:`third parties <privacy-policy-third-parties>`.
-
-
-.. _privacy-policy-third-parties:
+:ref:`third parties <privacy-policy:Third party vendors>`.
 
 Third party vendors
 ~~~~~~~~~~~~~~~~~~~
@@ -189,7 +186,7 @@ Analytics
 +++++++++
 
 We go into detail on analytics in a
-:ref:`separate section specific to analytics <privacy-policy-analytics>`.
+:ref:`separate section specific to analytics <privacy-policy:Google Analytics>`.
 
 Email newsletter
 ++++++++++++++++
@@ -235,8 +232,6 @@ By using our website, you agree that we can place these types of cookies on your
 If you disable your browser or device's ability to accept cookies,
 you will not be able to log in to Read the Docs.
 
-.. _privacy-policy-analytics:
-
 Google Analytics
 ~~~~~~~~~~~~~~~~
 

docs/security.rst

@@ -6,23 +6,23 @@ Security is very important to us at Read the Docs. We are committed to responsib
 Reporting a security issue
 --------------------------
 
-If you believe you've discovered a security issue at Read the Docs, please contact us at **[email protected]** (optionally using our :ref:`pgp-key`). We request that you please not publicly disclose the issue until it has been addressed by us.
+If you believe you've discovered a security issue at Read the Docs,
+please contact us at **[email protected]** (optionally using our :ref:`security:PGP key`).
+We request that you please not publicly disclose the issue until it has been addressed by us.
 
 You can expect:
 
 * We will respond acknowledging your email typically within one business day.
 * We will follow up if and when we have confirmed the issue with a timetable for the fix.
 * We will notify you when the issue is fixed.
-* We will add the issue to our :ref:`security issue archive <security-issue-archive>`.
-
-.. _pgp-key:
+* We will add the issue to our :ref:`security issue archive <security:Security issue archive>`.
 
 PGP key
 -------
 
-You may use this `PGP key`_ to securely communicate with us and to verify signed messages you receive from us.
+You may use this `PGP key`__ to securely communicate with us and to verify signed messages you receive from us.
 
-.. _PGP key: https://pgp.mit.edu/pks/lookup?op=vindex&search=0xFEEF9FC2DD21D271
+__ https://pgp.mit.edu/pks/lookup?op=vindex&search=0xFEEF9FC2DD21D271
 
 ::
 
@@ -81,13 +81,9 @@ You may use this `PGP key`_ to securely communicate with us and to verify signed
     =LjIC
     -----END PGP PUBLIC KEY BLOCK-----
 
-.. _security-issue-archive:
-
 Security issue archive
 ----------------------
 
-.. _security-2.3.0:
-
 Release 2.3.0
 ~~~~~~~~~~~~~
 

docs/webhooks.rst

@@ -17,20 +17,18 @@ dashboard, under **Integrations**. You can select any of these integrations to
 see the *integration detail page*. This page has additional configuration
 details and a list of HTTP exchanges that have taken place for the integration.
 
-.. _webhook-creation:
-
-Webhook creation
+Webhook Creation
 ----------------
 
-If you import a project using a :ref:`connected account <connect-account>`, a
-webhook will be set up automatically for your repository. However, if your
+If you import a project using a :ref:`connected account <getting_started:Sign Up and Connect an External Account>`,
+a webhook will be set up automatically for your repository. However, if your
 project was not imported through a connected account, you may need to
 manually configure a webhook for your project.
 
 To manually set up a webhook, click **Add integration** on your project's
 **Integrations** admin dashboard page and select the integration type you'd like
 to add. After you have added the integration, you'll see a URL for the
-integration on the :ref:`integration detail page <Webhook Integrations>`. Use this
+integration on the :ref:`integration detail page <webhooks:Webhook Integrations>`. Use this
 URL when setting up a new webhook with your provider -- these steps vary
 depending on the provider:
 
@@ -40,7 +38,7 @@ GitHub
 * Go to the **Settings** page for your project
 * Click **Webhooks** and then **Add webhook**
 * For **Payload URL**, use the URL of the integration on Read the Docs, found on
-  the :ref:`integration detail page <integration-detail>` page
+  the :ref:`integration detail page <webhooks:Webhook Integrations>` page
 * For **Content type**, both *application/json* and
   *application/x-www-form-urlencoded* work
 * Select **Just the push event**
@@ -54,7 +52,7 @@ Bitbucket
 * Go to the **Settings** page for your project
 * Click **Webhooks** and then **Add webhook**
 * For **URL**, use the URL of the integration on Read the Docs, found on the
-  :ref:`integration detail page <integration-detail>` page
+  :ref:`integration detail page <webhooks:Webhook Integrations>` page
 * Under **Triggers**, **Repository push** should be selected
 * Finish by clicking **Save**
 
@@ -64,7 +62,7 @@ GitLab
 * Go to the **Settings** page for your project
 * Click **Integrations**
 * For **URL**, use the URL of the integration on Read the Docs, found on the
-  :ref:`integration detail page <integration-detail>` page
+  :ref:`integration detail page <webhooks:Webhook Integrations>` page
 * Leave the default **Push events** selected and mark **Tag push events** also
 * Finish by clicking **Add Webhook**
 
@@ -74,7 +72,7 @@ Using the generic API integration
 For repositories that are not hosted with a supported provider, we also offer a
 generic API endpoint for triggering project builds. Similar to webhook
 integrations, this integration has a specific URL, found on the
-:ref:`integration detail page <integration-detail>`.
+:ref:`integration detail page <webhooks:Webhook Integrations>`.
 
 Token authentication is required to use the generic endpoint, you will find this
 token on the integration details page. The token should be passed in as a
@@ -93,7 +91,7 @@ branches
 
 token
     The integration token. You'll find this value on the
-    :ref:`integration detail page <integration-detail>` page.
+    :ref:`integration detail page <webhooks:Webhook Integrations>` page.
 
 For example, the cURL command to build the ``dev`` branch, using the token
 ``1234``, would be::