[RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme

[RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme

[Markus Heiser]

From: Markus Heiser <markus.heiser@darmarIT.de>

The default layout of the RTD HTML theme has some tweaks, discussed in the
linux-doc ML [1][2].

This series adds a boilerplate to customize HTML themes and it fix the tweaks
(mainly) for tables, captions and inline literals.

Since there is no (vast) table in Jon's docs-next yet, this RFC has to be tested
with Mauro's docs-next branch which includes the linux_tv doc (see chapter
"Media Bus Formats" for vast tables). If you don't like merge it all just for a
test, pull it from my linux_tv_migration branch at:

  https://github.com/return42/linux.git linux_tv_migration

Any comments are welcome

  -- Markus --

[1] http://article.gmane.org/gmane.linux.kernel/2216509
[2] http://article.gmane.org/gmane.linux.drivers.video-input-infrastructure/101099


Markus Heiser (3):
  doc-rst: boilerplate HTML theme customization
  doc-rst: customize RTD theme, table & full width
  doc-rst: customize RTD theme, captions & inline literal

 Documentation/conf.py                           |  9 ++++-
 Documentation/sphinx-static/theme_overrides.css | 53 +++++++++++++++++++++++++
 2 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/sphinx-static/theme_overrides.css

-- 
docs-next/sphinx-4.8

[RFC PATCH 1/3] doc-rst: boilerplate HTML theme customization

[Markus Heiser]

From: Markus Heiser <markus.heiser@darmarIT.de>
To: Jonathan Corbet <corbet@lwn.net>
To: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Cc: Hans Verkuil <hverkuil@xs4all.nl>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Airlie <airlied@gmail.com>
Cc: Likely <grant.likely@secretlab.ca>
Cc: Dunlap <rdunlap@infradead.org>
Cc: Packard <keithp@keithp.com>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org

Implements the minimal boilerplate for Sphinx HTML theme customization.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
---
 Documentation/conf.py                           | 9 ++++++++-
 Documentation/sphinx-static/theme_overrides.css | 9 +++++++++
 2 files changed, 17 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/sphinx-static/theme_overrides.css

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 792b633..f35748b 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -176,7 +176,14 @@ except ImportError:
 # 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 = ['sphinx-static']
+
+html_context = {
+    'css_files': [
+        '_static/theme_overrides.css',
+    ],
+}
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
new file mode 100644
index 0000000..4d670db
--- /dev/null
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -0,0 +1,9 @@
+/* -*- coding: utf-8; mode: css -*-
+ *
+ * Sphinx HTML theme customization
+ *
+ */
+
+@media screen {
+
+}
-- 
docs-next/sphinx-4.8

[RFC PATCH 2/3] doc-rst: customize RTD theme, table & full width

[Markus Heiser]

From: Markus Heiser <markus.heiser@darmarIT.de>
To: Jonathan Corbet <corbet@lwn.net>
To: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Cc: Hans Verkuil <hverkuil@xs4all.nl>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Airlie <airlied@gmail.com>
Cc: Likely <grant.likely@secretlab.ca>
Cc: Dunlap <rdunlap@infradead.org>
Cc: Packard <keithp@keithp.com>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org

The default table layout of the RTD theme does not fit for vast tables,
like the ones we have in the linux_tv project. This has been discussed
on the ML [1].

The RTD theme is a two column layout, with a navigation column on the
left and a content column on the right:

content column

 RTD theme's default is 800px as max width for the content, but we have
 tables with tons of columns, which need the full width of the
 view-port (BTW: *full width* is what DocBook's HTML is).

table

   - sequences of whitespace should collapse into a single whitespace.
   - make the overflow auto (scrollbar if needed)
   - align caption "left" ("center" is unsuitable on vast tables)

[1] http://article.gmane.org/gmane.linux.kernel/2216509

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
---
 Documentation/sphinx-static/theme_overrides.css | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index 4d670db..ea06799 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -1,9 +1,28 @@
 /* -*- coding: utf-8; mode: css -*-
  *
- * Sphinx HTML theme customization
+ * Sphinx HTML theme customization: read the doc
  *
  */
 
 @media screen {
 
+    /* content column
+     *
+     * RTD theme's default is 800px as max width for the content, but we have
+     * tables with tons of columns, which need the full width of the view-port.
+     */
+
+    .wy-nav-content{max-width: none; }
+
+    /* table:
+     *
+     *   - Sequences of whitespace should collapse into a single whitespace.
+     *   - make the overflow auto (scrollbar if needed)
+     *   - align caption "left" ("center" is unsuitable on vast tables)
+     */
+
+    .wy-table-responsive table td { white-space: normal; }
+    .wy-table-responsive { overflow: auto; }
+    .rst-content table.docutils caption { text-align: left; font-size: 100%; }
+
 }
-- 
docs-next/sphinx-4.8

[RFC PATCH 3/3] doc-rst: customize RTD theme, captions & inline literal

[Markus Heiser]

From: Markus Heiser <markus.heiser@darmarIT.de>
To: Jonathan Corbet <corbet@lwn.net>
To: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Cc: Hans Verkuil <hverkuil@xs4all.nl>
Cc: Daniel Vetter <daniel.vetter@ffwll.ch>
Cc: Airlie <airlied@gmail.com>
Cc: Likely <grant.likely@secretlab.ca>
Cc: Dunlap <rdunlap@infradead.org>
Cc: Packard <keithp@keithp.com>
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org

The layout of (table) captions in the RTD theme is a bit ugly and the
bordered, red colored of inline literals is a bit to gaudy. The
requirements has been discussed in the ML [1].

captions:

  - captions should have 100% (not 85%) font size
  - hide the permalink symbol as long as link is not hovered

inline literal:

  - drop the borderbox and red color

[1] http://article.gmane.org/gmane.linux.drivers.video-input-infrastructure/101099

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
---
 Documentation/sphinx-static/theme_overrides.css | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index ea06799..c97d842 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -25,4 +25,29 @@
     .wy-table-responsive { overflow: auto; }
     .rst-content table.docutils caption { text-align: left; font-size: 100%; }
 
+    /* captions:
+     *
+     *   - captions should have 100% (not 85%) font size
+     *   - hide the permalink symbol as long as link is not hovered
+     */
+
+    caption, .wy-table caption, .rst-content table.field-list caption {
+        font-size: 100%;
+    }
+    caption a.headerlink { opacity: 0; }
+    caption a.headerlink:hover { opacity: 1; }
+
+    /* inline literal: drop the borderbox and red color */
+
+    code, .rst-content tt, .rst-content code {
+        color: inherit;
+        border: none;
+        background: inherit;
+        font-size: 85%;
+    }
+
+    .rst-content tt.literal,.rst-content tt.literal,.rst-content code.literal {
+        color: inherit;
+    }
+
 }
-- 
docs-next/sphinx-4.8

Re: [RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme

[Mauro Carvalho Chehab]

Hi Jon,

I hope you don't mind. I'm merging those three patches on my tree
(for now, they're on an experimental tree that I can easily rebase, if
needed). If OK for you, my plan is to merge it on a separate branch,
together with the other patches for Documentation/linux_tv.

They actually apply outside Documentation/linux_tv, but are needed in order
to fix the display of the long tables we have at the media doc.

If you want to take a look of the patches I'm adding there, they're all
at:
	https://git.linuxtv.org//mchehab/experimental.git/log/?h=docs-next
(please notice that I rebase this tree from time to time, as needed).

Regards,
Mauro


Em Sun,  3 Jul 2016 14:24:52 +0200
Markus Heiser <markus.heiser@darmarit.de> escreveu:

> From: Markus Heiser <markus.heiser@darmarIT.de>
> 
> The default layout of the RTD HTML theme has some tweaks, discussed in the
> linux-doc ML [1][2].
> 
> This series adds a boilerplate to customize HTML themes and it fix the tweaks
> (mainly) for tables, captions and inline literals.
> 
> Since there is no (vast) table in Jon's docs-next yet, this RFC has to be tested
> with Mauro's docs-next branch which includes the linux_tv doc (see chapter
> "Media Bus Formats" for vast tables). If you don't like merge it all just for a
> test, pull it from my linux_tv_migration branch at:
> 
>   https://github.com/return42/linux.git linux_tv_migration
> 
> Any comments are welcome
> 
>   -- Markus --
> 
> [1] http://article.gmane.org/gmane.linux.kernel/2216509
> [2] http://article.gmane.org/gmane.linux.drivers.video-input-infrastructure/101099
> 
> 
> Markus Heiser (3):
>   doc-rst: boilerplate HTML theme customization
>   doc-rst: customize RTD theme, table & full width
>   doc-rst: customize RTD theme, captions & inline literal
> 
>  Documentation/conf.py                           |  9 ++++-
>  Documentation/sphinx-static/theme_overrides.css | 53 +++++++++++++++++++++++++
>  2 files changed, 61 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/sphinx-static/theme_overrides.css
> 


-- 
Thanks,
Mauro

Re: [RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme

[Jonathan Corbet]

On Tue, 5 Jul 2016 14:55:09 -0300
Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:

> I hope you don't mind. I'm merging those three patches on my tree
> (for now, they're on an experimental tree that I can easily rebase, if
> needed). If OK for you, my plan is to merge it on a separate branch,
> together with the other patches for Documentation/linux_tv.

[Slowly trying to catch back up with the real world; service will
continue to be intermittent for a bit yet.]

So as far as I can tell, I never got part 1/3, not sure what happened
there.

In general, my only concern is that we haven't really begun the process
of debating the proper bikeshed^Wtheme for the kernel docs.  Which is
just fine.  At some point, we may want to think about it a bit more, but,
for now, there is certainly no harm in making what we have work better.
Please feel free to include these with your stuff with my acked-by.

Thanks,

jon

Re: [RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme

[Mauro Carvalho Chehab]

Em Sat, 9 Jul 2016 23:22:22 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue, 5 Jul 2016 14:55:09 -0300
> Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
> 
> > I hope you don't mind. I'm merging those three patches on my tree
> > (for now, they're on an experimental tree that I can easily rebase, if
> > needed). If OK for you, my plan is to merge it on a separate branch,
> > together with the other patches for Documentation/linux_tv.  
> 
> [Slowly trying to catch back up with the real world; service will
> continue to be intermittent for a bit yet.]
> 
> So as far as I can tell, I never got part 1/3, not sure what happened
> there.

Yeah, I didn't receive either. I got them from the Markus git tree.

> In general, my only concern is that we haven't really begun the process
> of debating the proper bikeshed^Wtheme for the kernel docs.  Which is
> just fine.  At some point, we may want to think about it a bit more, but,
> for now, there is certainly no harm in making what we have work better.

Yeah, at some time we'll need to discuss the theme. The theme we're
using is fine, but still there are some things that could be improved.

Btw, if you want to take a look on how it it looks like,
you could take a look at:
	https://linuxtv.org/downloads/v4l-dvb-apis-new/media/media_uapi.html

Right now (while we don't have an option to build just one book),
this is a complete build of the Sphinx documentation.

> Please feel free to include these with your stuff with my acked-by.

Ok, thanks! I actually merged it already on my main tree, on a
separate topic branch, together with the other patches that are
needed for the conversion:

	https://git.linuxtv.org/media_tree.git/log/?h=docs-next

The changes there include patches for a new book part (CEC) and
for the new entities needed by the vsp1 (both are also on separate
topic branches).

My plan is to send my docs-next topic branch after Linus pick from
your tree, and, at by end of the merge window, send a patch
removing Documentation/media/DocBook.

Regards,
Mauro

Re: [RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme

[Markus Heiser]

Am 10.07.2016 um 12:06 schrieb Mauro Carvalho Chehab <mchehab@osg.samsung.com>:

> Em Sat, 9 Jul 2016 23:22:22 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
>> On Tue, 5 Jul 2016 14:55:09 -0300
>> Mauro Carvalho Chehab <mchehab@osg.samsung.com> wrote:
>> 
>>> I hope you don't mind. I'm merging those three patches on my tree
>>> (for now, they're on an experimental tree that I can easily rebase, if
>>> needed). If OK for you, my plan is to merge it on a separate branch,
>>> together with the other patches for Documentation/linux_tv.  
>> 
>> [Slowly trying to catch back up with the real world; service will
>> continue to be intermittent for a bit yet.]
>> 
>> So as far as I can tell, I never got part 1/3, not sure what happened
>> there.
> 
> Yeah, I didn't receive either. I got them from the Markus git tree.

strange [1] ... but anyway, thanks for acked-by

[1] http://mid.gmane.org/1467548695-16403-2-git-send-email-markus.heiser@darmarit.de

>> In general, my only concern is that we haven't really begun the process
>> of debating the proper bikeshed^Wtheme for the kernel docs.  Which is
>> just fine.  At some point, we may want to think about it a bit more, but,
>> for now, there is certainly no harm in making what we have work better.
> 
> Yeah, at some time we'll need to discuss the theme. The theme we're
> using is fine, but still there are some things that could be improved.

Laurent mentioned javascript as "pain point" [2] and that the 
TOC depth is only one ...

[2] http://mid.gmane.org/1602772.oBh27pyGSf@avalon

I can't judge the importance of javascript / no javascript.

For the first, until we have more practical experience, my suggestion is:

We should support / customize only one theme, the RTD theme, which covers
most viewports as best.

If someone need something special, he could build it with a different theme.

 http://www.sphinx-doc.org/en/stable/theming.html#builtin-themes

But as far as I know, all themes make more or less use of javascript.
Independent from the theme, the search index needs always javascript.

-- Markus --

> Btw, if you want to take a look on how it it looks like,
> you could take a look at:
> 	https://linuxtv.org/downloads/v4l-dvb-apis-new/media/media_uapi.html
> 
> Right now (while we don't have an option to build just one book),
> this is a complete build of the Sphinx documentation.
> 
>> Please feel free to include these with your stuff with my acked-by.
> 
> Ok, thanks! I actually merged it already on my main tree, on a
> separate topic branch, together with the other patches that are
> needed for the conversion:
> 
> 	https://git.linuxtv.org/media_tree.git/log/?h=docs-next
> 
> The changes there include patches for a new book part (CEC) and
> for the new entities needed by the vsp1 (both are also on separate
> topic branches).
> 
> My plan is to send my docs-next topic branch after Linus pick from
> your tree, and, at by end of the merge window, send a patch
> removing Documentation/media/DocBook.
> 
> Regards,
> Mauro