sphinx: fix warnings

In particular:
- warning about extlinks in sphinx 6.0
- warning about duplicate targets for weigh, and wiki
- warning about glossary not included in toctree
- underline warning in ordering constructors

Author: doyougnu

conf.py

@@ -54,7 +54,10 @@
 todo_link_only     = False
 autosectionlabel_prefix_document = True
 
-extlinks = {'userGuide': ('https://downloads.haskell.org/~ghc/9.2.4/docs/html/users_guide/%s', '')}
+## global links in the book that share a prefix that we've named.
+extlinks = {'userGuide': ('https://downloads.haskell.org/~ghc/9.2.4/docs/html/users_guide/%s', '%s'),
+            'ghcWiki': ('https://gitlab.haskell.org/ghc/ghc/wikis/%s', '#%s'),
+            }
 
 # prolog for colored text
 rst_prolog = """

contents.rst

@@ -21,6 +21,11 @@ Haskell Optimization Handbook
 Indices and tables
 ==================
 
+.. toctree::
+   :hidden:
+
+   src/glossary
+
 * :ref:`genindex`
 * :ref:`search`
 * :ref:`glossary`

src/Measurement_Observation/Heap_Ghc/eventlog.rst

@@ -8,17 +8,16 @@
 Eventlog
 ========
 
-`Eventlog
-<https://downloads.haskell.org/ghc/latest/docs/users_guide/runtime_control.html#rts-eventlog>`_
-is a GHC runtime system feature that logs events at runtime of a compiled
-program. It provides runtime information on the heap, the garbage collector, the
-scheduler, and arbitrary events that a user inserts into their own code.
-Eventlog is a versatile profiling tool, and should be one of the first tools in
-the profiling toolbox you reach for. Use eventlog when you are just beginning to
-diagnose the problem and are gathering data. Specifically when you want to
-inspect the heap or some other subsystem, such as the garbage collector. This
-chapter walks through using eventlog to inspect a small program that suffers
-from :ref:`Excessive Pointer Chasing`. By the end of the chapter you should
+:userGuide:`Eventlog <runtime_control.html#rts-eventlog>` is a GHC runtime
+system feature that logs events at runtime of a compiled program. It provides
+runtime information on the heap, the garbage collector, the scheduler, and
+arbitrary events that a user inserts into their own code. Eventlog is a
+versatile profiling tool, and should be one of the first tools in the profiling
+toolbox you reach for. Use eventlog when you are just beginning to diagnose the
+problem and are gathering data. Specifically when you want to inspect the heap
+or some other subsystem, such as the garbage collector. This chapter walks
+through using eventlog to inspect a small program that suffers from
+:ref:`Excessive Pointer Chasing <canonical-pointer-chasing>`. By the end of the chapter you should
 understand:
 
 #. What information can you retrieve by using eventlog.
@@ -56,15 +55,15 @@ define and track their own events using the base functions `traceEvent
 When should I use Eventlog
 --------------------------
 
-Eventlog is most useful when you need to :ref:`Characterize the Problem`. It
-yields runtime information on the specific subsystems the program relies on.
-Thus, it allows you to drill down into the behavior of the garbage collector,
-the scheduler, the heap and so. For example, using the flag ``+RTS -lg`` you can
-collect the ``CONC_MARK_BEGIN`` and ``CONC_MARK_END`` events which log the
-beginning and end of the concurrent garbage collectors marking phase. Similarly,
-you can collect ``MEM_RETURN`` which provides information about the current
-allocation of megablocks, attempts to return them to the operating system, and
-heap fragmentation.
+Eventlog is most useful when you need to :ref:`Characterize the Problem
+<characterize-the-problem>`. It yields runtime information on the specific
+subsystems the program relies on. Thus, it allows you to drill down into the
+behavior of the garbage collector, the scheduler, the heap and so. For example,
+using the flag ``+RTS -lg`` you can collect the ``CONC_MARK_BEGIN`` and
+``CONC_MARK_END`` events which log the beginning and end of the concurrent
+garbage collectors marking phase. Similarly, you can collect ``MEM_RETURN``
+which provides information about the current allocation of megablocks, attempts
+to return them to the operating system, and heap fragmentation.
 
 
 The Running Example

src/Measurement_Observation/Measurement_Libs/weigh.rst

@@ -1,4 +1,4 @@
-.. _Weigh:
+.. _Weigh Chapter:
 
 `Weigh`
 =======
@@ -175,8 +175,8 @@ output from weigh:
    Foo2              336    0
    Benchmark weigh: FINISH
 
- Notice that built in types such as ``()`` and ``True`` do not do any
-allocation. This is because these types are `wired-in
+Notice that built in types such as ``()`` and ``True`` do not do any allocation.
+This is because these types are `wired-in
 <https://gitlab.haskell.org/ghc/ghc/-/wikis/commentary/compiler/wired-in>`_ to
 GHC, which means that there is a single shared ``()`` in GHC, so our call to
 ``value "()" ()`` performs no allocation because it references the shared

src/Measurement_Observation/the_recipe.rst

@@ -46,6 +46,7 @@ definition we present them here instead of in the :ref:`glossary`:
    program which constitutes *normal operation*. This is how you know you have a
    problem.
 
+.. _characterize-the-problem:
 
 Characterize the Problem
 ------------------------

src/Optimizations/Code_Changes/ordering_constructors.rst

@@ -1,6 +1,6 @@
 .. _Ordering Constructors Chapter:
 
 :lightgrey:`Ordering Data Constructors`
-======================================
+=======================================
 
 `TODO <https://github.com/input-output-hk/hs-opt-handbook.github.io/issues/47>`_

src/Optimizations/GHC_opt/lambda_lifting.rst

@@ -83,9 +83,7 @@ hypothetical heap allocations a function will induce. GHC lists heuristics for
 when *not* to lambda lift in `Note [When to lift]
 <https://gitlab.haskell.org/ghc/ghc/-/blob/master/compiler/GHC/Stg/Lift/Analysis.hs#L46>`_
 , we repeat the basic ideas here. See :cite:t:`selectiveLambdaLifting`, and the
-`lambda lifting wiki
-<https://gitlab.haskell.org/ghc/ghc/-/wikis/late-lam-lift>`_ entry for more
-details.
+:ghcWiki:`lambda lifting wiki <late-lam-lift>` entry for more details.
 
 GHC does not lambda lift:
 

src/Optimizations/GHC_tech/ghc_flags.rst

@@ -1,4 +1,4 @@
-.. GHC Flags
+.. _GHC Flags:
 
 :lightgrey:`GHC Flags`
 ======================

src/glossary.rst

@@ -139,9 +139,9 @@ Glossary
       Every heap allocated object in the runtime system keeps an information
       table that stores data such as: the object type (function, data
       constructor, thunk etc.) before the payload of the object. This is called
-      the info table. See :cite:t:`pointerTaggingLaziness` and the `wiki
-      <https://gitlab.haskell.org/ghc/ghc/-/wikis/commentary/rts/storage/heap-objects#info-tables>`_
-      for more details.
+      the info table. See :cite:t:`pointerTaggingLaziness` and the
+      :ghcWiki:`wiki <commentary/rts/storage/heap-objects#info-tables>` for more
+      details.
 
    Join Point :  Optimization
 
@@ -167,15 +167,15 @@ Glossary
       avoid these problems and are particularly relevant for Stream
       :term:`Fusion` performance.
 
-    Known Function
+   Known Function
 
-      A known function is a function in the STG machine of which GHC statically
-      knows the :term:`Entry Code` pointer and the :term:`Arity` of. This means
-      that the function binding site is statically visible, that is, the
-      function is :term:`Top-Level`, or the function is bound by an enclosing
-      ``let``. With this information the STG machine can use a faster function
-      application procedure because the function pointer does not need to be
-      scrutinized. See also :term:`Unknown Function`.
+     A known function is a function in the STG machine of which GHC statically
+     knows the :term:`Entry Code` pointer and the :term:`Arity` of. This means
+     that the function binding site is statically visible, that is, the
+     function is :term:`Top-Level`, or the function is bound by an enclosing
+     ``let``. With this information the STG machine can use a faster function
+     application procedure because the function pointer does not need to be
+     scrutinized. See also :term:`Unknown Function`.
 
 
    Levity Polymorphism
@@ -205,9 +205,8 @@ Glossary
       closure that represents a function applied to *too few* arguments. PAPs
       should never be entered, and are only applied using the generic apply
       functions in the STG machine. See the file ``rts/Apply.cmm`` in GHC or the
-      `heap object
-      <https://gitlab.haskell.org/ghc/ghc/-/wikis/commentary/rts/storage/heap-objects>`_
-      wiki page for more.
+      :ghcWiki:`heap object <commentary/rts/storage/heap-objects>` wiki page for
+      more.
 
    Pinned : Memory