and leave only their neighbor subsystem-apis
because these links are already listed under
section "Core subsystems" of Documentation/subsystem-apis.rst:
Core subsystems
---------------
.. toctree::
:maxdepth: 1
core-api/index
driver-api/index
mm/index
power/index
scheduler/index
timers/index
locking/index
Reference:
- https://www.kernel.org/doc/html/next/subsystem-apis.html#core-subsystems
Motivation:
- make the documentation more organized
- increase consistency, observability and maintainability
- improve balance of ToC tree by reducing overly populated lists
- avoid duplicate parallel links
- escape tangling of links
- intention to fit the main index into one page
Signed-off-by: Costa Shulyupin <[email protected]>
---
Documentation/index.rst | 3 ---
1 file changed, 3 deletions(-)
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 9dfdc826618c..8d8b7eab1131 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -38,10 +38,7 @@ kernel.
.. toctree::
:maxdepth: 1
- core-api/index
- driver-api/index
subsystem-apis
- Locking in the kernel <locking/index>
Development tools and processes
===============================
--
2.41.0
Costa Shulyupin <[email protected]> writes:
> and leave only their neighbor subsystem-apis
>
> because these links are already listed under
> section "Core subsystems" of Documentation/subsystem-apis.rst:
>
> Core subsystems
> ---------------
>
> .. toctree::
> :maxdepth: 1
>
> core-api/index
> driver-api/index
> mm/index
> power/index
> scheduler/index
> timers/index
> locking/index
>
> Reference:
> - https://www.kernel.org/doc/html/next/subsystem-apis.html#core-subsystems
>
> Motivation:
> - make the documentation more organized
> - increase consistency, observability and maintainability
> - improve balance of ToC tree by reducing overly populated lists
> - avoid duplicate parallel links
> - escape tangling of links
> - intention to fit the main index into one page
>
> Signed-off-by: Costa Shulyupin <[email protected]>
> ---
> Documentation/index.rst | 3 ---
> 1 file changed, 3 deletions(-)
>
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 9dfdc826618c..8d8b7eab1131 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -38,10 +38,7 @@ kernel.
> .. toctree::
> :maxdepth: 1
>
> - core-api/index
> - driver-api/index
> subsystem-apis
> - Locking in the kernel <locking/index>
So I don't really see the value of this. It takes away some of the most
important links from the documentation front page, leaving the "Internal
API manuals" section nearly empty. Why would we want to do this?
Thanks,
jon
The left column "Contents" is overloaded and hard to use. The value of
this patch is to make it more usable.
Sections of the main page are not displayed after patch "docs: Add
more information to the HTML sidebar". So sections don't work now and
should be fixed too.
I have in mind to reorganize the main page so the left column
"Contents" becomes usable.
Thanks
Costa
On Fri, 21 Jul 2023 at 22:56, Jonathan Corbet <[email protected]> wrote:
>
> Costa Shulyupin <[email protected]> writes:
>
> > and leave only their neighbor subsystem-apis
> >
> > because these links are already listed under
> > section "Core subsystems" of Documentation/subsystem-apis.rst:
> >
> > Core subsystems
> > ---------------
> >
> > .. toctree::
> > :maxdepth: 1
> >
> > core-api/index
> > driver-api/index
> > mm/index
> > power/index
> > scheduler/index
> > timers/index
> > locking/index
> >
> > Reference:
> > - https://www.kernel.org/doc/html/next/subsystem-apis.html#core-subsystems
> >
> > Motivation:
> > - make the documentation more organized
> > - increase consistency, observability and maintainability
> > - improve balance of ToC tree by reducing overly populated lists
> > - avoid duplicate parallel links
> > - escape tangling of links
> > - intention to fit the main index into one page
> >
> > Signed-off-by: Costa Shulyupin <[email protected]>
> > ---
> > Documentation/index.rst | 3 ---
> > 1 file changed, 3 deletions(-)
> >
> > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > index 9dfdc826618c..8d8b7eab1131 100644
> > --- a/Documentation/index.rst
> > +++ b/Documentation/index.rst
> > @@ -38,10 +38,7 @@ kernel.
> > .. toctree::
> > :maxdepth: 1
> >
> > - core-api/index
> > - driver-api/index
> > subsystem-apis
> > - Locking in the kernel <locking/index>
>
> So I don't really see the value of this. It takes away some of the most
> important links from the documentation front page, leaving the "Internal
> API manuals" section nearly empty. Why would we want to do this?
>
> Thanks,
>
> jon
>
Costa Shulyupin <[email protected]> writes:
> The left column "Contents" is overloaded and hard to use. The value of
> this patch is to make it more usable.
>
> Sections of the main page are not displayed after patch "docs: Add
> more information to the HTML sidebar". So sections don't work now and
> should be fixed too.
>
> I have in mind to reorganize the main page so the left column
> "Contents" becomes usable.
No, that is not the right approach.
Much of our documentation is just thrown together in haphazard ways, but
the front page has actually been the target of a certain amount of
thought. It is, after all, the entry point into our documentation.
This page can surely be improved. But thrashing it up for the purpose
of making the sidebar better is getting the priorities wrong; the front
page is far more important. The way to improve the sidebar is to change
how that is generated; that almost certainly requires digging into the
theme code. That has been on my list for some time, but I haven't
gotten to it. It would be wonderful if somebody beat me to it.
Thanks,
jon