Your message dated Sat, 23 Mar 2024 17:08:27 +0100
with message-id <20240323170827.5cc38a6bec5e5a7b93aee...@mailbox.org>
and subject line Re: Bug#1066967: Bug#1064593: Bug#1066967: dh_sphinxdoc:
replaces files provided by read-the-doc theme by empty symlinks
has caused the Debian Bug report #1066967,
regarding dh_sphinxdoc: replaces files provided by read-the-doc theme by empty
symlinks
to be marked as done.
This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.
(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact ow...@bugs.debian.org
immediately.)
--
1066967: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1066967
Debian Bug Tracking System
Contact ow...@bugs.debian.org with problems
--- Begin Message ---
Package: sphinx-common
Severity: serious
Hi,
dh_sphinxdoc does not work well with read-the-doc theme, apparently.
Debian policy document has switched to sphinx_rtd_theme recently (see
https://salsa.debian.org/dbnpolicy/policy/-/commit/686622814018b5a121252b189d99c1968f332b78
)
However, the built document has a completely broken html layout, because
many files under _static/ are empty (0B size), most noteably
_static/css/theme.css.
If I replace
dh $@ --with sphinxdoc
by
dh $@
(so do not use dh_sphinxdoc), I get a valid html file with the theme
in use.
More details on that topic can be found in
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1064593
To get an idea of how it looks like, see
https://www.debian.org/doc/debian-policy/
(however, there is also an issue with rtd theme on debian.org, that's
why _static/css/ is completely missing there. That's an known issue,
but we need a valid document in the debian-policy binary package first,
to get the website problem fixed.)
So long
Holger
--
Holger Wansing <hwans...@mailbox.org>
PGP-Finterprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
--- End Message ---
--- Begin Message ---
Hi,
Dmitry Shachnev <mity...@debian.org> wrote (Fri, 22 Mar 2024 18:46:25 +0300):
> On Fri, Mar 22, 2024 at 03:30:55PM +0100, Holger Wansing wrote:
> > Ok, I see.
> > So, we will need to get sphinx-rtd-theme-common installed on all debian.org
> > website mirrors, and it will just work (?) ...
>
> From your earlier message it seemed to me like you are using the build
> tree in your deploy process, not the built package.
>
> That is why I suggested not running dh_sphinxdoc, however my suggestion
> applied only to your deploy procedure. The package which is being uploaded
> to Debian archive should still use dh_sphinxdoc.
>
> If you are using the built package and installing it on the remote server,
> then yes, install sphinx-rtd-theme-common and you should be good.
While working on adapting the parts/7doc script (from Debian Webmaster
Team's 'cron' repo), I realized that this is not going to work out of the
box: while the concept of the symlinks mentioned above is working fine,
when the debian-policy document is installed on a machine as usual
(means it recides in the same path as in the binary deb package, aka
/usr/share/doc/debian-policy/policy.html), we have the docs for the website
on the debian.org website machine in another path. That is in
/srv/www.debian.org/www/doc/debian-policy/.
That means the (relative) symlinks will not resolve!
Therefore I think the best solution here is, to change the relative
symlinks into absolute ones, on the debian.org website machine.
I have worked out the needed changes for cron/parts/7doc to deal with all
this (it works fine here locally). The debian-policy package could stay
unchanged.
I attach the patch here just for reference; will apply it, as soon as
sphinx-rtd-theme-common gets installed on wolkenstein
(working on a bugreport to DSA to get this done).
Closing #1066967 against sphinx-common/dh_sphinxdoc now.
Thanks python people for your help!
> Actually, I would move ${sphinxdoc:Depends} from Recommends to Depends,
> because the documentation is mostly unusable without the static files.
Ok. I will leave this mostly to Debian Policy maintainers.
Greetings
Holger
--
Holger Wansing <hwans...@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
diff --git a/parts/7doc b/parts/7doc
index b079aea..5a358d7 100755
--- a/parts/7doc
+++ b/parts/7doc
@@ -260,22 +260,24 @@ if [ "$lang" = "en" ]; then
install -p -m 664 `readlink -f $page` $destdir/Common_Content/images/$(basename $page)
fi
done
fi
}
#############################################################################
mvhtml_sphinx()
{
-# Copy of mvhtml(), modified so it copies the _images and _static subfolders too
-# This is needed by debian-policy since they moved to reStructuredText and Sphinx
+# Copy of mvhtml(), modified so it copies the _images, _sources, _static, _static/css
+# and _static/fonts subfolders too.
+# This is needed by some manuals which moved to reStructuredText and Sphinx
+# (like debian-policy and developers-reference) and use an html theme from read-the-docs.
# This is probably uncomplete, since the _static folder contains symlinks to
# some javascript that probably will not work.
namedest=$1 # destdir directory: maint-guide
basedir=$2 # binary package data dir.: usr/share/doc/maint-guide-fr/html
addlang=${3:-NO} # $lang in filename: NO | ADD | YES
# NO: without $lang and leave it so
# ADD: without $lang and add it (make link for en) (internal URL conversion)
# YES: with $lang and leave it so (make link for en)
lang=${4:-en} # language name: en (default), fr, ...
@@ -317,20 +319,36 @@ for page in $pagepattern; do
done
if [ "$lang" = "en" ]; then
pagepattern="$basedir/_static/*"
for page in $pagepattern; do
if [ -f "`readlink -f $page`" ]; then
mkdirp $destdir/_static
install -p -m 664 `readlink -f $page` $destdir/_static/$(basename $page)
fi
done
+ pagepattern="$basedir/_static/css/*"
+ for page in $pagepattern; do
+ if [ -d "$basedir/_static/css" ]; then
+ # Replace all existing relative symlinks in css by absolute symlinks to the correct place.
+ mkdirp $destdir/_static/css
+ ln -sf /usr/share/sphinx_rtd_theme/static/css/$(basename $page) $destdir/_static/css/$(basename $page)
+ fi
+ done
+ pagepattern="$basedir/_static/fonts/*"
+ for page in $pagepattern; do
+ if [ -d "$basedir/_static/fonts" ]; then
+ # Replace all existing relative symlinks in fonts by absolute symlinks to the correct place.
+ mkdirp $destdir/_static/fonts
+ ln -sf /usr/share/sphinx_rtd_theme/static/fonts/$(basename $page) $destdir/_static/fonts/$(basename $page)
+ fi
+ done
pagepattern="$basedir/_images/*"
for page in $pagepattern ; do
if [ -f "`readlink -f $page`" ]; then
mkdirp $destdir/_images
install -p -m 664 `readlink -f $page` $destdir/_images/$(basename $page)
fi
done
pagepattern="$basedir/_sources/*"
for page in $pagepattern ; do
if [ -f "`readlink -f $page`" ]; then
--- End Message ---
