docs: use ref-links for internal references

Ref-link have two benefits over generic links:

1. They produce the right result for non-HTML outputs
2. They get validated at build-time

So let's use them for internal references instead.

Reviewed-by: Eric Engestrom <eric@engestrom.ch>
Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/5671>

docs/dispatch.rst

@@ -5,7 +5,7 @@ Several factors combine to make efficient dispatch of OpenGL functions
 fairly complicated. This document attempts to explain some of the issues
 and introduce the reader to Mesa's implementation. Readers already
 familiar with the issues around GL dispatch can safely skip ahead to the
-`overview of Mesa's implementation <#overview>`__.
+:ref:`overview of Mesa's implementation <overview>`.
 
 1. Complexity of GL Dispatch
 ----------------------------
@@ -162,7 +162,7 @@ dispatch routines are very short, and it is trivial to create optimal
 assembly language versions. The amount of optimization provided by using
 assembly stubs varies from platform to platform and application to
 application. However, by using the assembly stubs, many platforms can
-use an additional space optimization (see `below <#fixedsize>`__).
+use an additional space optimization (see :ref:`below <fixedsize>`).
 
 The biggest hurdle to creating assembly stubs is handling the various
 ways that the dispatch table pointer can be accessed. There are four

docs/meson.rst

@@ -290,7 +290,7 @@ Then configure meson:
 
    meson builddir/ --cross-file cross-llvm.ini
 
-See the `Cross Compilation <#cross-compilation>`__ section for more
+See the :ref:`Cross Compilation <cross-compilation>` section for more
 information.
 
 On windows (and in other cases), using llvm-config or cmake may be

docs/repository.rst

@@ -7,8 +7,8 @@ system.
 The master git repository is hosted on
 `freedesktop.org <https://www.freedesktop.org>`__.
 
-You may access the repository either as an `anonymous
+You may access the repository either as an :ref:`anonymous
-user <#anonymous>`__ (read-only) or as a `developer <#developer>`__
+user <anonymous>` (read-only) or as a :ref:`developer <developer>`
 (read/write).
 
 You may also `browse the main Mesa git

docs/submittingpatches.rst

@@ -14,11 +14,11 @@ Basic guidelines
    components.
 -  Patches should never introduce build breaks and should be bisectable
    (see ``git bisect``.)
--  Patches should be properly `formatted <#formatting>`__.
+-  Patches should be properly :ref:`formatted <formatting>`.
--  Patches should be sufficiently `tested <#testing>`__ before
+-  Patches should be sufficiently :ref:`tested <testing>` before
    submitting.
--  Patches should be `submitted <#submit>`__ via a merge request for
+-  Patches should be :ref:`submitted <submit>` via a merge request for
-   `review <#reviewing>`__.
+   :ref:`review <reviewing>`.
 
 .. _formatting:
 
@@ -64,7 +64,7 @@ Patch formatting
 
    **Do not use the ``Fixes:`` tag for this!** Mesa already uses
    ``Fixes:`` for something else.
-   See `below <#fixes>`__.
+   See :ref:`below <fixes>`.
 
 -  If there have been several revisions to a patch during the review
    process, they should be noted such as in this example:
@@ -126,7 +126,7 @@ The stable tag
 If you want a commit to be applied to a stable branch, you should add an
 appropriate note to the commit message.
 
-Using a ``Fixes:`` tag as described in `Patch formatting <#formatting>`__
+Using a ``Fixes:`` tag as described in :ref:`Patch formatting <formatting>`
 is the preferred way to nominate a commit that should be backported.
 There are scripts that will figure out which releases to apply the patch
 to automatically, so you don't need to figure it out.
@@ -286,8 +286,8 @@ is not monitored actively and is a historical artifact.
 If you are not the author of the original patch, please Cc: them in your
 nomination request.
 
-The current patch status can be observed in the `staging
+The current patch status can be observed in the :ref:`staging
-branch <releasing.rst#stagingbranch>`__.
+branch <stagingbranch>`.
 
 .. _criteria:
 
@@ -301,7 +301,7 @@ mechanism described above. The following rules define which patches are
 accepted and which are not. The stable-release manager is also given
 broad discretion in rejecting patches that have been nominated.
 
--  Patch must conform with the `Basic guidelines <#guidelines>`__
+-  Patch must conform with the :ref:`Basic guidelines <guidelines>`
 -  Patch must have landed in master first. In case where the original
    patch is too large and/or otherwise contradicts with the rules set
    within, a backport is appropriate.
@@ -319,7 +319,7 @@ broad discretion in rejecting patches that have been nominated.
 
    .. note::
       An exception to this rule, are hardware-enabling "features". For
-      example, `backports <#backports>`__ of new code to support a
+      example, :ref:`backports <backports>` of new code to support a
       newly-developed hardware product can be accepted if they can be
       reasonably determined not to have effects on other hardware.