Bug#1064593: Bug#1066967: Bug#1064593: Bug#1066967: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks
Hello,
On Fri 22 Mar 2024 at 06:46pm +03, Dmitry Shachnev wrote:
> Actually, I would move ${sphinxdoc:Depends} from Recommends to
> Depends, because the documentation is mostly unusable without the
> static files.
I think it's in Recommends because we ship other formats that don't need
it, and to ensure installability on stable, or something similar.
--
Sean Whitton
signature.asc
Description: PGP signature
Bug#1064593: Bug#1066967: Bug#1064593: Bug#1066967: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks
Hello, On Sat 23 Mar 2024 at 05:08pm +01, Holger Wansing wrote: > 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! Many thanks all for working on this, especially you Holger for this scripting work. So, we're waiting in DSA and then on your script changes, and it'll work again. -- Sean Whitton signature.asc Description: PGP signature
Bug#1064593: Bug#1066967: Bug#1064593: Bug#1066967: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks
Hi,
Dmitry Shachnev 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
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
Bug#1064593: Bug#1066967: Bug#1064593: Bug#1066967: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks
Hi,
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.
Actually, I would move ${sphinxdoc:Depends} from Recommends to Depends,
because the documentation is mostly unusable without the static files.
--
Dmitry Shachnev
signature.asc
Description: PGP signature
Bug#1064593: Bug#1066967: Bug#1064593: Bug#1066967: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks
Hi, Dmitry Shachnev wrote (Fri, 22 Mar 2024 16:04:14 +0300): > On Fri, Mar 22, 2024 at 01:46:48PM +0100, Holger Wansing wrote: > > [...] > > Anyway, the symlink points to some path inside the package build path, here: > > /srv/debian-policy/debian-policy-4.6.2.1/debian/debian-policy/usr/share/sphinx_rtd_theme_static/css/theme.css > > > > and that path does not exist. > > Same in the debian-policy binary package. > > This is expected. The path in the build tree is relative in a way that when > a package is built and installed, it becomes working. 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 (?) ... > The symlink is generated relative per Policy 10.5. And I think that even if > dh_sphinxdoc generated it as absolute, dh_link would later change it to > relative. > > If you are trying to rely on something that is in the build directory, you > have to turn relative symlinks into absolute ones on your own. Or just don't > call dh_sphinxdoc, then you will get normal files. ... or we switch away from dh_sphinxdoc. But there was already a hint, why this is a bad idea. Will need to be evaluated... Thanks for your time, guys! Holger -- Holger Wansing PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076
Bug#1064593: Bug#1066967: Bug#1064593: Bug#1066967: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks
On Fri, Mar 22, 2024 at 01:46:48PM +0100, Holger Wansing wrote: > [...] > Anyway, the symlink points to some path inside the package build path, here: > /srv/debian-policy/debian-policy-4.6.2.1/debian/debian-policy/usr/share/sphinx_rtd_theme_static/css/theme.css > > and that path does not exist. > Same in the debian-policy binary package. This is expected. The path in the build tree is relative in a way that when a package is built and installed, it becomes working. The symlink is generated relative per Policy 10.5. And I think that even if dh_sphinxdoc generated it as absolute, dh_link would later change it to relative. If you are trying to rely on something that is in the build directory, you have to turn relative symlinks into absolute ones on your own. Or just don't call dh_sphinxdoc, then you will get normal files. -- Dmitry Shachnev signature.asc Description: PGP signature
