From d923270d33278ef74314c1fdf27f5be7d15c8ecc Mon Sep 17 00:00:00 2001 From: Richard Brooksby Date: Thu, 16 Feb 2023 18:10:33 +0000 Subject: [PATCH 1/7] Fixing ``make clean`` . --- mps/manual/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mps/manual/Makefile b/mps/manual/Makefile index 71adef25ae0..8ad7787c3dc 100644 --- a/mps/manual/Makefile +++ b/mps/manual/Makefile @@ -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) From 062041f7ce8b002d10a85f24f93e27d985a4a9ff Mon Sep 17 00:00:00 2001 From: Richard Brooksby Date: Thu, 16 Feb 2023 21:48:38 +0000 Subject: [PATCH 2/7] Moving the anchor for guide-build to immediately before the heading in build.txt so that sphinx defines it. works around . --- mps/manual/build.txt | 3 ++- mps/manual/source/guide/build.rst | 2 -- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/mps/manual/build.txt b/mps/manual/build.txt index 46e62bdca49..5a74e070906 100644 --- a/mps/manual/build.txt +++ b/mps/manual/build.txt @@ -1,6 +1,7 @@ .. mode: -*- rst -*- -=============================== +.. _guide-build: + Building the Memory Pool System =============================== diff --git a/mps/manual/source/guide/build.rst b/mps/manual/source/guide/build.rst index 9c97e9a3bb3..ccc3d90b088 100644 --- a/mps/manual/source/guide/build.rst +++ b/mps/manual/source/guide/build.rst @@ -5,6 +5,4 @@ single: compiling single: installing -.. _guide-build: - .. include:: ../../build.txt From df6a03cbbe4eae6121ad8a7e31f86af6e822ca67 Mon Sep 17 00:00:00 2001 From: Richard Brooksby Date: Sun, 19 Feb 2023 12:09:18 +0000 Subject: [PATCH 3/7] Adding note to manual/build.txt to prevent manual breakage. --- mps/manual/build.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/mps/manual/build.txt b/mps/manual/build.txt index 5a74e070906..16b26b38242 100644 --- a/mps/manual/build.txt +++ b/mps/manual/build.txt @@ -1,5 +1,11 @@ .. 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 . + .. _guide-build: Building the Memory Pool System From 2f9ff7d0df8ee73c597b95351bbf649db00c36ba Mon Sep 17 00:00:00 2001 From: Richard Brooksby Date: Wed, 22 Feb 2023 22:53:17 +0000 Subject: [PATCH 4/7] Make sphinx fail on warnings so that ci detects problems with the manual early . fixing warnings. undoing mystery merge . --- mps/.readthedocs.yaml | 1 + mps/design/object-debug.txt | 4 ---- mps/manual/Makefile | 2 +- mps/manual/source/extensions/mps/__init__.py | 7 ++++--- mps/manual/source/topic/scanning.rst | 2 +- 5 files changed, 7 insertions(+), 9 deletions(-) diff --git a/mps/.readthedocs.yaml b/mps/.readthedocs.yaml index 0a269c4fb07..8ae20323cd0 100644 --- a/mps/.readthedocs.yaml +++ b/mps/.readthedocs.yaml @@ -26,6 +26,7 @@ python: sphinx: configuration: manual/source/conf.py + fail_on_warning: true # A. REFERENCES # diff --git a/mps/design/object-debug.txt b/mps/design/object-debug.txt index 3ecea76544e..66f1ba958f3 100644 --- a/mps/design/object-debug.txt +++ b/mps/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 diff --git a/mps/manual/Makefile b/mps/manual/Makefile index 8ad7787c3dc..25615b85712 100644 --- a/mps/manual/Makefile +++ b/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 = . diff --git a/mps/manual/source/extensions/mps/__init__.py b/mps/manual/source/extensions/mps/__init__.py index 9fa0c43f04c..6c4900b86d6 100644 --- a/mps/manual/source/extensions/mps/__init__.py +++ b/mps/manual/source/extensions/mps/__init__.py @@ -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' diff --git a/mps/manual/source/topic/scanning.rst b/mps/manual/source/topic/scanning.rst index dd481947c41..b8809941850 100644 --- a/mps/manual/source/topic/scanning.rst +++ b/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. From f3aa9326d7f800bfc3d96f55e3daa19e60157a35 Mon Sep 17 00:00:00 2001 From: Richard Brooksby Date: Thu, 23 Feb 2023 10:59:07 +0000 Subject: [PATCH 5/7] Fixing url reference to sphinx documentation. --- mps/manual/source/extensions/mps/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mps/manual/source/extensions/mps/__init__.py b/mps/manual/source/extensions/mps/__init__.py index 6c4900b86d6..7c48b78127a 100644 --- a/mps/manual/source/extensions/mps/__init__.py +++ b/mps/manual/source/extensions/mps/__init__.py @@ -1,6 +1,6 @@ ''' Sphinx extensions for the MPS documentation. -See +See ''' from collections import defaultdict From 310a8a2a8e836d7e53b11841c3ac8ce8a1bde70e Mon Sep 17 00:00:00 2001 From: Richard Brooksby Date: Thu, 23 Feb 2023 15:37:30 +0000 Subject: [PATCH 6/7] Marking missing tags with todo comments so they're more likely to get fixed . --- mps/design/object-debug.txt | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/mps/design/object-debug.txt b/mps/design/object-debug.txt index 66f1ba958f3..29ecc496fec 100644 --- a/mps/design/object-debug.txt +++ b/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,6 +343,7 @@ 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)`` From 75acd47f9aadd0a69c9d433947d74a6552919109 Mon Sep 17 00:00:00 2001 From: Richard Brooksby Date: Thu, 23 Feb 2023 17:24:20 +0000 Subject: [PATCH 7/7] Adding an introductory warning to the design section. adding leader comment with reference to design and notes. --- mps/manual/source/design/index.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/mps/manual/source/design/index.rst b/mps/manual/source/design/index.rst index 7e568a89d79..8b074f61e93 100644 --- a/mps/manual/source/design/index.rst +++ b/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: