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@xxxxxxxxxxxxxxx>:

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

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