make documentation building compatible with sphinx 5

[kiwifb]

Sphinx 5 has been out for a bit and is now stable in Gentoo at least.

Identified issues

make[1]: Entering directory '/home/portage/sci-mathematics/sage-doc-9999/work/sage-doc-9999/src/doc'
python -m sage_docbuild --no-pdf-links reference/references inventory 
[reference] Extension error:
[reference] Could not import extension sage_docbuild.ext.sage_autodoc (exception: cannot import name 'get_module_members' from 'sphinx.ext.autodoc.importer' (/usr/lib/python3.10/site-packages/sphinx/ext/autodoc/importer.py))

According to https://www.sphinx-doc.org/en/master/extdev/deprecated.html sphinx.ext.autodoc.importer.get_module_members was deprecated in sphinx 3.5 and removed in sphinx 5.0. As it happen, this is a useless import since the method is superseded by sage_autodoc's own.

Error building the documentation.
Traceback (most recent call last):
  File "/usr/lib/python3.10/runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/usr/lib/python3.10/runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "/usr/lib/python3.10/site-packages/sage_docbuild/__main__.py", line 500, in <module>
    sys.exit(main())
  File "/usr/lib/python3.10/site-packages/sage_docbuild/__main__.py", line 497, in main
    builder()
  File "/usr/lib/python3.10/site-packages/sage_docbuild/builders.py", line 823, in _wrapper
    getattr(DocBuilder, build_type)(self, *args, **kwds)
  File "/usr/lib/python3.10/site-packages/sage_docbuild/builders.py", line 167, in f
    runsphinx()
  File "/usr/lib/python3.10/site-packages/sage_docbuild/sphinxbuild.py", line 327, in runsphinx
    sys.stderr.raise_errors()
  File "/usr/lib/python3.10/site-packages/sage_docbuild/sphinxbuild.py", line 263, in raise_errors
    raise OSError(self._error)
OSError: WARNING: extlinks: Sphinx-6.0 will require a caption string to contain exactly one '%s' and all other '%' need to be escaped as '%%'.

This can be fixed by a small syntax correction for extlinks in sage.misc.sagedoc

[structure] /usr/lib/python3.10/site-packages/sage_docbuild/ext/sage_autodoc.py:791: RemovedInSphinx60Warning: DocumenterBridge.filename_set is deprecated.
[structure]   self.directive.filename_set.add(self.analyzer.srcname)

by the truckload everywhere (not just structure) and repeatedly. Suggested replacement is sphinx.ext.autodoc.directive.DocumenterBridge.record_dependencies. But it doesn't prevent the documentation to build unlike the previous two.

All changes in the branch should work with sphinx 4.4 and 4.5 as they concern things deprecated in sphinx 4.0 or earlier.

Depends on #34109

CC: @antonio-rojas @strogdon @collares

Component: documentation

Author: François Bissey

Branch/Commit: 6f9ceb7

Reviewer: Antonio Rojas

Issue created by migration from https://trac.sagemath.org/ticket/34149

[kiwifb]

comment:3

As it turns out, the imported get_module_members is overridden by the method of the same name from sage_autodoc own ModuleDocumenter class. Simply removing the import is enough.

Next error:

Error building the documentation.
Traceback (most recent call last):
  File "/usr/lib/python3.10/runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/usr/lib/python3.10/runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "/usr/lib/python3.10/site-packages/sage_docbuild/__main__.py", line 500, in <module>
    sys.exit(main())
  File "/usr/lib/python3.10/site-packages/sage_docbuild/__main__.py", line 497, in main
    builder()
  File "/usr/lib/python3.10/site-packages/sage_docbuild/builders.py", line 823, in _wrapper
    getattr(DocBuilder, build_type)(self, *args, **kwds)
  File "/usr/lib/python3.10/site-packages/sage_docbuild/builders.py", line 167, in f
    runsphinx()
  File "/usr/lib/python3.10/site-packages/sage_docbuild/sphinxbuild.py", line 327, in runsphinx
    sys.stderr.raise_errors()
  File "/usr/lib/python3.10/site-packages/sage_docbuild/sphinxbuild.py", line 263, in raise_errors
    raise OSError(self._error)
OSError: WARNING: extlinks: Sphinx-6.0 will require a caption string to contain exactly one '%s' and all other '%' need to be escaped as '%%'.

Warning for upcoming sphinx 6.0 is treated as an error.

[kiwifb]

Author: François Bissey

[kiwifb]

Commit: 18c9245

[kiwifb]

Branch: u/fbissey/sphinx5

[kiwifb]

New commits:

3ee509a	remove unused, and removed from sphinx 5, imported get_module_members
18c9245	fix syntax so extlinks stop complaining

[sagetrac-git]

Changed commit from 18c9245 to c27e4e4

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

c27e4e4

migrate from filename_set to record_dependencies as suggested in https://www.sphinx-doc.org/en/master/extdev/deprecated.html

[kiwifb]

comment:8

@antonio-rojas FYI if this doesn't make it in 9.7.

[kiwifb]

comment:9

@Steve I pushed the change in Gentoo last night (NZ time) would be OK to review this?

[antonio-rojas]

comment:10

WFM, thanks (and I just found out that doc building on distros got yet more complicated in 9.7, sigh)

[kiwifb]

comment:11

Replying to @antonio-rojas:

WFM, thanks (and I just found out that doc building on distros got yet more complicated in 9.7, sigh)

I haven't experienced trouble so far apart from sphinx just going up under my nose on Gentoo. What do you have problem with? For the record, I ended up splitting sage-doc as its own thing at about sage 9.5 because my work arounds for monolithic build where just looking they could break any time. Splitting has its issue but for documentation building it was positive overall.

[antonio-rojas]

comment:12

Replying to @kiwifb:

I haven't experienced trouble so far apart from sphinx just going up under my nose on Gentoo. What do you have problem with? For the record, I ended up splitting sage-doc as its own thing at about sage 9.5 because my work arounds for monolithic build where just looking they could break any time. Splitting has its issue but for documentation building it was positive overall.

Going through the makefile is now mandatory
sagemath/sagetrac-mirror@7759f3c

[kiwifb]

comment:13

Yes, I split before my work around for not using the Makefile would break. It looks like that was a good early move. Using the Makefile is good but I could not leave it as is, especially the bits about SAGE_ROOT.
https://github.com/cschwan/sage-on-gentoo/blob/master/sci-mathematics/sage-doc/files/sage-doc-9.7-makefile_and_parallel.patch

[vbraun]

comment:14

Merge failure on top of:

73d7bb0aae Trac #34122: Bug in is_planar() method for directed graphs

b9b73ce665 Trac #33160: update Singular to 4.3.1

1dd3b4819f Trac #33134: doctest failure in hilbert_poincare_series with singular 4.2.1

c9cfb53 Trac #34087: inverse reciprocal trig functions not (back)translated to/from Mathematica

1d6d055 Trac #34076: pycodestyle cleanup in src/sage/graphs/genus.pyx

043d862 Trac #34071: pycodestyle cleanup in asteroidal_triples.pyx, chrompoly.pyx, cliquer.pyx, convexity_properties.pyx

b9b25dc Trac #34070: pycodestyle cleanup in src/sage/graphs/centrality.pyx

4ef2c65 Trac #34069: pycodestyle cleanup in src/sage/graphs/comparability.pyx

5b11467 Trac #34066: Tachyon help message

798adaa Trac #34065: pycodestyle cleanup in src/sage/graphs/bliss.pyx

ce62be2 Trac #34063: pycodestyle cleanup in src/sage/graphs/base/

a0eadb3 Trac #34059: Fix trivial case in conversion of list to number field element

fea0ac5 Trac #34057: changes about avoiding double dieses

9eefd5c Trac #34145: modernize super in geometry/

01e117d Trac #34137: modernize super in categories/

6c79334 Trac #33819: build.yml: In workflow_dispatch, make container and base tag selectable; add doc

6a64ab8 Trac #33760: do not update _pos, _pos3d, _embedding on vertex/edge deletions

dbf091d Trac #34139: fix the linter

625ac58 Updated SageMath version to 9.7.beta5

reviewer '' does not look right

[strogdon]

Reviewer: Antonio Rojas

[strogdon]

comment:15

I think this is all that was needed.

[kiwifb]

comment:16

Thanks Steve, I did not receive an email for the change triggered by Volker.

[kiwifb]

Dependencies: #34109

[kiwifb]

comment:17

Conflict with #34109 which touches exactly the same line in sagedoc.py.

[sagetrac-git]

Changed commit from c27e4e4 to 6f9ceb7

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

211f964	pep8 for sagedoc.py
9059b4c	fix
6f9ceb7	Merge branch '34109' into sphinx-5

[kiwifb]

comment:19

Merged with #34109 which is positively reviewed and in the process of being merged - back to positive review.

[vbraun]

Changed branch from u/fbissey/sphinx5 to 6f9ceb7