linux-kernel - Re: [PATCH] docs/sphinx: More depth in the rtd sidebar toc

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]

Date:   Tue, 8 Nov 2022 12:59:39 +0100
From:   Daniel Vetter <daniel.vetter@...ll.ch>
To:     Jonathan Corbet <corbet@....net>
Cc:     DRI Development <dri-devel@...ts.freedesktop.org>,
        LKML <linux-kernel@...r.kernel.org>,
        Daniel Vetter <daniel.vetter@...el.com>,
        linux-doc@...r.kernel.org
Subject: Re: [PATCH] docs/sphinx: More depth in the rtd sidebar toc

On Mon, 7 Nov 2022 at 21:06, Daniel Vetter <daniel.vetter@...ll.ch> wrote:
>
> On Fri, 28 Oct 2022 at 20:19, Jonathan Corbet <corbet@....net> wrote:
> >
> > Daniel Vetter <daniel.vetter@...ll.ch> writes:
> >
> > > We love to nest our documenation for good structure, but that means
> > > the table of contents needs to keep up or you can't navigate them.
> > >
> > > Realized this trying to find the drm property documentation, which
> > > with some shuffling around disappeared. Why I didn't realize we can do
> > > this earlier, no idea.
> > >
> > > Since the relevant parts of the toc are only loaded if you're in the
> > > right .html file there's no harm in going all the way to unlimited.
> > >
> > > Note that this has no impact on the classic theme (which doesn't have
> > > the sidebar) nor on the various :toctree: rendered inline in the
> > > output.
> > >
> > > Signed-off-by: Daniel Vetter <daniel.vetter@...el.com>
> > > Cc: Jonathan Corbet <corbet@....net>
> > > Cc: linux-doc@...r.kernel.org
> > > ---
> > >  Documentation/conf.py | 4 ++++
> > >  1 file changed, 4 insertions(+)
> > >
> > > diff --git a/Documentation/conf.py b/Documentation/conf.py
> > > index 934727e23e0e..5dc141c66726 100644
> > > --- a/Documentation/conf.py
> > > +++ b/Documentation/conf.py
> > > @@ -240,6 +240,10 @@ if html_theme == 'sphinx_rtd_theme' or html_theme == 'sphinx_rtd_dark_mode':
> > >                  # Add color-specific RTD normal mode
> > >                  html_css_files.append('theme_rtd_colors.css')
> > >
> > > +        html_theme_options = {
> > > +            'navigation_depth': -1,
> > > +        }
> > > +
> > >      except ImportError:
> > >          html_theme = 'classic'
> >
> > So this patch isn't against docs-next, and applies to the RTD theme,
> > which is no longer the default.  I have no objection to it, but have you
> > looked at how your docs come out with the alabaster theme?
>
> [sorry took a bit longer to get back to this]
>
> Hm looks pretty, but more in a print style than using it dynamically,
> you can't really click through the sidebar toc at all to quickly find
> something, and if you're wrong, navigate up a few levels again. It's
> just the toc for exactly the local document, nothing else at all. rtd
> theme always gives you the full toc all the way up, and if you have
> epic patience could actually give you the full toc on every document
> (but that's probably not a good idea for the kernel). Do you need me
> to send the rebased version or can you smash this one in?
>
> btw on today's linux-next the sphinx.rst page isn't updated with the
> new default theme choice of alabaster. That seems to have been
> forgotten.

Sorry got confused on this and looked at the wrong tab/build output
locally, it's good. Anyway I sent out a rebased version of the rtd
patch, I do like that sidebar a lot more for navigating the docs :-)
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch