Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1435955 > unrolled thread

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

Back to article view | Back to linux.kernel

Contents

  [RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme Markus Heiser <markus.heiser@darmarit.de> - 2016-07-03 14:30 +0200
    [RFC PATCH 2/3] doc-rst: customize RTD theme, table & full width Markus Heiser <markus.heiser@darmarit.de> - 2016-07-03 14:30 +0200
    Re: [RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-05 20:00 +0200
      Re: [RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme Jonathan Corbet <corbet@lwn.net> - 2016-07-10 07:30 +0200
        Re: [RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-07-10 12:10 +0200
          Re: [RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme Markus Heiser <markus.heiser@darmarit.de> - 2016-07-11 19:50 +0200

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

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

[toc] | [next] | [standalone]

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

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

[toc] | [prev] | [next] | [standalone]

#1437215

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

[toc] | [prev] | [next] | [standalone]

#1440034

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

[toc] | [prev] | [next] | [standalone]

#1440069

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

[toc] | [prev] | [next] | [standalone]

#1440794

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

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web