Bug#1090126: pyte: FTBFS: ERROR: Invalid value `None` in intersphinx_mapping['http://docs.python.org/']. Expected a two-element tuple or list.

[Florian Ernst]

Control: tags -1 upstream patch
Control: forwarded -1 https://github.com/selectel/pyte/issues/191

Dear maintainer,

[ adding a CC to debian-***@lists.debian.org to solicit further input
on best practices ]

[...]
python3 -m sphinx -b html -d docs/build/doctrees docs docs/build/html
Running Sphinx v8.1.3
loading translations [en]... done
making output directory... done
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
ERROR: Invalid value `None` in intersphinx_mapping['http://docs.python.org/']. Expected a two-element tuple or list.
Invalid `intersphinx_mapping` configuration (1 error).
make[1]: *** [debian/rules:11: override_dh_auto_build] Error 2
[...]

The intersphinx_mapping does not conform to the recent standards
anymore, cf.
<https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_mapping>.

A simple patch along the lines of

| --- pyte-0.8.0.orig/docs/conf.py
| +++ pyte-0.8.0/docs/conf.py
| @@ -176,7 +176,7 @@ else:
| htmlhelp_basename = 'pytedoc'
|
| # Example configuration for intersphinx: refer to the Python standard library.
| -intersphinx_mapping = {'http://docs.python.org/': None}
| +intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
|
| autodoc_member_order = 'bysource'
| todo_include_todos = True

allows the package to successfully build its documentation again.

JFTR, so far this seems to be unresolved even in the most recent
upstream version, cf.
<https://github.com/selectel/pyte/blob/master/docs/conf.py#L215>, so I
filed <https://github.com/selectel/pyte/issues/191> for this.


@debian-python:

However, AFAIK intersphinx will download things from the internet during
build, which is not allowed by policy. So maybe just ripping out all
intersphinx references from the conf.py would be more suitable. I tested
that and the resulting files are identical (except for a missing
reference to intersphinx in the resulting searchindex.js, of course).
I don't know the current best practices on that with respect to Sphinx,
hence the CC.

Cheers,
Flo

[Andrey Rakhmatullin]

Post by Florian Ernst
However, AFAIK intersphinx will download things from the internet during
build, which is not allowed by policy. So maybe just ripping out all
intersphinx references from the conf.py would be more suitable. I tested
that and the resulting files are identical (except for a missing
reference to intersphinx in the resulting searchindex.js, of course).
I don't know the current best practices on that with respect to Sphinx,
hence the CC.

Yes, we normally patch docs/conf.py to use objects.inv from the -doc
packages.

[Florian Ernst]

Post by Andrey Rakhmatullin

Post by Florian Ernst
However, AFAIK intersphinx will download things from the internet during
build, which is not allowed by policy. So maybe just ripping out all
intersphinx references from the conf.py would be more suitable. I tested
that and the resulting files are identical (except for a missing
reference to intersphinx in the resulting searchindex.js, of course).
I don't know the current best practices on that with respect to Sphinx,
hence the CC.

Yes, we normally patch docs/conf.py to use objects.inv from the -doc
packages.

Ah, right, thanks for the pointer. And when I restrict my codesearch to
just files below debian/ as per
<https://codesearch.debian.net/search?q=intersphinx_mapping+path%3Adebian%2F&literal=1>
then I get sensible patch samples, whereas without that restriction I was
overwhelmed by 355 pages of intersphinx_mapping that seemingly still
cause downloads during build.

So yeah, then my previous patch should rather look like this, I presume:

| Index: pyte-0.8.0/docs/conf.py
| ===================================================================
| --- pyte-0.8.0.orig/docs/conf.py
| +++ pyte-0.8.0/docs/conf.py
| @@ -176,7 +176,9 @@ else:
| htmlhelp_basename = 'pytedoc'
|
| # Example configuration for intersphinx: refer to the Python standard library.
| -intersphinx_mapping = {'http://docs.python.org/': None}
| +intersphinx_mapping = {
| + 'python': ('/usr/share/doc/python3-doc/html', '/usr/share/doc/python3-doc/html/objects.inv'),
| +}
|
| autodoc_member_order = 'bysource'
| todo_include_todos = True

I confirmed that the FTBFS will still remain resolved with this.

HTH,
Flo