Update chpldoc dependencies (#24612)

This PR updates the chpldoc requirements to the newest versions. I tried this because I was thinking about adjustment to the search box, and I wanted to see if the newer versions of Sphinx behave differently. (They do not seem to). Sphinx 7.2.6 requires Python >= 3.9, so this PR updates prereqs.rst to list 3.9 as required for chpldoc, start_test, and c2chapel. (The previous requirement for these was Python 3.7). It adds the sphinx extension `sphinxcontrib.jquery` to `conf.py` because the search box from sphinx-rtd-theme now uses jquery. | package | version before this PR | version after this PR | | ------- | ---------------------- | --------------------- | | MarkupSafe | 2.1.3 | 2.1.5 | | Sphinx | 5.3.0 | 7.2.6 | | urllib3 | 2.1.0 | 2.2.1 | | docutils | 0.18 | 0.20.1 | | sphinxcontrib-chapeldomain | 0.0.31 | 0.0.32 | (note that chapel-lang/sphinxcontrib-chapeldomain#92 updated sphinxcontrib-chapeldomain in a coordinated manner: docutils 0.18 -> 0.20.1 and Sphinx 5.3.0 -> 7.2.6. The result of that PR is available in sphinxcontrib-chapeldomain version 0.0.32.) Reviewed by @lydia-duncan - thanks! - [x] full comm=none testing
chapel-lang · Apr 9, 2024 · 985649f · 985649f
2 parents 701d0c7 + 1f8dd11
commit 985649f
Show file tree

Hide file tree

Showing 17 changed files with 29 additions and 16 deletions.
diff --git 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

diff --git a/doc/rst/conf.py b/doc/rst/conf.py
@@ -33,13 +33,17 @@
 # ones.
 extensions = [
     'sphinx.ext.todo',
+    'sphinxcontrib.jquery',
     'sphinxcontrib.chapeldomain',
     'sphinx.ext.mathjax',
     'util.disguise',
     'breathe',
 ]
 
 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 = []

diff --git 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.

diff --git 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
@@ -46,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
@@ -63,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

diff --git 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:

diff --git 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`.

diff --git 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
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/test/chpldoc/links/nested.doc.prediff b/test/chpldoc/links/nested.doc.prediff
@@ -24,7 +24,7 @@ reference_pat = re.compile('<a class="reference internal" href="#(.+?)" title="\
 for m in re.finditer(reference_pat, html_output):
     # for each reference, check if the link exists
     link = m.group(1)
-    if not re.search(f'<a class="headerlink" href="#{link}" title="Permalink to this definition">', html_output):
+    if not re.search(f'<a class="headerlink" href="#{link}" title="Link to this definition">', html_output):
         output.append(f"Could not find link for reference '#{link}'")
     else:
         output.append(f"Found link for reference '#{link}'")

diff --git 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
@@ -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
@@ -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==0.0.32
 breathe==4.35.0
Original file line number	Diff line number	Diff line change
		@@ -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
Original file line number	Diff line number	Diff line change
		@@ -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
Original file line number	Diff line number	Diff line change
		@@ -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
Original file line number	Diff line number	Diff line change
		@@ -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
Original file line number	Diff line number	Diff line change
		@@ -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