XPost: linux.debian.policy
This is a multi-part message in MIME format.
Hi,
Dmitry Shachnev <
mitya57@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 <
hwansing@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-f