From ca85a7c1f84af136d9a5340ba5eb9eec58e1604f Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 24 May 2018 14:29:45 -0500 Subject: [PATCH 1/2] Add autosectionlabel extension --- docs/conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index e8201d8622d..e45e058dedd 100644 --- a/docs/conf.py +++ b/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') From 4eff588de2e533fc763b26a0866efb793d0faaeb Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 24 May 2018 14:29:59 -0500 Subject: [PATCH 2/2] Use autosectionlabel extension --- docs/contribute.rst | 4 ++-- docs/design.rst | 2 +- docs/ethical-advertising.rst | 19 +++++++------------ docs/faq.rst | 5 ++--- docs/getting_started.rst | 10 +++------- docs/install.rst | 2 -- docs/issue-labels.rst | 2 -- docs/privacy-policy.rst | 9 ++------- docs/security.rst | 16 ++++++---------- docs/webhooks.rst | 20 +++++++++----------- 10 files changed, 32 insertions(+), 57 deletions(-) diff --git a/docs/contribute.rst b/docs/contribute.rst index fb8d0ac9881..793a62d27be 100644 --- a/docs/contribute.rst +++ b/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 `. After that is done we +:doc:`Installation Guide `. 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/design.rst b/docs/design.rst index bdbfea3bccf..814b90f10ec 100644 --- a/docs/design.rst +++ b/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 diff --git a/docs/ethical-advertising.rst b/docs/ethical-advertising.rst index f4c6dd7a095..c802623e65a 100644 --- a/docs/ethical-advertising.rst +++ b/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 `, +We also give 10% of our ad space to :ref:`community projects `, as our way of saying thanks to the open source community. -We talk a bit below about :ref:`our worldview on advertising `, +We talk a bit below about :ref:`our worldview on advertising `, 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 `_. -You can :ref:`opt out ` of having paid ads on your projects, +You can :ref:`opt out ` of having paid ads on your projects, or seeing paid ads if you want. -You will still see :ref:`community ads `, +You will still see :ref:`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 `_ 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 `_ by contributing to the project. * Moving to our `paid product `_ 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. - diff --git a/docs/faq.rst b/docs/faq.rst index 1c4a18edb9e..d21cf1039f0 100644 --- a/docs/faq.rst +++ b/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 --------------------------------------------------------- diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 0134080ec0d..c415b06b62a 100644 --- a/docs/getting_started.rst +++ b/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 -` for more information on this process. +configure a new webhook, or see :ref:`our steps for 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. diff --git a/docs/install.rst b/docs/install.rst index 0d7c9a73e72..70a5f5a7cc6 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -1,5 +1,3 @@ -.. _installing-read-the-docs: - Installation ============ diff --git a/docs/issue-labels.rst b/docs/issue-labels.rst index de214d90b88..e460439bd1b 100644 --- a/docs/issue-labels.rst +++ b/docs/issue-labels.rst @@ -1,5 +1,3 @@ -.. _issue-label-overview: - Overview of issue labels ======================== diff --git a/docs/privacy-policy.rst b/docs/privacy-policy.rst index 49f22ea68b3..ccb4b8d54fd 100644 --- a/docs/privacy-policy.rst +++ b/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: +:ref:`third parties `. Third party vendors ~~~~~~~~~~~~~~~~~~~ @@ -189,7 +186,7 @@ Analytics +++++++++ We go into detail on analytics in a -:ref:`separate section specific to analytics `. +:ref:`separate section specific to 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 ~~~~~~~~~~~~~~~~ diff --git a/docs/security.rst b/docs/security.rst index 3b901152001..ba24a3f5028 100644 --- a/docs/security.rst +++ b/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 **security@readthedocs.org** (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 **security@readthedocs.org** (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 `. - -.. _pgp-key: +* We will add the issue to our :ref:`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 ~~~~~~~~~~~~~ diff --git a/docs/webhooks.rst b/docs/webhooks.rst index 73961ec00c5..f707c85b2e7 100644 --- a/docs/webhooks.rst +++ b/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 `, a -webhook will be set up automatically for your repository. However, if your +If you import a project using a :ref:`connected 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 `. Use this +integration on the :ref:`integration detail page `. 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 ` page + the :ref:`integration detail page ` 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 ` page + :ref:`integration detail page ` 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 ` page + :ref:`integration detail page ` 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 `. +:ref:`integration detail page `. 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 ` page. + :ref:`integration detail page ` page. For example, the cURL command to build the ``dev`` branch, using the token ``1234``, would be::