Control: reassign 1064593 www.debian.org
Hi all, Sean Whitton <spwhit...@spwhitton.name> wrote (Tue, 02 Apr 2024 10:11:39 +0800): > Hello, > > On Mon 01 Apr 2024 at 02:50pm +02, Holger Wansing wrote: > > > 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. > > I mean, it seems okay to me, but it's up to the web team really. Yeah, that makes we aware of that this bug is now assigned to the wrong package (this is no longer an issue on debian-policy side, but on www.debian.org). Therefore, web team is most probably not aware at all of this specific issue. So, I'm reassigning this bug to www.debian.org now. And also debian-doc in CC, since in the past the doc/manuals part of the website was somehow under responsibility of -doc people IIRC. @web + doc teams: We have (after more than 5 years) a new Debian-style html theme for sphinx-based documents, created by Stéphane Blondon based on a readthedocs.org theme. It looks really good, and a preview of debian-policy with this theme can be seen here: https://people.debian.org/~holgerw/new-rtd-sphinx-theme-for-debian/debian-policy/debian-policy/ However, getting this theme to work on the Debian website became more and more of a challenge these days/weeks. An issue came up, which can be seen at Debian's website: https://www.debian.org/doc/debian-policy/ The html layout is completely broken, because the theme relys on files provided by the sphinx-rtd-theme-common package, which are not there on the www mirrors. Getting that files correctly on the mirrors occured to become difficult, sadly. You can find a current summary of this issue at https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1064593#125 This comes down to one more adaption of the 1ftpfiles / 7doc scripts in webmaster's cron repo. Attached is the latest version of my patch, to get this going. It works so far, but I wonder if this is the way we want to go. There is a significant amount of things, which need to work correctly to make this new theme appear correctly on Debian's website: We need a separate copy of 3 packages in our www build tree on wolkenstein and all www static mirrors (simply let DSA install those packages on the machines will not work). And every sphinx-based manual needs relative symlinks in its tree, pointing to the above packages' content. The 1ftpfiles and 7doc scripts, which need to be adapted for that, and also the situation on the www mirrors is getting more complex, so I'm unsure if we want this. See my patch. On the other side, I don't see any other solution apart from developing a new theme. Comments? Holger -- Holger Wansing <hwans...@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 b079aea..c2ff284 100755 --- a/parts/7doc +++ b/parts/7doc @@ -341,6 +341,39 @@ if [ "$lang" = "en" ]; then fi } +############################################################################# + +place_symlinks_to_theme_files() +# To make the html theme (which is based on a readthedocs.org theme) for +# sphinx-based documents work, we need relative symlinks pointing from the +# manual's _static/css/* and _static/fonts/* files to targets inside of +# doc/html-theme/ in the www build tree. +# Those targets are populated from the sphinx-rtd-theme-common, fonts-font-awesome +# and fonts-lato packages. See below. +{ +namedest=$1 # destdir directory: debian-policy +basedir=$2 # binary package data dir.: usr/share/doc/debian-policy/policy.html +sectdir=$3 # destination top directory (/ for debian-policy; manuals/ for all other documents) + +destdir=$webdocdir/${sectdir}$namedest +mkdirp $destdir + +pagepattern="$basedir/_static/css/*" +for page in $pagepattern; do + if [ -d "$basedir/_static/css" ]; then + mkdirp $destdir/_static/css + ln -srf $webdocdir/html-theme/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 + mkdirp $destdir/_static/fonts + ln -srf $webdocdir/html-theme/sphinx_rtd_theme/static/fonts/$(basename $page) $destdir/_static/fonts/$(basename $page) + fi +done +} + ############################################################################# lclocal() { @@ -408,11 +441,52 @@ 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 (see function +# place_symlinks_to_theme_files above), 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 of the package contents inside the tree +# (I have created ../www/doc/html-theme for that purpose). +# Since the manuals' binary packages processed 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 mvdocs debian-policy usr/share/doc/debian-policy NO en / policy mvhtml_sphinx debian-policy usr/share/doc/debian-policy/policy.html NO en / +place_symlinks_to_theme_files debian-policy usr/share/doc/debian-policy/policy.html / mvdocs fhs usr/share/doc/debian-policy/fhs NO en packaging-manuals/ fhs-3.0 mvhtml fhs usr/share/doc/debian-policy/fhs NO en packaging-manuals/ fhs-3.0
