Package: python3.14-doc
Version: 3.14.7-4
Severity: normal
debian/pyhtml2devhelp.py generates an index for the HTML documentation,
in devhelp format, by screen-scraping Sphinx's HTML output.
Unfortunately it makes some assumptions about the HTML that are no
longer true. When a function of the same name exists in multiple places,
which is quite common in Python, index entries in genindex-*.html look
like this:
>...
>exhausted
>exists() (in module os.path)
> (pathlib.Path method)
> (pathlib.types.PathInfo method
> (tkinter.ttk.Treeview method)
> (zipfile.Path method)
>exit (built-in variable)
>...
The first of the multiple entries for `exists()` gets into the devhelp
index correctly, as something like this (this is with my patch sent to a
separate bug to generate devhelp2 format, currently it's a <function>
but the content is otherwise equivalent):
> <keyword link="library/os.path.html#os.path.exists" name="exists() (in
> module os.path)" type="function"/>
But the others lose the information that the method is named "exists",
making the index entries unhelpful to search or browse:
> <keyword link="library/pathlib.html#pathlib.Path.exists" name="(pathlib.Path
> method)" type="function"/>
> <keyword link="library/pathlib.html#pathlib.types.PathInfo.exists"
> name="(pathlib.types.PathInfo method)" type="function"/>
> <keyword link="library/tkinter.ttk.html#tkinter.ttk.Treeview.exists"
> name="(tkinter.ttk.Treeview method)" type="function"/>
> <keyword link="library/zipfile.html#zipfile.Path.exists" name="(zipfile.Path
> method)" type="function"/>
It looks as though maybe Sphinx output used to emit these disambiguation
entries wrapped in <dl>/<dt>? But now they are in <ul>/<li>, for
example:
> <li><a href="library/os.path.html#os.path.exists">exists() (in module
> os.path)</a>
>
> <ul>
> <li><a href="library/pathlib.html#pathlib.Path.exists">(pathlib.Path
> method)</a>
></li>
> <li><a
> href="library/pathlib.html#pathlib.types.PathInfo.exists">(pathlib.types.PathInfo
> method)</a>
></li>
> <li><a
> href="library/tkinter.ttk.html#tkinter.ttk.Treeview.exists">(tkinter.ttk.Treeview
> method)</a>
></li>
> <li><a href="library/zipfile.html#zipfile.Path.exists">(zipfile.Path
> method)</a>
></li>
> </ul></li>
One way to fix this, which would probably be the most reliable in the
long term, would be to use the python3-sphinxcontrib.devhelp Sphinx
plugin to generate HTML with an accompanying devhelp index, instead of
generating the index separately. That would offload responsibility for
generating the devhelp index onto code that is already designed to
handle it.
Or failing that, perhaps the index could be generated from
searchindex.js or objects.inv, or some intermediate file used by Sphinx
during the build, instead of parsing the HTML?
Or, the heuristic for screen-scraping the HTML could be updated to
understand the new <ul>/<li>-based formatting.
Thanks,
smcv
-- System Information:
Debian Release: forky/sid
APT prefers unstable-debug
APT policy: (500, 'unstable-debug'), (500, 'testing-debug'), (500,
'stable-updates'), (500, 'stable-security-debug'), (500, 'stable-security'),
(500, 'stable-debug'), (500, 'proposed-updates-debug'), (500,
'oldstable-security-debug'), (500, 'oldstable-security'), (500,
'oldstable-debug'), (500, 'buildd-unstable'), (500, 'unstable'), (500,
'testing'), (500, 'stable'), (1, 'experimental-debug'), (1,
'buildd-experimental'), (1, 'experimental')
Architecture: amd64 (x86_64)
Foreign Architectures: i386
Kernel: Linux 7.1.13+deb14-amd64 (SMP w/14 CPU threads; PREEMPT)
Locale: LANG=en_GB.UTF-8, LC_CTYPE=en_GB.UTF-8 (charmap=UTF-8),
LANGUAGE=en_GB:en
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
Versions of packages python3.14-doc depends on:
ii libjs-jquery 3.7.1+dfsg+~3.5.33-1
ii libjs-underscore 1.13.8~dfsg+~1.13.0-1
python3.14-doc recommends no packages.
Versions of packages python3.14-doc suggests:
ii python3.14 3.14.7-4
-- no debconf information
