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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-Id: <9E01B339-15E5-4640-8B07-7309FA5E23B5@darmarit.de>
Date:	Mon, 11 Jul 2016 19:42:54 +0200
From:	Markus Heiser <markus.heiser@...marit.de>
To:	Mauro Carvalho Chehab <mchehab@....samsung.com>,
	Jonathan Corbet <corbet@....net>
Cc:	Hans Verkuil <hverkuil@...all.nl>,
	Daniel Vetter <daniel.vetter@...ll.ch>,
	Airlie <airlied@...il.com>, Likely <grant.likely@...retlab.ca>,
	Dunlap <rdunlap@...radead.org>, Packard <keithp@...thp.com>,
	linux-doc@...r.kernel.org,
	"linux-kernel@...r.kernel.org List" <linux-kernel@...r.kernel.org>,
	Laurent Pinchart <laurent.pinchart@...asonboard.com>
Subject: Re: [RFC PATCH 0/3] doc-rst: customize HTML (RTD) theme


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

> Em Sat, 9 Jul 2016 23:22:22 -0600
> Jonathan Corbet <corbet@....net> escreveu:
> 
>> On Tue, 5 Jul 2016 14:55:09 -0300
>> Mauro Carvalho Chehab <mchehab@....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