Control: reassign 1064593 www.debian.org
Hi all,
Sean Whitton 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
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 sphi
