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.

Hello,

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 wrote:

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,

Hello,

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.

I wrote a basic CSS file to overwrite the used theme (called
'nature'). The colors fit better the debian style.
A patch is available in the merge request:
https://salsa.debian.org/holgerw/release-notes/-/merge_requests/4

The CSS file is also attached to this email. It must be copied in
_static directory.
The following line has to be added to conf.py:
html_css_files = ['debian.css']

A screenshot is attached to this email too.

Pro:
- easy to setup

Con:
- Not responsive to small screens. To be responsive, the way to
display the menu must be modified. The problem already exists in the
'nature' theme. So we could change the default theme or fix it
upstream if doable.
- The title and subtitles are less readable to me (black on
transparent red) than the current style in the release notes (red on
white background). It should be easy to change.

What do you think about it?

In the long term, perhaps it should be packaged like
python3-sphinx-rtd-theme or python3-pallets-sphinx-themes to
synchronize the style between the documentation using Sphinx.

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 Blondon <stephane.blondon@gmail.com> writes:

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.

Hi Russ,

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

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!

Hello Stéphane,

Thank you for working on this.  A couple of things I have written in my
notes, from years ago, on this topic:

- it would be good for footnote references to stand out more than they
  do at present.  I think your theme achieves this.

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

Thanks again.

    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.

Le ven. 3 nov. 2023 à 15:43, Sam Hartman <hartmans@debian.org> a écrit :
You can test it at:
http://stephane.yaal.fr/tmp/policy/

Regards

    Stéphane> Le ven. 3 nov. 2023 à 15:43, Sam Hartman
    Stéphane> <hartmans@debian.org> a écrit :
    >> >>>>> "Sean" == Sean Whitton <spwhitton@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.

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

Hello,

This doesn't seem to be enough to ensure that debian.css gets installed
to the .deb.  I think we might also need to set html_static_path ?

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.

[ Hrrr, I sent this to the wrong bug #1059730; so resending to the correct
one #915583 for completeness ]


Holger Wansing <hwansing@mailbox.org> wrote (Sun, 31 Dec 2023 10:02:29 +0100):
[...]
They look really good indeed.
Especially how the menu/sidebar is shown/not shown on small screens
(smartphones) is fine, that was an open point in my proposal :-)

BTW: I think it would be good to have the 'Next'/'Previous' buttons
at the top additionally to those at the bottom.
The theme supports this via a config option. Simply set

	html_theme_options = {
		# To get previous/next buttons at the top and the bottom:
		'prev_next_buttons_location': 'both'
	}

in conf.py.in.


Holger

Thanks you but it's more a good work by readthedoc theme than me. ^^

It's a good idea.
The interface is visible in the screenshot attached to this message.

Hello,

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

Sean Whitton <spwhitton@spwhitton.name> wrote:

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

Hello,

Attached is the patch I prepared, which I couldn't get to work.  Maybe
you can see what is wrong.  Thanks!

---
 debian/changelog  |   3 ++
 debian/control    |   1 +
 policy/conf.py.in |   5 ++-
 policy/debian.css | 103 ++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 111 insertions(+), 1 deletion(-)
 create mode 100644 policy/debian.css

diff --git a/debian/changelog b/debian/changelog
index ffa0f8b..6d04491 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -14,6 +14,9 @@ debian-policy (4.6.2.1) UNRELEASED; urgency=medium
       package metadata.
   * Update Installed-Size algorithm used by dpkg (Closes: #793499).

+  [ Stéphane Blondon ]
+  * New Debian-specific Sphinx style (Closes: #915583).
+
  -- Russ Allbery <rra@debian.org>  Sat, 09 Sep 2023 15:27:27 -0700

 debian-policy (4.6.2.0) unstable; urgency=medium
diff --git a/debian/control b/debian/control
index a98b425..ebb3c3f 100644
--- a/debian/control
+++ b/debian/control
@@ -17,6 +17,7 @@ Build-Depends:
  libxml2-utils,
  links | elinks,
  python3-sphinx,
+ python3-sphinx-rtd-theme,
  sphinx-common (>= 1.6.5),
  sphinx-intl,
  texinfo,
diff --git a/policy/conf.py.in b/policy/conf.py.in
index d516d7b..86bc1ac 100755
--- a/policy/conf.py.in
+++ b/policy/conf.py.in
@@ -84,7 +84,7 @@ todo_include_todos = False
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'nature'
+html_theme = 'sphinx_rtd_theme'

 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -92,6 +92,9 @@ html_theme = 'nature'
 #
 # html_theme_options = {}

+# Overwrite theme to fit Debian colors
+html_css_files = ['debian.css']
+
 # Override the title to remove the unnecessary "documentation" suffix.
 html_title = "Debian Policy Manual v@VERSION@"

diff --git a/policy/debian.css b/policy/debian.css
new file mode 100644
index 0000000..7f0981b
--- /dev/null
+++ b/policy/debian.css
@@ -0,0 +1,103 @@
+/* Debian Cascading stylesheet for Sphinx */
+
+div.related {
+    background-color: #C70036;
+}
+
+.rst-content h1, .rst-content h2, .rst-content h3, .rst-content h4, .rst-content h5, .rst-content h6 {
+    color: #C70036;
+}
+
+.wy-nav-top {
+    background-color: #C70036;
+}
+
+.wy-side-nav-search {
+    background-color: #C70036;
+}
+
+.rst-content a:link {
+    color: #0035C7;
+    text-decoration: none;
+}
+.rst-content a:visited {
+    color: #00207A;
+    text-decoration: none;
+}
+.rst-content a:link:hover {
+    color: #00207A;
+    text-decoration: underline;
+}
+
+
+/* Table in content */
+
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}
+
+.rst-content table.docutils, .wy-table-bordered-all {
+    width: 100%;
+}
+
+.wy-table-responsive table.docutils thead tr {
+    background-color: #C70036;
+    border: 1px solid black;
+    color: black;
+}
+
+.wy-table-responsive table.docutils thead tr:hover {
+    color: #fcfcfc;
+}
+
+.wy-table-responsive table.docutils tbody tr:hover {
+    background-color:#666666;
+    color: #FFFFFF;
+}
+
+.rst-content table.docutils:not(.field-list) tbody tr:hover:nth-child(2n-1), .wy-table-backed, .wy-table-odd td, .wy-table-striped tr:nth-child(2n-1) td {
+    background-color:#666666;
+}
+
+/* Previous and next buttons */
+
+.rst-footer-buttons .btn:hover {
+    text-decoration: none !important;
+}
+
+/* Version release more readable */
+
+.wy-side-nav-search > div.version {
+    color: #FCFCFC;
+}
+
+/* Infos blocks */
+
+div.warning {
+    border: 1px dashed #EFF500;
+    background-color: #eff50030;
+}
+
+div.note {
+    border: 1px dashed blue;
+    background-color: #0000ff30;
+
+}
+
+.warning, .note {
+    margin-left: 1em;
+    margin-right: 1em;
+}
+
+@media (max-width: 5in), (max-device-width: 5in){
+    .warning, .note {
+        margin-left: 0.5em;
+        margin-right: 0.5em;
+    }
+}
+
+/* Notes */
+
+html.writer-html5 .rst-content aside.citation, html.writer-html5 .rst-content aside.footnote, html.writer-html5 .rst-content div.citation {
+    display: block;
+}
-- 
Sean Whitton

Hi Sean,

Sean Whitton <spwhitton@spwhitton.name> wrote (Sat, 24 Feb 2024 11:58:59 +0800):
And activate (un-comment) the path declaration for that in line 105 of conf.py.in.

Additionally, as I already wrote somewhere, for navigating it would be good
to have the Next/Previous buttons at the top of the page as well, not only
at the bottom.

And: do we want to have the
	"Built with Sphinx using a theme provided by Read the Docs."
in the footer? If not, that could be suppressed by
	html_show_sphinx = False
in conf.py.in.


My diff for conf.py.in would be like this (with above suggestions):

diff --git a/policy/conf.py.in b/policy/conf.py.in
index d516d7b..4ea4df6 100755
--- a/policy/conf.py.in
+++ b/policy/conf.py.in
@@ -84,13 +84,19 @@ todo_include_todos = False
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'nature'
+html_theme = 'sphinx_rtd_theme'

 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {
+       # To get previous/next buttons at the top and the bottom:
+       'prev_next_buttons_location': 'both'
+}
+
+# Overwrite theme to fit Debian colors
+html_css_files = ['debian.css']

 # Override the title to remove the unnecessary "documentation" suffix.
 html_title = "Debian Policy Manual v@VERSION@"
@@ -98,11 +104,14 @@ html_title = "Debian Policy Manual v@VERSION@"
 # Suppress the copyright notice.
 html_show_copyright = False

+# Hide “Created using Sphinx” in the HTML footer
+html_show_sphinx = False
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 #
-# html_static_path = ['_static']
+html_static_path = ['_static']


 # -- Options for HTMLHelp output ------------------------------------------



Best regards
Holger

control: tag -1 + pending

Hello,

Thank you very much, both -- now merged for the next upload.

We believe that the bug you reported is fixed in the latest version of
debian-policy, which is due to be installed in the Debian FTP archive.

A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 915583@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Sean Whitton <spwhitton@spwhitton.name> (supplier of updated debian-policy package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)
Format: 1.8
Date: Sat, 24 Feb 2024 20:39:43 +0800
Source: debian-policy
Architecture: source
Version: 4.6.2.1
Distribution: unstable
Urgency: medium
Maintainer: Debian Policy Editors <debian-policy@lists.debian.org>
Changed-By: Sean Whitton <spwhitton@spwhitton.name>
Closes: 793499 915583 1020248 1031403
Changes:
 debian-policy (4.6.2.1) unstable; urgency=medium
 .
   [ Guillem Jover ]
   * Standardize terminology with dpkg.  (Closes: #1020248)
     - Use 'stanza' for each section of a multi-section control file, such as
       the source package template control file (debian/control).
     - Use standardized naming for binary package control files, source
       package control files (.dsc), source package template control files
       (debian/control), and upload changes control files (.changes).
     - Refer to members of the control member of the .deb archive as
       'package metadata'.
   * Update Installed-Size algorithm used by dpkg (Closes: #793499).
 .
   [ Stéphane Blondon ]
   * New Debian-specific Sphinx style (Closes: #915583).
 .
   [ Max-Julian Pogner ]
   * Fix missing quotes in dpkg-divert examples. (Closes: #1031403)
Checksums-Sha1:
 1ca66544071b0942fdbd0f2fc155ff98e0794349 2136 debian-policy_4.6.2.1.dsc
 0194a75ba91649127927fc24df894f4c2e8740c6 554296 debian-policy_4.6.2.1.tar.xz
Checksums-Sha256:
 fc4f8728464f039ab2ff9063d28a9538e92cb68605d980ac608689306bfc80b6 2136 debian-policy_4.6.2.1.dsc
 0a69d1e25d821e6eb1e1773f4a8626ecdf2abf23ce50d0ba4e90208fd67052a3 554296 debian-policy_4.6.2.1.tar.xz
Files:
 9907e689604584693d5494d3133e71e0 2136 doc optional debian-policy_4.6.2.1.dsc
 d40f37ab7ab1b736b65844669a5baf01 554296 doc optional debian-policy_4.6.2.1.tar.xz
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEEm5FwB64DDjbk/CSLaVt65L8GYkAFAmXZ48MACgkQaVt65L8G
YkCORQ/8D0vQa4AKBnKAmJd8QFrjbKMqSTphLlcq2kCaXnNEtTz0mtZ4YMQd+4lh
ce8J6/qOYarhkBSCvz//cb1WMDUXt4M9l0NoOMcw6rZHxzkUf315O8NLjktM0D52
/+HhdgMmE9IhzOqohNvmB/DiCogqfLQvKRswKdbr0FNIbeqv8CJAYZdatgoBIZVJ
zkpub9K3EM1tY3V5aRWi6rPj5QQIE0yMF1v+MP5aQc8cyTeE3YwPH1iAOJwgSUgE
CSBQqzYU1MgLVYipvVCp6at44Mpj32spUAOjXBxUGVfstR0lYzk6Q6y7nQwEb+rl
eFWkmSuY5ynkNAV1H4xvS4PVPFSHQU336cuUecc3c0TSynQ9fAi8tRfPgEW1UT87
mUmj8yjy8aSslv/Yhsb6/yULIJS0np01RXI4pBaTpu6CU2oVbtHJVW+Hcc4VKC7P
l5iN4CAV0wn8UqEXJPTd3TibtBlN0CbnfUIA6/ZxQq3CwI5OHp00PLPTHSoOEQe7
ZiurbnAAyI9Dlrn+lkUFMPF3ukeq6EaVelze/QMEB6BWP0ZAni7qWZKACaasuUkm
f/t+pWpVyZQx7CegSi2DGRnjsLD+wi2ylYu3GDvogrNR92I+kMgYOtX/PvSgJ904
FF3zt3K0ZNcsEkso456N/3Zcbp9/iwtxC6Pwtt2aLO5CdKj4QKU=
=9HMh
-----END PGP SIGNATURE-----