Update chpldoc dependencies

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

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

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.

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

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:

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

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

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

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

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

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

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

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}'")

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

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

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