UX Bug in Sphinx HTML Layout for Programming Guide (and maybe other guides?)

UX Bug in Sphinx HTML Layout for Programming Guide (and maybe other guides?)

[Matthew Hall]

When you go to this link:

http://dpdk.org/doc/guides/prog_guide/perf_opt_guidelines.html

There is a bug in the Sphinx layout, where the subchapters of a chapter are
invisible even after the chapter is clicked.

It is a pain when you are trying to figure out the different sections in a 
widely variable chapter like the performance chapter, to know which section to 
read without having to click one-by-one to find the right part.

I am not sure about what it would take to show the subchapters in the outline 
view to make this easier for someone to figure out. Or maybe a TOC for a 
chapter at the beginning of the chapter?

This would really help a lot.

Sincerely,
Matthew.

Re: UX Bug in Sphinx HTML Layout for Programming Guide (and maybe other guides?)

[Mcnamara, John]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Matthew Hall
> Sent: Wednesday, January 13, 2016 5:26 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] UX Bug in Sphinx HTML Layout for Programming Guide
> (and maybe other guides?)
> 
> When you go to this link:
> 
> http://dpdk.org/doc/guides/prog_guide/perf_opt_guidelines.html
> 
> There is a bug in the Sphinx layout, where the subchapters of a chapter
> are invisible even after the chapter is clicked.

Hi Matthew,

It seems to be an issue with the way the documentation section headings are
structured and with the new "ReadTheDocs" theme that we introduced for the
DPDK 2.2 documentation.

Basically, because the heading underline formats are not consistent they
don't show up as subsections in the sidebar. The previous themes used for
the docs were more forgiving about this.

In theory the subsections should show up. See this simplified example:

    http://imgur.com/qkgxGvX

I'll look into fixing it. 

In the meantime use the index.html pages of the various docs to navigate, e.g.

    http://dpdk.org/doc/guides/prog_guide/index.html

John.
-- 

Re: UX Bug in Sphinx HTML Layout for Programming Guide (and maybe other guides?)

[Mcnamara, John]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Matthew Hall
> Sent: Wednesday, January 13, 2016 5:26 PM
> To: dev@dpdk.org
> Subject: [dpdk-dev] UX Bug in Sphinx HTML Layout for Programming Guide
> (and maybe other guides?)
> 
> When you go to this link:
> 
> http://dpdk.org/doc/guides/prog_guide/perf_opt_guidelines.html
> 
> There is a bug in the Sphinx layout, where the subchapters of a chapter
> are invisible even after the chapter is clicked.

Hi Thomas,

I found the issue causing this and I'll submit a patch shortly.

If possible could you apply it a copy of the 2.2 code and rebuild the online docs.

John.
-- 
 

Re: UX Bug in Sphinx HTML Layout for Programming Guide (and maybe other guides?)

[Thomas Monjalon]

2016-01-15 16:23, Mcnamara, John:
> > -----Original Message-----
> > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Matthew Hall
> > Sent: Wednesday, January 13, 2016 5:26 PM
> > To: dev@dpdk.org
> > Subject: [dpdk-dev] UX Bug in Sphinx HTML Layout for Programming Guide
> > (and maybe other guides?)
> > 
> > When you go to this link:
> > 
> > http://dpdk.org/doc/guides/prog_guide/perf_opt_guidelines.html
> > 
> > There is a bug in the Sphinx layout, where the subchapters of a chapter
> > are invisible even after the chapter is clicked.
> 
> Hi Thomas,
> 
> I found the issue causing this and I'll submit a patch shortly.
> 
> If possible could you apply it a copy of the 2.2 code and rebuild the online docs.

Yes, done.
Thanks guys