Bug#1064593: dh_sphinxdoc: replaces files provided by read-the-doc theme by empty symlinks

[Holger Wansing <hwansing@mailbox.org>]

Hi,

Sean Whitton <spwhitton@spwhitton.name> wrote (Thu, 28 Mar 2024 09:48:51 +0800):
> 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.

DSA (adsb) did install the python3-sphinx-rtd-theme package on the www static 
mirrors (thanks Adam for the quick reaction !!!), and I pushed my changings 
to the 7doc script, but reality has proven me wrong, sadly:

The idea was, to have absolute symlinks from inside the manuals directories
to /usr/share/sphinx_rtd_theme/static/... and all looks fine on wolkenstein,
but those symlinks fail to get synced to the www static mirrors, because of
rsync's "--safe-links" option:

	--safe-links             ignore symlinks that point outside the tree

Thus, the debian-policy is still broken on our website, as before.


I now tend to switch to another approach (also proposed similarly by Adam):

instead of relying on the rtd-theme package in the default install path of the
package installed by DSA, I will use the infrastructure in 1ftpfiles and 
7doc of webmaster's cron repo, to (always) fetch the latest version of that 
package (and two more packages, which the former depends on: fonts-font-awesome
and fonts-lato, to get the needed fonts) and unpack+copy them into
a dedicated path inside the www build tree.

That path will be synced to the static www mirrors, and we can symlink
to it from the manuals.
(And the content of that path will automatically be kept up-to-date on
the unstable version of packages, so we don't get outdated/orphaned
copies of that packages in the isolated path.)
I want the unstable version of that packages here, since they need to
incorporate with the unstable version of the different manuals (like
debian-policy), and those packages are built by buildd, so unstable.

How does that sound in the light of Debian guidelines and best practice?

Is it ok, to have such "isolated copies" of packages as described above?

I have not much experience in similar things, so I would like to get
some comments here, please.

Or do people prefer a complete different way, like using another theme
or whatever? (since this thing is getting bigger and bigger currently)

(Please keep in mind that this is not only for debian-policy, but in the
long term all sphinx-based manuals are supposed to follow the path 
discussed here.)

I already proposed to switch away from dh_sphinxdoc, to completely get rid 
of this symlink issue, but someone mentioned various privacy issues as a
contra argument...



Patch attached for the first part (to get above mentioned packages
in the www build path) - just posted for reference here.
(Second part - to point the debian-policy manual to that path - will
follow in another round.)


Holger



-- 
Holger Wansing <hwansing@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508  3529 59F1 87CA 156E B076

diff --git a/parts/1ftpfiles b/parts/1ftpfiles
index 3a2d953..3079131 100755
--- a/parts/1ftpfiles
+++ b/parts/1ftpfiles
@@ -72,6 +72,11 @@ $WGET -O - $httpurlamd64 | xzcat >Packages-amd64
 
 httpurlrepo="http://${ftpsite}/debian";
 
+# readthedocs.org html theme files and related fonts
+getdeb all sphinx-rtd-theme-common
+getdeb all fonts-font-awesome
+getdeb all fonts-lato
+
 # many language specific binary packages (arch=all)
 getdebs aptitude
 getdebs debian-faq
diff --git a/parts/7doc b/parts/7doc
index 6998512..47e076e 100755
--- a/parts/7doc
+++ b/parts/7doc
@@ -428,6 +428,45 @@ echo -n "Installing documents:" >> $webdocdir/build.log
 # We only have sid now
 dist=sid
 
+# readthedocs.org html theme files and related fonts.
+# We need those files inside the www.d.o build tree on wolkenstein, because
+# the manuals will have symlinks pointing to those files, and syncing such
+# symlinks to the static www mirrors fails, when they point outside of the
+# tree (because of rsync's "--safe-links" option).
+# Therefore, we cannot simply have the packages installed by DSA on
+# wolkenstein, but we need an own copy inside the tree (in
+# www/doc/html-theme).
+# Since the manuals here are built on buildds and therefore are based on
+# unstable, I want to use the unstable version of the following packages
+# as well.
+unpack sphinx-rtd-theme-common
+   for themefilecss in usr/share/sphinx_rtd_theme/static/css/* ; do
+	mkdirp $webdocdir/html-theme/sphinx_rtd_theme/static/css
+	cp -rf $themefilecss $webdocdir/html-theme/sphinx_rtd_theme/static/css
+   done
+   for themefilefonts in usr/share/sphinx_rtd_theme/static/fonts/* ; do
+	mkdirp $webdocdir/html-theme/sphinx_rtd_theme/static/fonts
+	cp -rf $themefilefonts $webdocdir/html-theme/sphinx_rtd_theme/static/fonts
+   done
+unpack fonts-font-awesome
+   for fontfileawesome1 in usr/share/fonts-font-awesome/fonts/* ; do
+	mkdirp $webdocdir/html-theme/fonts-font-awesome/fonts
+	cp -rf $fontfileawesome1 $webdocdir/html-theme/fonts-font-awesome/fonts
+   done
+   for fontfileawesome2 in usr/share/fonts/opentype/font-awesome/* ; do
+	mkdirp $webdocdir/html-theme/fonts/opentype/font-awesome
+	cp -rf $fontfileawesome2 $webdocdir/html-theme/fonts/opentype/font-awesome
+   done
+   for fontfileawesome3 in usr/share/fonts/truetype/font-awesome/* ; do
+	mkdirp $webdocdir/html-theme/fonts/truetype/font-awesome
+	cp -rf $fontfileawesome3 $webdocdir/html-theme/fonts/truetype/font-awesome
+   done
+unpack fonts-lato
+   for fontfilelato in usr/share/fonts/truetype/lato/* ; do
+	mkdirp $webdocdir/html-theme/fonts/truetype/lato
+	cp -rf $fontfilelato $webdocdir/html-theme/fonts/truetype/lato
+   done
+
 # Debian Policy Manual
 unpack debian-policy
 if [ ! -e $ftpdir/${dist}/debian-policy.skip ]; then