Bug#915583: debian-policy: More attractive sphinx theme, please

[Hideki Yamane]

package: debian-policy
severity: wishlist

Hi,

Maybe more eye-candy theme (see https://sphinx-themes.org/) is good for
policy-doc and other debian docs, we can create theme for debian-policy
and share between debian docs.


--
Hideki Yamane <hen...@iijmio-mail.jp>

[Sean Whitton]

Hello,

On Wed 05 Dec 2018 at 11:15AM +0900, Hideki Yamane wrote:

> Maybe more eye-candy theme (see https://sphinx-themes.org/) is good for
> policy-doc and other debian docs, we can create theme for debian-policy
> and share between debian docs.

Yup. We put out a call for this as soon as we switched to Sphinx[1] and
it was included in Debian Project News.[2] Maybe filing this bug will
cause someone who's interested to notice -- thanks!

[1] https://lists.debian.org/debian-devel-announce/2017/08/msg00007.html
[2] https://www.debian.org/News/weekly/2017/03/#help

--
Sean Whitton

[Chris Lamb]

Sean Whitton wrote:

> > Maybe more eye-candy theme (see https://sphinx-themes.org/) is good for

> > policy-doc and other debian docs [..]

>
> Yup. We put out a call for this as soon as we switched to Sphinx[1] and
> it was included in Debian Project News.[2]

Did you hear anything on this?

(+1 for a "Debian" Sphinx theme. I am sure there are many other
tools that would benefit from such a thing.)


Best wishes,

--
,''`.
: :' : Chris Lamb
`. `'` la...@debian.org 🍥 chris-lamb.co.uk
`-

[Sean Whitton]

Hello,

On Thu 24 Jan 2019 at 05:08PM +01, Chris Lamb wrote:

> Sean Whitton wrote:
>
>> > Maybe more eye-candy theme (see https://sphinx-themes.org/) is good for
>> > policy-doc and other debian docs [..]
>>
>> Yup. We put out a call for this as soon as we switched to Sphinx[1] and
>> it was included in Debian Project News.[2]
>
> Did you hear anything on this?
>
> (+1 for a "Debian" Sphinx theme. I am sure there are many other
> tools that would benefit from such a thing.)

Nothing yet.

Since things like dev-ref will probably switch to Sphinx to someday,
it would indeed be really cool to have a Debian theme.

--
Sean Whitton

[Stéphane Blondon]

Hello,

I've done a new version. It's based on 'sphinx_rtd_theme' theme. So,
to build the site, the package 'python3-sphinx-rtd-theme' requires to
be added to dependencies. A new file 'debian.css' is specific to set
some colors and renderings.

Reusing 'Read the docs' theme allows to have a responsive design automatically.

The theme could be modified more but it could be considered as a first
step which is already usable.

There are temporary demos available:
- for debian-policy: http://stephane.yaal.fr/tmp/policy/
- for (draft sphinx) release-notes: http://stephane.yaal.fr/tmp/release-notes/

What do you think about it?

--
Stéphane

[Russ Allbery]

Hi Stéphane,

Thank you so much for this! I poked around a little bit on your draft
render of Policy and personally I'm quite happy with it. The sidebar
management with small screens seemed to work for me and is definitely
better that what we have right now. I would encourage others to also take
a look and provide feedback. My inclination is to merge this in a future
release of Policy.

The one minor thing that I noticed was that the version number of Policy
in the left sidebar at the top is very difficult to read because it's
almost the same color as the background.

--
Russ Allbery (r...@debian.org) <https://www.eyrie.org/~eagle/>

[Stéphane Blondon]

Hi Russ,

> My inclination is to merge this in a future release of Policy.

I will clean the CSS file and add it to a new message to this bug
report to help the merge.

> The one minor thing that I noticed was that the version number of Policy
> in the left sidebar at the top is very difficult to read because it's
> almost the same color as the background.

You're right. I made a little patch on debian.css for improve it. It's
visible at http://stephane.yaal.fr/tmp/policy/

Other feedbacks are welcome!

--
Stéphane

[Sam Hartman]

>>>>> "Sean" == Sean Whitton <spwh...@spwhitton.name> writes:

Sean> - it would be good to do some accessibility testing of some
Sean> kind, at least with screenreaders. But maybe the fact that
Sean> you've based your theme on an existing, popular Sphinx theme
Sean> means this is covered?

I'm happy to test with Orca on Firefox on Debian.
Feel free to point me at a URL.

[Stéphane Blondon]

You can test it at:

http://stephane.yaal.fr/tmp/policy/

Regards

[Sam Hartman]

>>>>> "Stéphane" == Stéphane Blondon <stephane...@gmail.com> writes:

Stéphane> Le ven. 3 nov. 2023 à 15:43, Sam Hartman
Stéphane> <hart...@debian.org> a écrit :

>> >>>>> "Sean" == Sean Whitton <spwh...@spwhitton.name> writes:
>>
>> I'm happy to test with Orca on Firefox on Debian. Feel free to
>> point me at a URL.
>>

Stéphane> You can test it at: http://stephane.yaal.fr/tmp/policy/

Given a quick look, appears okay to me.

[Stéphane Blondon]

Hello,

the attached file (debian.css) sets up the custom style.

In order to work:
- add the 'python3-sphinx-rtd-theme' package to the dependencies
- in `conf.py.in`, replace:
html_theme = 'nature'
by
html_theme = 'sphinx_rtd_theme'

The generated conf.py file must contain:
# Overwrite theme to fit Debian colors
html_css_files = ['debian.css']


Please tell me if it does not work because I made several workarounds
in order to get it work without everything properly
installed/configured.

Cheers
--
Stéphane

[Stéphane Blondon]

Yes, html_static_path must be set but it's already the case in conf.py.in:
https://sources.debian.org/src/debian-policy/4.6.2.0/policy/conf.py.in/#L105

I guess conf.py is generated from conf.py.in so we only need to keep
the current setup.

--
Stéphane

[Holger Wansing]

Sean Whitton <spwh...@spwhitton.name> wrote:

> That line is commented out, though. Are you saying it takes on its
> default value in that case?

I think it would be good to un-comment such lines which are needed, so it's
clear without doubt, what is used and active.
Works fine here BTW.


Holger

--
Holger Wansing <hwan...@mailbox.org>
PGP-Fingerprint: 496A C6E8 1442 4B34 8508 3529 59F1 87CA 156E B076