diff --git a/docs/.rstcheck.cfg b/docs/.rstcheck.cfg index df5cbe9c461..a59e4e1cc72 100644 --- a/docs/.rstcheck.cfg +++ b/docs/.rstcheck.cfg @@ -1,6 +1,6 @@ [rstcheck] ignore_directives=automodule,http:get,tabs,tab,prompt,http:patch,http:post,http:put,http:delete -ignore_roles=djangosetting,setting,featureflags,buildpyversions +ignore_roles=djangosetting,setting,featureflags,buildpyversions,external+rtd:doc,external,external+rtd ignore_substitutions=org_brand,com_brand,:smile:,:arrows_counterclockwise:,:heavy_plus_sign:,:tada:,:heart:,:pencil2: # This error needs to be ignored for now # See: https://github.com/myint/rstcheck/issues/19 diff --git a/docs/conf.py b/docs/conf.py index 6930a9b6870..a16e4a88cb3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -94,6 +94,9 @@ "rtd": ("https://docs.readthedocs.io/en/stable/", None), "rtd-dev": ("https://dev.readthedocs.io/en/latest/", None), } +# Redundant in Sphinx 5.0 +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes +intersphinx_disabled_reftypes = ["std:doc"] myst_enable_extensions = [ "deflist", ] diff --git a/docs/dev/contribute.rst b/docs/dev/contribute.rst index 16d63101e67..2b2509d90ea 100644 --- a/docs/dev/contribute.rst +++ b/docs/dev/contribute.rst @@ -87,15 +87,22 @@ projects, feel free to suggest the language on Transifex to start the process. .. _our projects on Transifex: https://www.transifex.com/projects/p/readthedocs/ -Triaging tickets ----------------- +Triaging issues +--------------- -Core team uses the following guidelines for issue triage on all of our projects. -These guidelines describe the issue lifecycle, and what is required at each step -of this lifecycle. +Everyone is encouraged to help improving, refining, verifying and prioritizing +issues on Github. The Read the Docs core :external+rtd:doc:`team` uses the following +guidelines for issue triage on all of our projects. These guidelines describe +the issue lifecycle step-by-step. .. note:: You will need Triage permission on the project in order to do this. - You can ask one of the members of the :doc:`team` to give you access. + You can ask one of the members of the :external+rtd:doc:`team` to give you access. + +.. tip:: Triaging helps identify problems and solutions and ultimately what + issues that are ready to be worked on. The core + :external+rtd:doc:`team` maintains a separate :doc:`/roadmap` + of prioritized issues - issues will only end up on that Roadmap after + they have been triaged. Initial triage ~~~~~~~~~~~~~~ diff --git a/docs/dev/roadmap.rst b/docs/dev/roadmap.rst index 5fc7ad76a69..a0607cffd88 100644 --- a/docs/dev/roadmap.rst +++ b/docs/dev/roadmap.rst @@ -12,7 +12,7 @@ Here, you will find several views into our roadmap: `Backlog `_ Work that we have planned for future sprints. Items with an assigned - timeframe have generally been discussed already by the team. Iteams that do + timeframe have generally been discussed already by the team. Items that do not yet have a timeframe assigned are not yet a priority of the core team. The focus of the core team will be on roadmap and sprint items. These items are @@ -20,11 +20,13 @@ promoted from our backlog before each sprint begins. .. _GitHub Roadmap: https://github.com/orgs/readthedocs/projects/156/views/1 -Triaging issues -~~~~~~~~~~~~~~~ +Triaging issues for the Roadmap +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Much of this is already covered in our guide on :doc:`contribute`, however to -summarize the important pieces: +Issues are triaged before they are worked on, involving a number of steps that +are covered in :doc:`/contribute`. Everyone can take part in helping to +triage issues, read more in :ref:`contribute:Triaging issues`. Additionally, issues are +considered for the Roadmap according to the following process: * New issues coming in will be triaged, but won't yet be considered part of our roadmap. diff --git a/docs/user/localization.rst b/docs/user/localization.rst index fe261b881c2..6c97c4caaec 100644 --- a/docs/user/localization.rst +++ b/docs/user/localization.rst @@ -51,7 +51,7 @@ It also gets included in the Read the Docs flyout: .. note:: The default language of a custom domain is determined by the language of the parent project that the domain was configured on. See - :doc:`custom_domains` for more information. + :doc:`/custom-domains` for more information. .. note:: You can include multiple translations in the same repository, with same ``conf.py`` and ``.rst`` files, diff --git a/docs/user/security.rst b/docs/user/security.rst index 1483f3c70ba..04741c36b61 100644 --- a/docs/user/security.rst +++ b/docs/user/security.rst @@ -69,7 +69,7 @@ The issue was found by the Read the Docs team. Version 5.14.0 ~~~~~~~~~~~~~~ -:ref:`changelog:Version 5.14.0` fixes an issue where that affected new code that removed multiple slashes in URL paths. The issue allowed the creation of hyperlinks that looked like they would go to a documentation domain on Read the Docs (either `*.readthedocs.io` or a [custom docs domain](https://docs.readthedocs.io/en/stable/custom_domains.html)) but instead went to a different domain. +:ref:`changelog:Version 5.14.0` fixes an issue where that affected new code that removed multiple slashes in URL paths. The issue allowed the creation of hyperlinks that looked like they would go to a documentation domain on Read the Docs (either `*.readthedocs.io` or a :doc:`custom docs domain `)) but instead went to a different domain. This issue was reported by Splunk after it was reported by a security audit. diff --git a/docs/user/single_version.rst b/docs/user/single_version.rst index d2581213fae..d5000085bc2 100644 --- a/docs/user/single_version.rst +++ b/docs/user/single_version.rst @@ -26,6 +26,6 @@ rather than redirecting to ``https://pip.readthedocs.io/en/latest/``. .. warning:: Documentation at ``///`` will stop working. - Remember to set :ref:`custom_domains:Canonical URLs` + Remember to set :doc:`canonical URLs ` to tell search engines like Google what to index, and to create :doc:`user-defined-redirects` to avoid broken incoming links.