Re: Bug#931548: Migration to Sphinx
Hi,
On Wed, Jul 24, 2019 at 08:40:19PM +0000, Holger Levsen wrote:
> hi,
>
> dear debian-www people: src:developers-reference was just switched to
> use sphinx, just like src:debian-policy. However, no upload to unstable
> has been made yet...
>
> On Tue, Jul 23, 2019 at 08:13:50AM -0700, Sean Whitton wrote:
> > On Mon 22 Jul 2019 at 09:22pm +00, Holger Levsen wrote:
> > > I wonder how this was done for debian-policy which is also hosted on
> > > www.debian.org. Sean, do you have any insight on this?
> > Paul, Laura and Osamu hacked on the www-team's scripts until it worked
> > -- I'm afraid I wasn't involved other than reporting problems with the
> > published version of Policy, and I don't think we made changes to our
> > package in response to any requests from the www-team.
>
> Am I correct to assume we could go a similar way with src:developers-reference ?
Yes.
Only remaining problem is it builds multi-language outputs as packages
but not for web. I mean that the English files are available on
www.debian.org but translations don't show up as described in
https://www.debian.org/intro/cn This is because all html files are
names as index.html etc. without language code, so automatic language
selection can not be implemented.
We can do 2 ways.
Option 1:
~~~~~~~~~
This approach was deployed for "The Debian Administrator's Handbook"
https://www.debian.org/doc/user-manuals#debian-handbook
I wrote a sed script to change internal reference URLs while adding
language code to html filename extensions. This script is run by cron
script when binary packages are unpacked and unpacked files are
installed.
I know it works but i18n via https://www.debian.org/intro/cn is not as
friendly as menu-driven selection as below.
Option 2:
~~~~~~~~~
I am looking for i18n web page like:
https://docs.python.org/3/
https://docs.python.org/3/library/index.html
https://docs.python.org/3/reference/index.html
where language can be selected via pull down menu.
These seem to be built via sphinx-doc. So this native sphinx i18n
approach seems to be better option than option 1 which use intrusive and
fragile sed script.
If I figure how to set up option2 type i18n web page, I may even do it
for debian-handbook.
> If you wanted, you could test by cloning the git repo, install the
> build-depends and run 'make'. The package build is still broken...
Yah... that part is easy.
Osamu
Reply to: