From 04cfc481f1adc884b386c035ad5a8c58b3047cc5 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Fri, 16 Feb 2018 13:15:17 -0500 Subject: [PATCH 01/31] Add rstcheck dependency --- requirements/lint.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/requirements/lint.txt b/requirements/lint.txt index bc27efe8f70..b19a14e73dd 100644 --- a/requirements/lint.txt +++ b/requirements/lint.txt @@ -7,3 +7,4 @@ pylint prospector pylint-django pyflakes +rstcheck From 607e3e201498d557385fff29c9fa1a6b1b744c86 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Fri, 16 Feb 2018 13:16:45 -0500 Subject: [PATCH 02/31] Add rstcheck to tox dosc environment --- tox.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/tox.ini b/tox.ini index e4ea2e3add4..23cb048be7d 100644 --- a/tox.ini +++ b/tox.ini @@ -24,6 +24,7 @@ commands = description = build readthedocs documentation changedir = {toxinidir}/docs commands = + rstcheck `find **/*.rst | xargs` sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html [testenv:lint] From c231285aa4c2c78bb711648078cf3cd952dcf9c0 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Fri, 16 Feb 2018 13:34:30 -0500 Subject: [PATCH 03/31] Expand find command on tox --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 23cb048be7d..a80c9f04c5a 100644 --- a/tox.ini +++ b/tox.ini @@ -24,7 +24,7 @@ commands = description = build readthedocs documentation changedir = {toxinidir}/docs commands = - rstcheck `find **/*.rst | xargs` + bash -c 'rstcheck `find **/*.rst | xargs`' sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html [testenv:lint] From 73f0883b4fefaad53fe49e5a670da338842d2001 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Fri, 16 Feb 2018 14:39:38 -0500 Subject: [PATCH 04/31] Add rstcheck config file --- docs/.rstcheck.cfg | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 docs/.rstcheck.cfg diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg new file mode 100644 index 00000000000..731b573b61b --- /dev/null +++ b/docs/.rstcheck.cfg @@ -0,0 +1,3 @@ +[rstcheck] +ignore_directives=automodule,http:get +ignore_roles=djangosetting From eec8189a3615ff607280680f4c163523f4490c4a Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 21 Feb 2018 12:27:10 -0500 Subject: [PATCH 05/31] Move to separate env --- tox.ini | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index a80c9f04c5a..d6151ca7be0 100644 --- a/tox.ini +++ b/tox.ini @@ -24,9 +24,14 @@ commands = description = build readthedocs documentation changedir = {toxinidir}/docs commands = - bash -c 'rstcheck `find **/*.rst | xargs`' sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html +[testenv:docs-lint] +deps = -r{toxinidir}/requirements/lint.txt +changedir = {toxinidir}/docs +commands = + bash -c 'rstcheck `find **/*.rst | xargs`' + [testenv:lint] description = run linter (prospector) to ensure the source code corresponds to our coding standards deps = -r{toxinidir}/requirements/lint.txt From c1e79507d32d43c47a869b6f156319a0a01edcde Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 21 Feb 2018 13:22:18 -0500 Subject: [PATCH 06/31] Include new env to travis --- .travis.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.travis.yml b/.travis.yml index b08e0cc0319..c47b682fddc 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,6 +7,8 @@ matrix: include: - python: 2.7 env: TOXENV=docs + - python: 2.7 + env: TOXENV=docs-lint - python: 2.7 env: TOXENV=lint - python: 2.7 From bb4c86e8ce8d9f8b7c1443fbf9de63170dadeea8 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 21 Feb 2018 13:24:15 -0500 Subject: [PATCH 07/31] Add new requirements file --- requirements/docs-lint.txt | 2 ++ requirements/lint.txt | 1 - 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 requirements/docs-lint.txt diff --git a/requirements/docs-lint.txt b/requirements/docs-lint.txt new file mode 100644 index 00000000000..c29c47c942b --- /dev/null +++ b/requirements/docs-lint.txt @@ -0,0 +1,2 @@ +-r pip.txt +rstcheck diff --git a/requirements/lint.txt b/requirements/lint.txt index b19a14e73dd..bc27efe8f70 100644 --- a/requirements/lint.txt +++ b/requirements/lint.txt @@ -7,4 +7,3 @@ pylint prospector pylint-django pyflakes -rstcheck From 49e544b365845dce860b7b1de481877e7f5c8b83 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 21 Feb 2018 13:24:40 -0500 Subject: [PATCH 08/31] Use new requirements file --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index d6151ca7be0..b337fe58943 100644 --- a/tox.ini +++ b/tox.ini @@ -27,7 +27,7 @@ commands = sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html [testenv:docs-lint] -deps = -r{toxinidir}/requirements/lint.txt +deps = -r{toxinidir}/requirements/docs-lint.txt changedir = {toxinidir}/docs commands = bash -c 'rstcheck `find **/*.rst | xargs`' From b0775d3a1262726b2d4345b881a59a3f3d42aa68 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 21 Feb 2018 15:43:34 -0500 Subject: [PATCH 09/31] Dependencies --- requirements/docs-lint.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements/docs-lint.txt b/requirements/docs-lint.txt index c29c47c942b..de55d534c7e 100644 --- a/requirements/docs-lint.txt +++ b/requirements/docs-lint.txt @@ -1,2 +1,2 @@ --r pip.txt +Sphinx rstcheck From 2ee1311e6cfc6529ecc70a9ea94a8b7510a636c2 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 21 Feb 2018 15:46:46 -0500 Subject: [PATCH 10/31] Lint docs with python 3.6 --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index c47b682fddc..7c481d32dea 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,7 +7,7 @@ matrix: include: - python: 2.7 env: TOXENV=docs - - python: 2.7 + - python: 3.6 env: TOXENV=docs-lint - python: 2.7 env: TOXENV=lint From 318d3fa0a45a818989e15df8d423f3f0aa214446 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 24 Feb 2018 18:17:03 -0500 Subject: [PATCH 11/31] Check files with recursive option --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index b337fe58943..7dcfe979261 100644 --- a/tox.ini +++ b/tox.ini @@ -30,7 +30,7 @@ commands = deps = -r{toxinidir}/requirements/docs-lint.txt changedir = {toxinidir}/docs commands = - bash -c 'rstcheck `find **/*.rst | xargs`' + rstcheck -r . [testenv:lint] description = run linter (prospector) to ensure the source code corresponds to our coding standards From 3c35393bd07e5a15cd9ffaad6fa65e1f6e2f6ecd Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 14:23:12 -0500 Subject: [PATCH 12/31] Ignore false positive error --- docs/.rstcheck.cfg | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg index 731b573b61b..ff7dbecbf3f 100644 --- a/docs/.rstcheck.cfg +++ b/docs/.rstcheck.cfg @@ -1,3 +1,4 @@ [rstcheck] ignore_directives=automodule,http:get ignore_roles=djangosetting +ignore_messages=(Duplicate implicit target name: "") From ed91b6d29ed7a4f7e176321b04540f1c033a3d0c Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 14:30:50 -0500 Subject: [PATCH 13/31] Remove unused global ref --- docs/webhooks.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/webhooks.rst b/docs/webhooks.rst index 91ccdffd65d..73961ec00c5 100644 --- a/docs/webhooks.rst +++ b/docs/webhooks.rst @@ -9,8 +9,6 @@ receive a webhook notification, we determine if the change is related to an active version for your project, and if it is, a build is triggered for that version. -.. _integration-detail: - Webhook Integrations -------------------- @@ -32,7 +30,7 @@ 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: From 87e92e57ccd48b551e78de6a14893eeaf23538aa Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 14:58:21 -0500 Subject: [PATCH 14/31] Remove unused links --- docs/contribute.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/contribute.rst b/docs/contribute.rst index 20a8ee1acd6..fb8d0ac9881 100644 --- 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 From b1affec1108cad66e6eb6ffaa0319997e62cf3ef Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 14:58:42 -0500 Subject: [PATCH 15/31] Remove unused link --- docs/sponsors.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/sponsors.rst b/docs/sponsors.rst index 72fbd9d0b36..4e363ae0f8e 100644 --- a/docs/sponsors.rst +++ b/docs/sponsors.rst @@ -32,7 +32,6 @@ Past sponsors .. _Rackspace: http://www.rackspace.com/ .. _Mozilla: https://www.mozilla.org/en-US/ .. _Twilio: http://twilio.com/ -.. _Signal: http://signal.twilio.com/ Sponsorship Information From 5ed816ba57d8658743fe8e1ab3bde43766f18fda Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 15:02:22 -0500 Subject: [PATCH 16/31] Change links to rst --- docs/changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index e807f88cbf4..ac64760f2c6 100644 --- 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 `_ and `finer grained in the repo `_ - 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: From d153df35134cb49b81ea65e8af82ffb29cfaa74b Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 15:44:30 -0500 Subject: [PATCH 17/31] Remove unused link --- docs/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 684985a8de9..c84e7edaf49 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,7 +13,6 @@ The code is open source, and `available on GitHub`_. .. _Sphinx: http://sphinx.pocoo.org/ .. _reStructuredText: http://sphinx.pocoo.org/rest.html .. _CommonMark: http://commonmark.org/ -.. _Markdown: http://daringfireball.net/projects/markdown/syntax .. _Subversion: http://subversion.tigris.org/ .. _Bazaar: http://bazaar.canonical.com/ .. _Git: http://git-scm.com/ From 6d4a28a6d8e7009eae340f526654a2d498abab35 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 15:45:03 -0500 Subject: [PATCH 18/31] Remove unused links --- docs/i18n.rst | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/docs/i18n.rst b/docs/i18n.rst index 174d560fb33..cca997b8cad 100644 --- a/docs/i18n.rst +++ b/docs/i18n.rst @@ -1,5 +1,3 @@ -.. _i18n: - Internationalization ==================== @@ -258,9 +256,6 @@ The updated files can now be localized in a `PO editor `_ or crowd-sourced online translation tool. - -.. _i18n-compiling: - Compiling to MO ^^^^^^^^^^^^^^^ @@ -288,7 +283,7 @@ push -s`` (for English) or ``tx push -t `` (for non-English). To pull changes from Transifex, run ``tx pull -a``. Note that Transifex does not compile the translation files, so you have to do this after the pull (see -the :ref:`i18n-compiling` section). +the `Compiling to MO`_ section). For more information about the ``tx`` command, read the `Transifex client's help pages `_. From 7aafded93b049b058b55691c0a8daecff6f53260 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 15:45:34 -0500 Subject: [PATCH 19/31] Fix internal links --- docs/getting_started.rst | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/getting_started.rst b/docs/getting_started.rst index b226eb2f058..0134080ec0d 100644 --- 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 ~~~~~~~~~~~ From f5b61899b3e84b90d82c758b592a942eea0094ad Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 15:46:30 -0500 Subject: [PATCH 20/31] Fix internal links --- docs/dmca/index.rst | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/dmca/index.rst b/docs/dmca/index.rst index 40c962fd79d..36fe33b5953 100644 --- a/docs/dmca/index.rst +++ b/docs/dmca/index.rst @@ -4,18 +4,20 @@ 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 `_. +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 `_, 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 ---------------- @@ -23,13 +25,15 @@ 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 - `_. 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 - `_. 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 From 5a67cfa14779dd203762f3bdf0c6e49d66b512cb Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 15:47:01 -0500 Subject: [PATCH 21/31] Remove unused links --- docs/design.rst | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/design.rst b/docs/design.rst index 35db0fa1e00..1edda51fa20 100644 --- a/docs/design.rst +++ b/docs/design.rst @@ -1,5 +1,3 @@ -.. _designing-read-the-docs: - Designing Read the Docs ======================= @@ -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 - - - - From 65914a3689f3cbdebd6cd1e8d5f63ba8bd51efed Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 15:47:32 -0500 Subject: [PATCH 22/31] Remove unused link --- docs/canonical.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/canonical.rst b/docs/canonical.rst index ebc89a53c3d..d53baf600b4 100644 --- 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/ From 8683ab17405eebee209aa67b3cd673fc58e171c9 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 15:48:10 -0500 Subject: [PATCH 23/31] Fix internal links --- docs/automatic-redirects.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/automatic-redirects.rst b/docs/automatic-redirects.rst index f9c0447ec79..2e6e97dfbd7 100644 --- 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 --------------------- From ea76877f66aec66ed106f7bccb4ca0042b24b1b6 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 15:49:18 -0500 Subject: [PATCH 24/31] Fix internal link --- docs/business/index.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/business/index.rst b/docs/business/index.rst index 360ad769ae4..fb01b1e5ff8 100644 --- 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 `_. +.. 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 `_ 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 From ffa1179bae1faefd949748dbfa03884230d3b648 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 15:49:39 -0500 Subject: [PATCH 25/31] Ignore false positives --- docs/.rstcheck.cfg | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg index ff7dbecbf3f..72c06777226 100644 --- a/docs/.rstcheck.cfg +++ b/docs/.rstcheck.cfg @@ -1,4 +1,4 @@ [rstcheck] ignore_directives=automodule,http:get -ignore_roles=djangosetting -ignore_messages=(Duplicate implicit target name: "") +ignore_roles=djangosetting,setting +ignore_messages=(Duplicate implicit target name: ".*")|(Hyperlink target ".*" is not referenced) From 994be939eafef5997368218fdf2ab9fea44ed067 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Sat, 17 Mar 2018 16:01:24 -0500 Subject: [PATCH 26/31] Fix lists --- docs/custom_installs/local_rtd_vm.rst | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/docs/custom_installs/local_rtd_vm.rst b/docs/custom_installs/local_rtd_vm.rst index 3ae2a47cec0..42f14a2d220 100644 --- 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. From eac2029db236bef07726fd3921427931d796d5bc Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Mon, 19 Mar 2018 13:45:02 -0500 Subject: [PATCH 27/31] Use doc directive --- docs/faq.rst | 2 +- docs/localization.rst | 2 -- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/faq.rst b/docs/faq.rst index f618fec000e..1c4a18edb9e 100644 --- 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/localization.rst b/docs/localization.rst index 0b66a2ce069..a2bb7ecf61d 100644 --- a/docs/localization.rst +++ b/docs/localization.rst @@ -1,5 +1,3 @@ -.. _`Localization of Documentation`: - Localization of Documentation ============================= From 646c2f8bb47493463d30d6a371cb3fc6782d4bd7 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Fri, 23 Mar 2018 11:31:20 -0500 Subject: [PATCH 28/31] Fix reference --- docs/design.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design.rst b/docs/design.rst index 1edda51fa20..bdbfea3bccf 100644 --- a/docs/design.rst +++ b/docs/design.rst @@ -42,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. From 0e25f29086ac5688f48aecd1311f77cf549511c2 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 10 Apr 2018 23:23:13 -0500 Subject: [PATCH 29/31] Fix python dictionary on docs --- docs/design/theme-context.rst | 138 +++++++++++++++++----------------- 1 file changed, 70 insertions(+), 68 deletions(-) diff --git a/docs/design/theme-context.rst b/docs/design/theme-context.rst index 5c959a1e36a..9f1d0bd1f3f 100644 --- 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:: From d6292bcb4e2682646611ec0885542b75823cfa6a Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 22 May 2018 23:27:42 -0500 Subject: [PATCH 30/31] Add description to tox env --- tox.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/tox.ini b/tox.ini index 7dcfe979261..c082a6d923e 100644 --- a/tox.ini +++ b/tox.ini @@ -27,6 +27,7 @@ commands = sphinx-build -b html -d {envtmpdir}/doctrees . {envtmpdir}/html [testenv:docs-lint] +description = run linter (rstcheck) to ensure there aren't errors on our docs deps = -r{toxinidir}/requirements/docs-lint.txt changedir = {toxinidir}/docs commands = From 51f7c7cffc1c250f5d2a2a90de1e1980be01a1de Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 22 May 2018 23:43:04 -0500 Subject: [PATCH 31/31] Remove trailing comma --- docs/guides/build-notifications.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/build-notifications.rst b/docs/guides/build-notifications.rst index 6cd203be4be..08ed1b578ae 100644 --- a/docs/guides/build-notifications.rst +++ b/docs/guides/build-notifications.rst @@ -36,7 +36,7 @@ The project name, slug and its details for the build that failed will be sent as "build": { "id": 6321373, "success": false, - "date": "2017-02-15 20:35:54", + "date": "2017-02-15 20:35:54" } }