Fix docs warnings and broken links (#11723)

* Fix docs warnings and broken links

Also enables checking for this in the future.

* Fix dev docs too

* Update .readthedocs.yml

Co-authored-by: Santos Gallegos <[email protected]>

---------

Co-authored-by: Santos Gallegos <[email protected]>

.readthedocs.yml

@@ -6,9 +6,7 @@ formats:
 
 sphinx:
   configuration: docs/conf.py
-
-  # Disabled due to temporary issue with Django docs
-  fail_on_warning: false
+  fail_on_warning: true
 
 python:
   install:

docs/dev/design/yaml-file.rst

@@ -157,4 +157,3 @@ Footnotes
 .. [#project-description] https://github.com/readthedocs/readthedocs.org/issues/3689
 .. [#yaml-spec] https://yaml.org/spec/1.2/spec.html
 .. [#specversioning] https://github.com/readthedocs/readthedocs.org/issues/3806
-.. [#one-checkout] https://github.com/readthedocs/readthedocs.org/issues/1375

docs/dev/install.rst

@@ -243,7 +243,7 @@ using your GitHub, Bitbucket, or GitLab credentials
 and this makes the process of importing repositories easier.
 
 However, because these services will not be able to connect back to your local development instance,
-:doc:`incoming webhooks <rtd:integrations>` will not function correctly.
+:doc:`incoming webhooks <rtd:reference/git-integration>` will not function correctly.
 For some services, the webhooks will fail to be added when the repository is imported.
 For others, the webhook will simply fail to connect when there are new commits to the repository.
 

docs/user/flyout-menu.rst

@@ -12,15 +12,15 @@ without having to have the documentation theme integrate it directly.
    The flyout menu is a default implementation that works for every site.
    You can access the full data used to construct the flyout,
    and use that to integrate the data directly into your documentation theme for a nicer user experience.
-   See the :ref:`Custom event integration` for more information.
+   See the :ref:`flyout-menu:Custom event integration` for more information.
 
 Addons flyout menu
 ------------------
 
 The :doc:`addons` flyout provides a place for a number of Read the Docs features:
 
 * A :doc:`version switcher </versions>` that shows users all of the active versions they have access to.
-* A :doc:`translation switcher </internationalization>` that shows all the documentation languages provided.
+* A :doc:`translation switcher </localization>` that shows all the documentation languages provided.
 * A list of :doc:`offline formats </downloadable-documentation>` for the current version, including HTML & PDF downloads.
 * Links to the Read the Docs dashboard for the project.
 * A search bar that gives users access to the :doc:`/server-side-search/index` of the current version.
@@ -57,7 +57,7 @@ Custom event integration
 
 Read the Docs Addons exposes all the data used to construct the flyout menu via a JavaScript ``CustomEvent``.
 If you'd like to integrate the data,
-you can use the :ref:`mkdocs:Integrate the Read the Docs version menu into your site navigation` example as a starting point.
+you can use the :ref:`intro/mkdocs:Integrate the Read the Docs version menu into your site navigation` example as a starting point.
 
 .. warning::
    We have not formally documented the API response returned from the Addons API,

docs/user/pull-requests.rst

@@ -28,7 +28,7 @@ Pull request notifications
     A pull request notifications is shown at the top of preview pages,
     which let readers know they aren't viewing an active version of the project.
 
-:doc:`DocDiff </doc-diff>``
+:doc:`DocDiff </doc-diff>`
     DocDiff shows proposed changes by visually highlighting the differences between the current pull request and the latest version of the project's documentation.
 
     Press ``d`` to toggle between DocDiff and normal pull request preview.