Package: python3.14-doc
Version: 3.14.7-4
Severity: normal
Tags: patch
debian/pyhtml2devhelp.py generates a manual in devhelp format v1, which
was replaced by format v2 in 2005 and deprecated in 2018. Applications
based on the foundry library, like manuals (which replaced devhelp in
testing/unstable) and gnome-builder, no longer support loading devhelp
format v1 libraries.
One way to address this would be to make pyhtml2devhelp.py generate a
.devhelp2 file, instead of the current .devhelp.gz, and adapt its
contents to format v2. I attach some patches to do this.
Alternatively, the packaging could use python3-sphinxcontrib.devhelp,
which provides an extended version of sphinx's HTML output that adds a
devhelp index, and was recently enhanced to generate devhelp format v2.
This would avoid needing to screen-scrape Sphinx's HTML output, which
doesn't work particularly well because it's very sensitive to the exact
HTML that's generated for the index (I'll open a separate bug for the
incomplete index entries that result from this).
Or the index could perhaps be generated by parsing Sphinx's internal
data (searchindex.js or objects.inv, or some temporary file from which
they are generated), but I don't know enough about Sphinx to know which
route would be the best for doing that.
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
>From d4db66846c910274a37b4d1d7271f5dbc822b306 Mon Sep 17 00:00:00 2001
From: Simon McVittie <[email protected]>
Date: Sun, 30 Aug 2026 15:31:03 +0100
Subject: [PATCH 1/3] pyhtml2devhelp.py: Emit devhelp file format v2
The version attribute on the book element is a devhelp file format
version number, not the version of the package that's documented.
The `devhelp` app didn't really validate this, but its replacement
`manuals` does.
Similarly, `devhelp` didn't require the correct XML namespace,
but `manuals` does.
Other than that, the main difference between format version 1 and 2
is that the `<function>` element has been generalized to `<keyword>`.
Signed-off-by: Simon McVittie <[email protected]>
---
debian/pyhtml2devhelp.py | 7 +++++--
1 file changed, 5 insertions(+), 2 deletions(-)
diff --git a/debian/pyhtml2devhelp.py b/debian/pyhtml2devhelp.py
index b19d2e7b568..240a97a9ad9 100644
--- a/debian/pyhtml2devhelp.py
+++ b/debian/pyhtml2devhelp.py
@@ -154,7 +154,7 @@ class PyIdxHTMLParser(HTMLParser):
# Save it in case we need it again
self.last_text = re.sub(' \([\w\-\.\s]+\)', '', text)
indent = self.indent
- print('%s<function link="%s" name="%s"/>' % (' ' * indent, new_href, text))
+ print('%s<keyword link="%s" name="%s" type="function"/>' % (' ' * indent, new_href, text))
def handle_starttag(self, tag, attrs):
if tag == 'a':
@@ -260,7 +260,10 @@ def main():
parser = PyHTMLParser(base, fn, indent=0)
print('<?xml version="1.0" encoding="iso-8859-1"?>')
- print('<book title="Python %s Documentation" name="Python %s" version="%s" link="index.html">' % (version, version, version))
+ print('<book xmlns="http://www.devhelp.net/book";')
+ print(' version="2"') # File format version, not Python version
+ print(' title="Python %s Documentation" name="Python %s"' % (version, version))
+ print(' link="index.html">')
print('<chapters>')
parser.parse_file(fn)
print('</chapters>')
--
2.55.0
>From 352e1e6b1aebb0a2ac98ff4c40058d51793577c2 Mon Sep 17 00:00:00 2001
From: Simon McVittie <[email protected]>
Date: Sun, 30 Aug 2026 15:31:36 +0100
Subject: [PATCH 2/3] pyhtml2devhelp.py: Treat external https links as
equivalent to http
Otherwise they'll be parsed as (broken) links to a local file.
Signed-off-by: Simon McVittie <[email protected]>
---
debian/pyhtml2devhelp.py | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/debian/pyhtml2devhelp.py b/debian/pyhtml2devhelp.py
index 240a97a9ad9..dfe406e5ddf 100644
--- a/debian/pyhtml2devhelp.py
+++ b/debian/pyhtml2devhelp.py
@@ -80,8 +80,13 @@ class PyHTMLParser(HTMLParser):
abs_href = os.path.join(self.basedir, href)
if abs_href in self.parents:
return
- if href.startswith('..') or href.startswith('http:') \
- or href.startswith('mailto:') or href.startswith('news:'):
+ if href.startswith((
+ '..',
+ 'http:',
+ 'https:',
+ 'mailto:',
+ 'news:',
+ )):
return
if href in ('', 'about.html', 'modindex.html', 'genindex.html', 'glossary.html',
'search.html', 'contents.html', 'download.html', 'bugs.html',
--
2.55.0
>From 6e60b9e5fc5abd526a1540404b7e535d3746e516 Mon Sep 17 00:00:00 2001
From: Simon McVittie <[email protected]>
Date: Sun, 30 Aug 2026 15:32:24 +0100
Subject: [PATCH 3/3] d/rules: Emit devhelp index uncompressed and with the
expected extension
This is one of several naming conventions that was accepted by the old
`devhelp` app. Applications based on libfoundry, such as the `manuals`
app that replaces `devhelp`, expect the index to have this specific name
and format.
Signed-off-by: Simon McVittie <[email protected]>
---
debian/rules | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/debian/rules b/debian/rules
index 70c346d4c6a..48449ec498e 100755
--- a/debian/rules
+++ b/debian/rules
@@ -1457,8 +1457,7 @@ binary-indep: build-indep install stamps/stamp-control
: # devhelp docs
cd $(buildd_static) && ./python ../debian/pyhtml2devhelp.py \
../$(d_doc)/usr/share/doc/$(p_base)/html index.html $(VER) \
- > ../$(d_doc)/usr/share/doc/$(p_base)/html/$(PVER).devhelp
- gzip -9nv $(d_doc)/usr/share/doc/$(p_base)/html/$(PVER).devhelp
+ > ../$(d_doc)/usr/share/doc/$(p_base)/html/$(PVER).devhelp2
dh_link -p$(p_doc) \
/usr/share/doc/$(p_base)/html /usr/share/devhelp/books/$(PVER)
--
2.55.0
