From julien at palard.fr  Thu Jun  4 19:12:33 2020
From: julien at palard.fr (Julien Palard)
Date: Thu, 04 Jun 2020 23:12:33 +0000
Subject: [Doc-SIG] Moving language and version switchers out of cpython
Message-ID: <7e479b43-0fc6-2172-3a57-8658460eb993@palard.fr>

Hi doc-sig and release managers,

I'd like the simplify the maintenance of the language and version 
switchers of docs.python.org.

The current implementation lies in cpython's 
Doc/tools/static/switchers.js, witch contains a hardcoded list of 
languages and versions (that has to be updated on each new release and 
each new language, and backported in multiple branches).

It can be enhanced by a clearer separation:

- cpython Doc/ would build a simple standalone documentation, without 
switchers.
- docsbuild-script would be responsible to add the switchers.


Pro: We do no longer need to keep an up-to-date list of languages and 
version in all cpython branches, a single commit in docsbuild-scripts 
would update all switchers.

Con: Maybe, somewhere, someone is building a private version of 
docs.python.org, without docsbuild-script, and will be sad to see the 
switchers disapear. The probablility is low as they would have to have 
the same URLs as us (/{language}/{version}/), the same languages, and 
the same versions build, as all is imposed by switchers.js.

I opened an issue [1] and a draft PR [2] to experiment around the idea, 
there's still some work to do, but I have to sleep.

What do you think?

[1]: https://github.com/python/docsbuild-scripts/issues/90
[2]: https://github.com/python/docsbuild-scripts/pull/91
-- 
[Julien Palard](https://mdk.fr)


From nad at python.org  Fri Jun  5 02:44:34 2020
From: nad at python.org (Ned Deily)
Date: Fri, 5 Jun 2020 02:44:34 -0400
Subject: [Doc-SIG] Moving language and version switchers out of cpython
In-Reply-To: <7e479b43-0fc6-2172-3a57-8658460eb993@palard.fr>
References: <7e479b43-0fc6-2172-3a57-8658460eb993@palard.fr>
Message-ID: <EAF81993-F42A-4F87-AB00-19AE10FF7FE3@python.org>

On Jun 4, 2020, at 19:12, Julien Palard <julien at palard.fr> wrote:
> It can be enhanced by a clearer separation:
> 
> - cpython Doc/ would build a simple standalone documentation, without 
> switchers.
> - docsbuild-script would be responsible to add the switchers.

I like this idea a lot.  It's a pain to have update each branch's
switcher and then they eventually go out-of-date.

> Pro: We do no longer need to keep an up-to-date list of languages and 
> version in all cpython branches, a single commit in docsbuild-scripts 
> would update all switchers.
> 
> Con: Maybe, somewhere, someone is building a private version of 
> docs.python.org, without docsbuild-script, and will be sad to see the 
> switchers disapear. The probablility is low as they would have to have 
> the same URLs as us (/{language}/{version}/), the same languages, and 
> the same versions build, as all is imposed by switchers.js.

As far as I'm aware, all of the docssets produced by release managers
and binary builders (to be packaged in binary installers) are always
just for a single version in English.  So none use the switcher today.

I'm not sure what you are suggesting replacing the index sidebar with
for the standalone build.  But perhaps rather than the current links to
and status of recent branches, it could have a few generic links to
the docs on the website, something like:

stable -> https://docs.python.org/
in development -> https://docs.python.org/dev/
all versions -> https://www.python.org/doc/versions/
more resources -> https://www.python.org/doc/

--
  Ned Deily
  nad at python.org -- []


From julien at palard.fr  Sat Jun  6 09:08:47 2020
From: julien at palard.fr (Julien Palard)
Date: Sat, 06 Jun 2020 13:08:47 +0000
Subject: [Doc-SIG] Moving language and version switchers out of cpython
In-Reply-To: <EAF81993-F42A-4F87-AB00-19AE10FF7FE3@python.org>
References: <7e479b43-0fc6-2172-3a57-8658460eb993@palard.fr>
 <EAF81993-F42A-4F87-AB00-19AE10FF7FE3@python.org>
Message-ID: <891e0374-e8fd-36ac-d846-c47798997d53@palard.fr>

Hi,

> I like this idea a lot.  It's a pain to have update each branch's
> switcher and then they eventually go out-of-date.

The current implementation is working for me \o/ : 
https://github.com/python/docsbuild-scripts/pull/91

If anyone want to review, it would be appreciated, I'll merge it later.

> I'm not sure what you are suggesting replacing the index sidebar with
> for the standalone build.  But perhaps rather than the current links to
> and status of recent branches, it could have a few generic links to
> the docs on the website, something like:
> 
> stable -> https://docs.python.org/
> in development -> https://docs.python.org/dev/
> all versions -> https://www.python.org/doc/versions/
> more resources -> https://www.python.org/doc/

I had no idea... I'll take those links, they look great! Thanks!

-- 
[Julien Palard](https://mdk.fr)