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
