Fix missing manual cross-references to guide-build

.readthedocs.yaml

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

design/object-debug.txt

@@ -347,10 +347,6 @@ _`.interface.tags.alloc`: Two functions to extend the existing
 _`.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

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)

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
 ===============================
 

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'

manual/source/guide/build.rst

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

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.