From 06e499b2e47ffc2ff2ba222f1e95ae199a582283 Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Wed, 13 Mar 2024 15:38:13 -0400 Subject: [PATCH 01/10] Experimentally try Sphinx 7 --- Signed-off-by: Michael Ferguson --- doc/rst/conf.py | 1 + third-party/chpl-venv/chpldoc-requirements1.txt | 2 +- third-party/chpl-venv/chpldoc-requirements2.txt | 6 +++--- third-party/chpl-venv/chpldoc-requirements3.txt | 2 +- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/rst/conf.py b/doc/rst/conf.py index 8cc10b8ece73..f38d5d59a21e 100644 --- a/doc/rst/conf.py +++ b/doc/rst/conf.py @@ -33,6 +33,7 @@ # ones. extensions = [ 'sphinx.ext.todo', + 'sphinxcontrib.jquery', 'sphinxcontrib.chapeldomain', 'sphinx.ext.mathjax', 'util.disguise', diff --git a/third-party/chpl-venv/chpldoc-requirements1.txt b/third-party/chpl-venv/chpldoc-requirements1.txt index 22a0ad2f3141..265423f39f9c 100644 --- a/third-party/chpl-venv/chpldoc-requirements1.txt +++ b/third-party/chpl-venv/chpldoc-requirements1.txt @@ -1,2 +1,2 @@ # Split into 3 files to work around problems with CHPL_PIP_FROM_SOURCE -MarkupSafe==2.1.3 +MarkupSafe==2.1.5 diff --git a/third-party/chpl-venv/chpldoc-requirements2.txt b/third-party/chpl-venv/chpldoc-requirements2.txt index fd0683b50951..7583018d1fc6 100644 --- a/third-party/chpl-venv/chpldoc-requirements2.txt +++ b/third-party/chpl-venv/chpldoc-requirements2.txt @@ -1,7 +1,7 @@ # Split into 3 files to work around problems with CHPL_PIP_FROM_SOURCE Jinja2==3.1.3 Pygments==2.17.2 -Sphinx==5.3.0 -urllib3==2.1.0 -docutils==0.18 +Sphinx==7.2.6 +urllib3==2.2.1 +docutils==0.20.1 babel==2.14.0 diff --git a/third-party/chpl-venv/chpldoc-requirements3.txt b/third-party/chpl-venv/chpldoc-requirements3.txt index 3b6843c0c5dc..6bbcc3dfb14d 100644 --- a/third-party/chpl-venv/chpldoc-requirements3.txt +++ b/third-party/chpl-venv/chpldoc-requirements3.txt @@ -1,4 +1,4 @@ # Split into 3 files to work around problems with CHPL_PIP_FROM_SOURCE sphinx-rtd-theme==2.0.0 -sphinxcontrib-chapeldomain==0.0.31 +./sphinxcontrib-chapeldomain breathe==4.35.0 From e29d133c41b9fa2687af5792992e2521b053a5e9 Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Thu, 14 Mar 2024 17:46:23 -0400 Subject: [PATCH 02/10] Avoid generating include samples in breathe docs to avoid errors like .../compiler-internals/libraries.rst:11: WARNING: undefined label: 'LibraryFile_8h' --- Signed-off-by: Michael Ferguson --- doc/rst/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/rst/conf.py b/doc/rst/conf.py index f38d5d59a21e..6f3310c4222e 100644 --- a/doc/rst/conf.py +++ b/doc/rst/conf.py @@ -41,6 +41,9 @@ ] breathe_default_project = "dyno" +# don't generate #include suggestions in docs because +# it tries to link to the source code which we're not setup for +breathe_show_include = False nitpick_ignore_regex = [('cpp:identifier', r'llvm(:.*)?')] nitpick_ignore = [] From bd825581b359cdfbb8cb1c8e8f744cf9127a4c2f Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Thu, 14 Mar 2024 17:47:23 -0400 Subject: [PATCH 03/10] Add TraceElement since it's defined in a no-doc'd section --- Signed-off-by: Michael Ferguson --- doc/util/nitpick_ignore | 1 + frontend/doc/doxygen-pitfalls.txt | 1 + 2 files changed, 2 insertions(+) diff --git a/doc/util/nitpick_ignore b/doc/util/nitpick_ignore index a8afdae78dc9..6159608e0755 100644 --- a/doc/util/nitpick_ignore +++ b/doc/util/nitpick_ignore @@ -36,6 +36,7 @@ cpp:identifier AstList::const_iterator cpp:identifier size_t cpp:identifier detail cpp:identifier detail::PODUniqueString +cpp:identifier TraceElement cpp:identifier AstList::const_iterator::difference_type cpp:identifier uint64_t cpp:identifier uint32_t diff --git a/frontend/doc/doxygen-pitfalls.txt b/frontend/doc/doxygen-pitfalls.txt index a7dcf67b5bdc..5d84a704df3d 100644 --- a/frontend/doc/doxygen-pitfalls.txt +++ b/frontend/doc/doxygen-pitfalls.txt @@ -12,6 +12,7 @@ Doxygen will fail to resolve: - C++ standard library types (that are not builtin, e.g. `int64_t`) - Any `compiler/dyno` types that are generated by macros (for now) + - any dyno types that are defined in no-doc sections - C++11 "in-class member initializers" for enum fields Just add these types to `$CHPL_HOME/doc/util/nitpick_ignore`. From 20cb68216a4841f27c7d59c68cf2a6967802502a Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Thu, 14 Mar 2024 17:47:42 -0400 Subject: [PATCH 04/10] Turn nitpicking back on it was temporarily disabled in PR #24201 --- Signed-off-by: Michael Ferguson --- doc/Makefile.sphinx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile.sphinx b/doc/Makefile.sphinx index 523c6986a5fc..54f1eb1c638c 100644 --- a/doc/Makefile.sphinx +++ b/doc/Makefile.sphinx @@ -8,7 +8,7 @@ CHPLDEPS = $(shell $(CHPL_MAKE_PYTHON) $(CHPL_MAKE_HOME)/util/chplenv/chpl_home_ COPY_IF_DIFFERENT = $(CHPL_MAKE_PYTHON) $(CHPL_MAKE_HOME)/util/config/update-if-different --copy # You can set these variables from the command line. -SPHINXOPTS = -W --keep-going +SPHINXOPTS = -n -W --keep-going SPHINXBUILD = $(CHPL_MAKE_PYTHON) $(CHPLDEPS) sphinx-build PAPER = SOURCEDIR = rst From 116eb80e9fdc42f2cb81e93f491b9821b23eae27 Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Mon, 8 Apr 2024 15:45:12 -0400 Subject: [PATCH 05/10] Update chpldoc python version requirement to 3.9 --- Signed-off-by: Michael Ferguson --- doc/rst/usingchapel/prereqs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/rst/usingchapel/prereqs.rst b/doc/rst/usingchapel/prereqs.rst index bcf348ec2854..f6d7dc7bd461 100644 --- a/doc/rst/usingchapel/prereqs.rst +++ b/doc/rst/usingchapel/prereqs.rst @@ -46,7 +46,7 @@ for using Chapel: In addition, several optional components have additional requirements: - * Python 3.7 or newer is required if you want to use chpldoc, c2chapel, + * Python 3.9 or newer is required if you want to use chpldoc, c2chapel, or Chapel's test system. These additionally require ``python3-devel`` or the equivalent package; ``python3`` and ``pip3`` commands; and the ``venv`` Python package. From e25853775e60d99f89cb4fc8f90c67f3d3f3164f Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Mon, 8 Apr 2024 15:50:25 -0400 Subject: [PATCH 06/10] Use sphinxcontrib-chapeldomain-0.0.32 --- Signed-off-by: Michael Ferguson --- third-party/chpl-venv/chpldoc-requirements3.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/third-party/chpl-venv/chpldoc-requirements3.txt b/third-party/chpl-venv/chpldoc-requirements3.txt index 6bbcc3dfb14d..ed282d0237a3 100644 --- a/third-party/chpl-venv/chpldoc-requirements3.txt +++ b/third-party/chpl-venv/chpldoc-requirements3.txt @@ -1,4 +1,4 @@ # Split into 3 files to work around problems with CHPL_PIP_FROM_SOURCE sphinx-rtd-theme==2.0.0 -./sphinxcontrib-chapeldomain +sphinxcontrib-chapeldomain==0.0.32 breathe==4.35.0 From 29f4cb2a29be702e44f90cb5dd03c0697b7227e7 Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Tue, 9 Apr 2024 09:46:22 -0400 Subject: [PATCH 07/10] Fix docs build errors --- Signed-off-by: Michael Ferguson --- doc/util/nitpick_ignore | 2 ++ frontend/doc/base.rst | 4 ++++ 2 files changed, 6 insertions(+) diff --git a/doc/util/nitpick_ignore b/doc/util/nitpick_ignore index 6159608e0755..8d421e3fc018 100644 --- a/doc/util/nitpick_ignore +++ b/doc/util/nitpick_ignore @@ -47,6 +47,8 @@ cpp:identifier int32_t cpp:identifier int16_t cpp:identifier int8_t cpp:identifier va_list +cpp:identifier ErrorNote +cpp:identifier ErrorCodeSnippet # TODO: Expand macros before generating docs to remove these. cpp:identifier ErrorParseErr cpp:identifier ParamTag diff --git a/frontend/doc/base.rst b/frontend/doc/base.rst index 3db15fb0d24e..b6e720f43809 100644 --- a/frontend/doc/base.rst +++ b/frontend/doc/base.rst @@ -35,6 +35,10 @@ namespace. The entries may not be exhaustive. :members: :undoc-members: +.. doxygenclass:: chpl::CompatibilityWriter + :members: + :undoc-members: + .. doxygenclass:: chpl::ErrorBase :members: :undoc-members: From f8faae6a28f67f4d1cc3576d5e60120bb044a62f Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Tue, 9 Apr 2024 09:55:07 -0400 Subject: [PATCH 08/10] Fix more docs build errors --- Signed-off-by: Michael Ferguson --- doc/util/nitpick_ignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/util/nitpick_ignore b/doc/util/nitpick_ignore index 8d421e3fc018..a124253dd422 100644 --- a/doc/util/nitpick_ignore +++ b/doc/util/nitpick_ignore @@ -66,6 +66,8 @@ cpp:identifier ZERO cpp:identifier SYMBOL_ONLY cpp:identifier uast::asttags::NUM_AST_TAGS cpp:identifier uast::Function::DEFAULT_RETURN_INTENT +cpp:identifier VisibilitySymbols::REGULAR_SCOPE +cpp:identifier VIS_USE # Common symbols used as template typenames. cpp:identifier T cpp:identifier Deserializer From bd3487bf5fae855c68c9c69949340127301544cf Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Tue, 9 Apr 2024 11:05:58 -0400 Subject: [PATCH 09/10] Update projectVersion pattern matching The PREDIFF stopped working because newer Sphinx does not start the record with URL_ROOT. --- Signed-off-by: Michael Ferguson --- test/chpldoc/compflags/version/PREDIFF | 9 +++++++-- .../compflags/version/projectVersion.doc.catfiles | 1 - .../compflags/version/projectVersion.dotEnd.doc.good | 1 - .../version/projectVersion.invalidCharacter.doc.good | 1 - .../compflags/version/projectVersion.invalidTag.doc.good | 1 - .../compflags/version/projectVersion.lessDots.doc.good | 1 - .../version/projectVersion.missingNumbers.doc.good | 1 - 7 files changed, 7 insertions(+), 8 deletions(-) delete mode 100644 test/chpldoc/compflags/version/projectVersion.doc.catfiles diff --git a/test/chpldoc/compflags/version/PREDIFF b/test/chpldoc/compflags/version/PREDIFF index 3289677b53e6..b94807a12604 100755 --- a/test/chpldoc/compflags/version/PREDIFF +++ b/test/chpldoc/compflags/version/PREDIFF @@ -1,4 +1,9 @@ #!/usr/bin/env bash -sed -e '/^Running Sphinx v/,/URL_ROOT:/d;s/^ *//;/LANGUAGE:/,$d' $2 > $2.tmp -mv $2.tmp $2 +# if the docs build suceeded, replace the output to check with +# the generated VERSION line, trimmed to remove leading spaces +if [ -f docs/_static/documentation_options.js ] +then + grep VERSION docs/_static/documentation_options.js | sed 's/^ *//' > $2.tmp + mv $2.tmp $2 +fi diff --git a/test/chpldoc/compflags/version/projectVersion.doc.catfiles b/test/chpldoc/compflags/version/projectVersion.doc.catfiles deleted file mode 100644 index cb260d287acb..000000000000 --- a/test/chpldoc/compflags/version/projectVersion.doc.catfiles +++ /dev/null @@ -1 +0,0 @@ -docs/_static/documentation_options.js diff --git a/test/chpldoc/compflags/version/projectVersion.dotEnd.doc.good b/test/chpldoc/compflags/version/projectVersion.dotEnd.doc.good index f8800cb50e7e..26265b6ab325 100644 --- a/test/chpldoc/compflags/version/projectVersion.dotEnd.doc.good +++ b/test/chpldoc/compflags/version/projectVersion.dotEnd.doc.good @@ -1,2 +1 @@ error: Invalid version format: 21.0. due to: Cannot end with dot, can end with either number or tag -cat: docs/_static/documentation_options.js: No such file or directory diff --git a/test/chpldoc/compflags/version/projectVersion.invalidCharacter.doc.good b/test/chpldoc/compflags/version/projectVersion.invalidCharacter.doc.good index 2fdda9fae089..1fcb43bd31bc 100644 --- a/test/chpldoc/compflags/version/projectVersion.invalidCharacter.doc.good +++ b/test/chpldoc/compflags/version/projectVersion.invalidCharacter.doc.good @@ -1,2 +1 @@ error: Invalid version format: a.c.d due to: Invalid Characters, only digits and dots permitted before a hyphen -cat: docs/_static/documentation_options.js: No such file or directory diff --git a/test/chpldoc/compflags/version/projectVersion.invalidTag.doc.good b/test/chpldoc/compflags/version/projectVersion.invalidTag.doc.good index 1c46a8aecbe9..f0558b03a44e 100644 --- a/test/chpldoc/compflags/version/projectVersion.invalidTag.doc.good +++ b/test/chpldoc/compflags/version/projectVersion.invalidTag.doc.good @@ -1,2 +1 @@ error: Invalid version format: 21.0.3-invalid due to: Tag not supported, supported tags are alpha/beta/rc -cat: docs/_static/documentation_options.js: No such file or directory diff --git a/test/chpldoc/compflags/version/projectVersion.lessDots.doc.good b/test/chpldoc/compflags/version/projectVersion.lessDots.doc.good index 04d1214c0586..01c224e5efa5 100644 --- a/test/chpldoc/compflags/version/projectVersion.lessDots.doc.good +++ b/test/chpldoc/compflags/version/projectVersion.lessDots.doc.good @@ -1,2 +1 @@ error: Invalid version format: 21.0-alpha due to: Required only two dots which separates three numbers -cat: docs/_static/documentation_options.js: No such file or directory diff --git a/test/chpldoc/compflags/version/projectVersion.missingNumbers.doc.good b/test/chpldoc/compflags/version/projectVersion.missingNumbers.doc.good index 40eef52a035b..3654b85ac5b9 100644 --- a/test/chpldoc/compflags/version/projectVersion.missingNumbers.doc.good +++ b/test/chpldoc/compflags/version/projectVersion.missingNumbers.doc.good @@ -1,2 +1 @@ error: Invalid version format: 21..3 due to: Missing number between dots -cat: docs/_static/documentation_options.js: No such file or directory From 1f8dd1195d9482d75f56b4eb6c52ba34eb83bbf4 Mon Sep 17 00:00:00 2001 From: Michael Ferguson Date: Tue, 9 Apr 2024 11:13:40 -0400 Subject: [PATCH 10/10] Update pattern matching in nested.doc.prediff --- Signed-off-by: Michael Ferguson --- test/chpldoc/links/nested.doc.prediff | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/chpldoc/links/nested.doc.prediff b/test/chpldoc/links/nested.doc.prediff index 003e24301777..be2d2f852844 100755 --- a/test/chpldoc/links/nested.doc.prediff +++ b/test/chpldoc/links/nested.doc.prediff @@ -24,7 +24,7 @@ reference_pat = re.compile('', html_output): + if not re.search(f'', html_output): output.append(f"Could not find link for reference '#{link}'") else: output.append(f"Found link for reference '#{link}'")