[dpdk-dev,v2] doc: change sphinx theme to the read the docs theme

  Change the Sphinx default theme from "alabaster" to the ReadTheDocs
theme. See for example:

    http://dpdk.readthedocs.org/en/latest/

This looks better for technical documentation and in particular
it has a 80 char wide verbatim block rendering.

Also turn off option for distracting Html mouseover permalinks.

Signed-off-by: John McNamara <john.mcnamara@intel.com>
---

v2:
* Add version check since rtd theme is only available, by default,
  in Sphinx 1.3.1 and later.

 doc/guides/conf.py | 4 ++++
 1 file changed, 4 insertions(+)
  

> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of John McNamara
> Sent: Wednesday, October 21, 2015 10:39 AM
> To: dev@dpdk.org
> Subject: [dpdk-dev] [PATCH v2] doc: change sphinx theme to the read the docs theme
> 
> Change the Sphinx default theme from "alabaster" to the ReadTheDocs
> theme. See for example:
> 
>     http://dpdk.readthedocs.org/en/latest/
> 
> This looks better for technical documentation and in particular
> it has a 80 char wide verbatim block rendering.
> 
> Also turn off option for distracting Html mouseover permalinks.
> 
> Signed-off-by: John McNamara <john.mcnamara@intel.com>

Acked-by: Harry van Haaren <harry.van.haaren@intel.com>
  

2015-10-21 10:39, John McNamara:
> Change the Sphinx default theme from "alabaster" to the ReadTheDocs
> theme. See for example:
> 
>     http://dpdk.readthedocs.org/en/latest/
> 
> This looks better for technical documentation and in particular
> it has a 80 char wide verbatim block rendering.

Yes it is a clean theme.
It would be nice to add the DPDK logo somewhere.

> Also turn off option for distracting Html mouseover permalinks.
[...]
> +html_add_permalinks = ""

I think the permalinks are very useful to point a specific doc chapter
to someone else.
  

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Monday, October 26, 2015 2:34 PM
> To: Mcnamara, John
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH v2] doc: change sphinx theme to the read
> the docs theme
> 
> 2015-10-21 10:39, John McNamara:
> > Change the Sphinx default theme from "alabaster" to the ReadTheDocs
> > theme. See for example:
> >
> >     http://dpdk.readthedocs.org/en/latest/
> >
> > This looks better for technical documentation and in particular it has
> > a 80 char wide verbatim block rendering.
> 
> Yes it is a clean theme.
> It would be nice to add the DPDK logo somewhere.

Hi,

I'll submit a V3 with a logo for the html and pdf docs.

Note, the SVG logos are quite big (2 are required) and converting them to pdf for the Latex pdf docs requires another addition to the makefiles. This is a case where the patch would be smaller and simpler with PNG files and where the images are unlikely to require editing.


> > Also turn off option for distracting Html mouseover permalinks.
> [...]
> > +html_add_permalinks = ""
> 
> I think the permalinks are very useful to point a specific doc chapter to
> someone else.


It is just as easy to get a link to a subsection from the index. The permalinks are distracting because they blink on and off when scrolling through the docs. Also, I doubt more than a handful of people will know what the permalinks in the Html docs are.

Anyway, I'll remove this part from the patch and submit it separately. If there is any support for it the patch can be applied, if not then you can reject it.

John.
--
  

2015-11-01 16:41, Mcnamara, John:
> I'll submit a V3 with a logo for the html and pdf docs.
> 
> Note, the SVG logos are quite big (2 are required) and converting them to pdf for the Latex pdf docs requires another addition to the makefiles. This is a case where the patch would be smaller and simpler with PNG files and where the images are unlikely to require editing.

Yes the logo files are huge and mainly binary data.
There is no interest in importing them in git until they are real vector images.
I'm in favor of importing a PNG with a reasonable resolution.
  

> -----Original Message-----
> From: Thomas Monjalon [mailto:thomas.monjalon@6wind.com]
> Sent: Sunday, November 1, 2015 6:37 PM
> To: Mcnamara, John
> Cc: dev@dpdk.org
> Subject: Re: [dpdk-dev] [PATCH v2] doc: change sphinx theme to the read
> the docs theme
> 
> 2015-11-01 16:41, Mcnamara, John:
> > I'll submit a V3 with a logo for the html and pdf docs.
> >
> > Note, the SVG logos are quite big (2 are required) and converting them
> to pdf for the Latex pdf docs requires another addition to the makefiles.
> This is a case where the patch would be smaller and simpler with PNG files
> and where the images are unlikely to require editing.
> 
> Yes the logo files are huge and mainly binary data.
> There is no interest in importing them in git until they are real vector
> images.
> I'm in favor of importing a PNG with a reasonable resolution.

Ok. I'll resubmit with 2 png logos.

John.
--