Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
MIME-Version: 1.0
References: <20221027104406.549734-1-daniel.vetter@ffwll.ch>
 <87tu3n6cb2.fsf@meer.lwn.net> <CAKMK7uHXz7kteQ_sckTQx=E9cWSqGXS_Y0_pLjX2CRcApOvKRQ@mail.gmail.com>
In-Reply-To: <CAKMK7uHXz7kteQ_sckTQx=E9cWSqGXS_Y0_pLjX2CRcApOvKRQ@mail.gmail.com>
From:   Daniel Vetter <daniel.vetter@ffwll.ch>
Date:   Tue, 8 Nov 2022 12:59:39 +0100
Message-ID: <CAKMK7uF7riJszvbVNA2PGAxndVkA-TmzBx0uVVfYZ4L_BLaEgA@mail.gmail.com>
Subject: Re: [PATCH] docs/sphinx: More depth in the rtd sidebar toc
To:     Jonathan Corbet <corbet@lwn.net>
Cc:     DRI Development <dri-devel@lists.freedesktop.org>,
        LKML <linux-kernel@vger.kernel.org>,
        Daniel Vetter <daniel.vetter@intel.com>,
        linux-doc@vger.kernel.org
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

On Mon, 7 Nov 2022 at 21:06, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
>
> On Fri, 28 Oct 2022 at 20:19, Jonathan Corbet <corbet@lwn.net> wrote:
> >
> > Daniel Vetter <daniel.vetter@ffwll.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@intel.com>
> > > Cc: Jonathan Corbet <corbet@lwn.net>
> > > Cc: linux-doc@vger.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