Merging branch/2023-02-16/manual-xrefs for github pull request <https://github.com/ravenbrook/mps/pull/159>.

GitHub-reference: https://github.com/Ravenbrook/mps/issues/159

mps/.readthedocs.yaml

@@ -26,6 +26,7 @@ python:
 
 sphinx:
   configuration: manual/source/conf.py
+  fail_on_warning: true
 
 # A. REFERENCES
 #

mps/design/object-debug.txt

@@ -41,7 +41,8 @@ Requirements
 
 _`.req.fencepost`: Try to detect overwrites and underwrites of
 allocated blocks by adding fenceposts (source req.product.??? VC++,
-req.epcore.fun.debug.support).
+req.epcore.fun.debug.support).  [TODO: Locate the relevant product
+requirement.  RB 2023-02-23]
 
 _`.req.fencepost.size`: The fenceposts should be at least 4 bytes on
 either side or 8 bytes if on one side only, with an adjustable content
@@ -61,6 +62,7 @@ separate debugging variety/mode (source req.epcore.fun.debug.support).
 _`.req.tag`: There should be a way to store at least a word of user
 data (a "tag", borrowing the SW term) with every object in debugging
 mode, to be used in memory dumps (source req.product.??? VC++).
+[TODO: Locate the relevant product requirement.  RB 2023-02-23]
 
 _`.req.tag.walk`: The walking function (as required by `.req.walk`_)
 should have access to this data (source req.epcore.fun.debug.support).
@@ -341,16 +343,13 @@ fenceposts around an object. The ``NULL`` method checks tails.
 
 _`.interface.tags.alloc`: Two functions to extend the existing
 ``mps_alloc()`` (request.???.??? proposes to remove the varargs)
+[TODO: Locate the relevant Harlequin request.  RB 2023-02-23]
 
 ``typedef void (*mps_objects_step_t)(mps_addr_t addr, size_t size, mps_fmt_t format, mps_pool_t pool, void *tag_data, void *p)``
 
 _`.interface.tags.walker.type`: Type of walker function for
 ``mps_pool_walk()`` and ``mps_arena_walk()``.
 
-``void mps_pool_walk(mps_arena_t arena, mps_pool_t pool, mps_objects_step_t step, void *p)``
-
-``void mps_arena_walk(mps_arena_t arena, mps_objects_step_t step, void *p)``
-
 _`.interface.tags.walker`: Functions to walk all the allocated
 objects in an arena (only client pools in this case),
 ``format`` and ``tag_data`` can be ``NULL`` (``tag_data`` really wants

mps/manual/Makefile

@@ -6,7 +6,7 @@
 
 # You can set these variables from the command line.
 PYTHON        = python3
-SPHINXOPTS    =
+SPHINXOPTS    = -T -W --keep-going
 SPHINXBUILD   = tool/bin/sphinx-build
 PAPER         =
 BUILDDIR      = .
@@ -44,7 +44,7 @@ help:
 	@echo "  tools      to install a local copy of the Python tools using virtualenv"
 
 clean:
-	-rm -rf $(BUILDDIR)/{changes,devhelp,dirhtml,doctest,doctrees,epub,html,htmlhelp,json,latex,linkcheck,locale,man,pickle,qthelp,singlehtml,texinfo,text}
+	-for dir in changes devhelp dirhtml doctest doctrees epub html htmlhelp json latex linkcheck locale man pickle qthelp singlehtml texinfo text; do rm -rf $(BUILDDIR)/$$dir; done
 	-find $(BUILDDIR)/source/design -name '*.rst' ! -name 'index.rst' ! -name 'old.rst' -exec rm -f '{}' ';'
 
 html: $(SPHINXBUILD)

mps/manual/build.txt

@@ -1,6 +1,13 @@
 .. mode: -*- rst -*-
 
-===============================
+.. NOTE: This file is a chapter of the MPS manual, and so uses some
+   Sphinx markup.  It does double-duty as plain text / GitHub rendered
+   instructions for bootstrapping the manual.  When editing, be
+   careful to ensure that the manual builds correctly.  See GitHub
+   issue #158 <https://github.com/Ravenbrook/mps/issues/158>.
+
+.. _guide-build:
+
 Building the Memory Pool System
 ===============================
 

mps/manual/source/design/index.rst

@@ -1,8 +1,25 @@
+.. manual/source/design/index.rst -- index of designs in MPS manual
+
+.. See design.mps.doc.impl.manual.design.
+
+.. NOTE: If there is a discrepancy between the design directory and
+   this list then Sphinx will produce a warning.
+
+.. TODO: Generate this list from the design directory rather than rely
+   in keeping it updated.
+
 .. _design:
 
 Design
 ******
 
+.. warning::
+
+    The documents in this section are included from the working
+    designs in the MPS source tree.  They are intended for developers
+    of the MPS.  They vary a great deal in detail depending on the
+    risks associated with the things they describe.
+
 .. toctree::
     :numbered:
 

mps/manual/source/extensions/mps/__init__.py

@@ -1,6 +1,6 @@
 '''
 Sphinx extensions for the MPS documentation.
-See <http://sphinx-doc.org/extensions.html>
+See <https://www.sphinx-doc.org/en/master/development/index.html>
 '''
 
 from collections import defaultdict
@@ -56,12 +56,13 @@ def add_to_app(cls, app):
         else:
             return
         if hasattr(cls, 'node_class') and hasattr(cls, 'visit'):
-            app.add_node(cls.node_class, html=cls.visit, latex=cls.visit,
+            app.add_node(cls.node_class, override=True,
+                         html=cls.visit, latex=cls.visit,
                          text=cls.visit, man=cls.visit)
         if hasattr(cls, 'domain'):
-            app.add_directive_to_domain(cls.domain, name, cls)
+            app.add_directive_to_domain(cls.domain, name, cls, override=True)
         else:
-            app.add_directive(name, cls)
+            app.add_directive(name, cls, override=True)
 
 class MpsPrefixDirective(MpsDirective):
     domain = 'mps'

mps/manual/source/guide/build.rst

@@ -5,6 +5,4 @@
    single: compiling
    single: installing
 
-.. _guide-build:
-
 .. include:: ../../build.txt

mps/manual/source/topic/scanning.rst

@@ -557,7 +557,7 @@ the scanners, found in ``scan.c`` in the MPS source code.
     .. note::
 
         The reason that :c:data:`base` and :c:data:`limit` have type
-        :c:type:`void *` and not :c:type:`mps_addr_t` is that the
+        ``void *`` and not :c:type:`mps_addr_t` is that the
         latter is used only for :term:`addresses` managed by the MPS,
         but :c:type:`mps_area_scan_t` may also be used to scan
         :term:`roots` that are not managed by the MPS.