docs: Add more information to the HTML sidebar
Subsystems (2)
Jonathan Corbet
maintainerRFC PATCH v2 1/1 docs: Add more information to the HTML sidebar
Add a new sidebar template that creates a more RTD-like "fisheye" view of the current place in the document hierarchy. It is far from ideal, but some readers may find it better for navigating through the documentation as a whole.
---
Sorry it took so long to get back to this...$EXCUSES plus trying to get ready for the merge window.
This version includes the suggestions Akira sent around a couple of weeks ago. I've also the sidebar TOC go one level deeper when appropriate.
There's a bit of JavaScript that attempts to scroll the sidebar appropriately. It's far from perfect but, hopefully an improvement. It could be made better, but I've managed to remain blissfully ignorant of JavaScript over the years, so it's slow going. It would sure be nice if somebody who is better at that stuff could jump in.
I think the contents of the sidebar could be improved too, but that's probably a bigger job.
As before, the results can be seen at:
https://static.lwn.net/kerneldoc/
This probably isn't going to get a lot further before the merge window. So I ask: is this sufficiently better that it should go into 6.3?
Documentation/conf.py | 5 +++-- Documentation/sphinx-static/custom.css | 20 ++++++++++++++++++- .../sphinx/templates/kernel-toc.html | 11 ++++++++++ 3 files changed, 33 insertions(+), 3 deletions(-) create mode 100644 Documentation/sphinx/templates/kernel-toc.html
Documentation/conf.py +3 -2
@@ -153,7 +153,7 @@ else: math_renderer = 'mathjax' # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ['sphinx/templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string:
@@ -328,6 +328,7 @@ if html_theme == 'alabaster': 'description': get_cline_version(), 'page_width': '65em', 'sidebar_width': '15em', + 'fixed_sidebar': 'true', 'font_size': 'inherit', 'font_family': 'serif', }
@@ -345,7 +346,7 @@ html_use_smartypants = False # Custom sidebar templates, maps document names to template names. # Note that the RTD theme ignores this -html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']} +html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']} # about.html is available for alabaster theme. Add it at the front. if html_theme == 'alabaster':
Documentation/sphinx-static/custom.css +19 -1
@@ -11,7 +11,9 @@ div.body h3 { font-size: 130%; } /* Tighten up the layout slightly */ div.body { padding: 0 15px 0 10px; } div.sphinxsidebarwrapper { padding: 1em 0.4em; } -div.sphinxsidebar { font-size: inherit; } +div.sphinxsidebar { font-size: inherit; + max-height: 100%; + overflow-y: auto; } /* Tweak document margins and don't force width */ div.document { margin: 20px 10px 0 10px;
@@ -27,3 +29,19 @@ dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; } dl.function dt { margin-left: 10em; text-indent: -10em; } dt.sig-object { font-size: larger; } div.kernelindent { margin-left: 2em; margin-right: 4em; } + +/* + * Tweaks for our local TOC + */ +div.kerneltoc li.toctree-l1 { font-size: smaller; + text-indent: -1em; + margin-left: 1em; } +div.kerneltoc li.current {font-weight: bold; } +div.kerneltoc li.toctree-l2,li.toctree-l3 { font-size: smaller; + text-indent: -1em; + margin-left: 2em; + list-style-type: none; + } +div.kerneltoc li.current ul { margin-left: 0; } +div.kerneltoc { background-color: #eeeeee; } +div.kerneltoc li.current ul { background-color: white; }
Documentation/sphinx/templates/kernel-toc.html new file +11 -0
@@ -0,0 +1,11 @@ +{# Create a local TOC the kernel way #} +<p> +<h3>Contents</h3> +<div class="kerneltoc" id="kerneltoc"> +{{ toctree(maxdepth=3) }} +</div> +{# hacky script to try to position the left column #} +<script type="text/javascript"> <!-- + var sbar = document.getElementsByClassName("sphinxsidebar")[0]; + sbar.scrollTop = document.getElementsByClassName("current")[0].offsetTop; + --> </script>
Signature · 1 line
2.39.1
Jonathan Corbet
maintainerQuoted 3 lines · Jonathan Corbet
As before, the results can be seen at:
What's there now reflects a couple of tweaks beyond the patch I sent.
Hopefully I've addressed some of the concerns... One thing I really don't like about the auto-positioning sidebar, though, is that it pushes the "The Linux Kernel" heading off-screen. For somebody following a link into the docs from elsewhere, that could be a bit confusing. I know vaguely how to fix it with CSS, but getting such things right always require a fair amount of dinking around and I can't do that now.
jon
Quoted 4 lines · Jonathan Corbet
Quoted 2 lines · Jonathan Corbet
As before, the results can be seen at:
Quoted 8 lines
Quoted 1 line
What's there now reflects a couple of tweaks beyond the patch I sent.
Hopefully I've addressed some of the concerns... One thing I really don't like about the auto-positioning sidebar, though, is that it pushes the "The Linux Kernel" heading off-screen. For somebody following a link into the docs from elsewhere, that could be a bit confusing.
That's the same in RTD. So this might be a point you hate RTD, I guess.
But I see a major problem on small/narrow screens.
The sidebar is now kept at the top, and by clicking/tapping a link in the TOC, I can't jump to the section I want to see.
Sorry, but this is not usable at all.
Quoted 3 lines
I
know vaguely how to fix it with CSS, but getting such things right always require a fair amount of dinking around and I can't do that now.
;-) ;-) ;-)
Thanks, Akira
Quoted 2 lines
jon
Quoted 14 lines · Akira Yokosawa
Quoted 4 lines · Jonathan Corbet
Quoted 2 lines · Jonathan Corbet
As before, the results can be seen at:
Quoted 8 lines
Quoted 1 line
What's there now reflects a couple of tweaks beyond the patch I sent.
Hopefully I've addressed some of the concerns... One thing I really don't like about the auto-positioning sidebar, though, is that it pushes the "The Linux Kernel" heading off-screen. For somebody following a link into the docs from elsewhere, that could be a bit confusing.
Quoted 7 lines
That's the same in RTD. So this might be a point you hate RTD, I guess.
But I see a major problem on small/narrow screens.
The sidebar is now kept at the top, and by clicking/tapping a link in the TOC, I can't jump to the section I want to see.Sorry, but this is not usable at all.
To be clear, I meant "on small/narrow screens".
On normal PC screens, this resolves the issues I mentioned earlier.
So I'm OK with this goes into v6.3. Maybe add a note on small screen devices in the Changelog.
BTW, I very much like the way LWN's site navigation behaves on small screen devices. LWN is designed to be accessible without hierarchical structure of documents, which is the opposite of how kernel documentation is managed based on the nested TOC entries.
Thanks, Akira
Quoted 11 lines
Quoted 4 lines
I
know vaguely how to fix it with CSS, but getting such things right always require a fair amount of dinking around and I can't do that now.;-) ;-) ;-)
Thanks, Akira
Quoted 2 lines
jon
Jonathan Corbet
maintainerQuoted 11 lines · Akira Yokosawa
Quoted 5 lines
But I see a major problem on small/narrow screens.
The sidebar is now kept at the top, and by clicking/tapping a link in the TOC, I can't jump to the section I want to see.Sorry, but this is not usable at all.
To be clear, I meant "on small/narrow screens".
On normal PC screens, this resolves the issues I mentioned earlier.So I'm OK with this goes into v6.3. Maybe add a note on small screen devices in the Changelog.
I see what you're saying.
The best solution to this, I guess, would be to hide the contents menu behind an icon in the small-screen view. Doable, I'll try to find some time to make that happen.
Quoted 4 lines
BTW, I very much like the way LWN's site navigation behaves on small screen devices. LWN is designed to be accessible without hierarchical structure of documents, which is the opposite of how kernel documentation is managed based on the nested TOC entries.
Yeah, but for the kernel documentation the hierarchy is the only structure we have. Making less of a mess out of it has been a many-year project, got a long way to go...
Thanks,
jon
Randy Dunlap
reviewerHi Jonathan,
Quoted 20 lines · Jonathan Corbet
Add a new sidebar template that creates a more RTD-like "fisheye" view of the current place in the document hierarchy. It is far from ideal, but some readers may find it better for navigating through the documentation as a whole.
Signed-off-by Jonathan Corbet <[email protected]>---
Sorry it took so long to get back to this...$EXCUSES plus trying to get ready for the merge window.This version includes the suggestions Akira sent around a couple of weeks ago. I've also the sidebar TOC go one level deeper when appropriate.
There's a bit of JavaScript that attempts to scroll the sidebar appropriately. It's far from perfect but, hopefully an improvement. It could be made better, but I've managed to remain blissfully ignorant of JavaScript over the years, so it's slow going. It would sure be nice if somebody who is better at that stuff could jump in.
Quoted 6 lines
I think the contents of the sidebar could be improved too, but that's probably a bigger job.
As before, the results can be seen at:
I haven't been following this saga closely but this is looking good to me. Thanks.
Nit: it says that it's for kernel 6.2.0-rc2-6.2.0-rc2+. Is that expected?
Another question: if I'm deep into the menu tree, is there a way (link) to get back to the top level? Other than editing the URL, that is.
Quoted 2 lines
This probably isn't going to get a lot further before the merge window. So I ask: is this sufficiently better that it should go into 6.3?
I'll let the others answer that one.
Quoted 5 lines
Documentation/conf.py | 5 +++-- Documentation/sphinx-static/custom.css | 20 ++++++++++++++++++- .../sphinx/templates/kernel-toc.html | 11 ++++++++++ 3 files changed, 33 insertions(+), 3 deletions(-) create mode 100644 Documentation/sphinx/templates/kernel-toc.html
Signature · 1 line
~Randy
Jonathan Corbet
maintainerQuoted 2 lines · Randy Dunlap
Nit: it says that it's for kernel 6.2.0-rc2-6.2.0-rc2+. Is that expected?
Um ... no. That won't be the result of my current changes, but I'll look into it.
Quoted 3 lines
Another question: if I'm deep into the menu tree, is there a way (link) to get back to the top level? Other than editing the URL, that is.
Click on "The Linux Kernel" at the top of the sidebar.
Thanks,
jon
Randy Dunlap
reviewerHi Jonathan,
Quoted 5 lines · Jonathan Corbet
Quoted 2 lines · Randy Dunlap
Nit: it says that it's for kernel 6.2.0-rc2-6.2.0-rc2+. Is that expected?
Quoted 8 lines
Um ... no. That won't be the result of my current changes, but I'll look into it.
Quoted 3 lines
Another question: if I'm deep into the menu tree, is there a way (link) to get back to the top level? Other than editing the URL, that is.
Click on "The Linux Kernel" at the top of the sidebar.
Ah. That works. :)
Is there a reason that the main index's "sections" (single underline) don't show up in the sidebar index? Is that on purpose? Or just a relic of them being "sections"?
(Why are they sections? Why is the main document's title a chapter instead of being the Document title?)
I would like to be able to see visually when the sidebar index goes from one "section" to another one, e.g., from "Internal API manuals" to "Development tools and processes". I think that there might be a small blank (like 1/2 line space) between these sections now, but that is easy to overlook.
Thanks for listening.
Signature · 1 line
~Randy
Jonathan Corbet
maintainerQuoted 3 lines · Randy Dunlap
Is there a reason that the main index's "sections" (single underline) don't show up in the sidebar index? Is that on purpose? Or just a relic of them being "sections"?
That's just how the sidebar gets generated. I would much rather see the sections there...but if we want that, I think we'll have to implement it ourselves.
Quoted 2 lines
(Why are they sections? Why is the main document's title a chapter instead of being the Document title?)
Good question...that's just how it was done. Probably worth fixing.
Quoted 5 lines
I would like to be able to see visually when the sidebar index goes from one "section" to another one, e.g., from "Internal API manuals" to "Development tools and processes". I think that there might be a small blank (like 1/2 line space) between these sections now, but that is easy to overlook.
See above :)
Thanks,
jon
Hi,
Quoted 9 lines · Jonathan Corbet
Quoted 3 lines · Randy Dunlap
Is there a reason that the main index's "sections" (single underline) don't show up in the sidebar index? Is that on purpose? Or just a relic of them being "sections"?
That's just how the sidebar gets generated. I would much rather see the sections there...but if we want that, I think we'll have to implement it ourselves.
I'd say that the reason why you don't see sections of the main index in the sidebar is because the main index.rst *isn't* listed in any of "toctree" directives.
So, if you want those "sections" in the sidebar, you need to create a .rst file and list it in a toctree of main index.
The RTD theme has exactly the same behavior ever since commit 0c7b4366f1ab ("docs: Rewrite the front page"). Furthermore, as there are quite a few pages which belong to multiple toctrees, sidebar sometimes behaves weirdly.
For example, see the sidebar at:
https://www.kernel.org/doc/html/next/process/submitting-patches.html
(built on current linux-next)
You will see that the "Submitting patches ..." title is expanded twice in the sidebar.
Don't you think this looks weird? ;-)
I think the patch appended below (on top of current docs-next) would have been a better approach, where each .rst file is listed only once in the whole toctree. The refurbished part of main index is moved to index-frequent.rst and toctrees are replaced with lists of :doc: references.
Per-directory indexes are listed in the main index's toctree below the index-frequent.
I'm not saying this is "the" right approach.
There can be many ways to accomplish the same result, I suppose.
I'll submit this change as a proper patch if I can get positive feedback.
Hope this helps.
Thanks, Akira
------------------
Documentation/index-frequent.rst new file +75 -0
@@ -0,0 +1,75 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================== +Frequently Referenced Documents +=============================== + +This is a list of links to kernel documents which would help +(prospective) kernel developers most. + +Working with the development community +====================================== + +The essential guides for interacting with the kernel's development +community and getting your work upstream. + + * process/development-process.rst + * process/submitting-patches.rst + * :doc:`Code of condust <process/code-of-conduct>` + * maintainer/index.rst + * :doc:`All development-process docs <process/index>` + + +Internal API manuals +==================== + +Manuals for use by developers working to interface with the rest of the +kernel. + + * core-api/index.rst + * driver-api/index.rst + * subsystems-apis/index.rst + * :doc:`Locking in the kernel <locking/index>` + + +Development tools and processes +=============================== + +Various other manuals with useful information for all kernel developers. + + * process/license-rules.rst + * doc-guide/index.rst + * dev-tools/index.rst + * dev-tools/testing-overview.rst + * kernel-hacking/index.rst + * trace/index.rst + * fault-injection/index.rst + * livepatch/index.rst + * rust/index.rst + + +User-oriented documentation +=========================== + +The following manuals are written for *users* of the kernel — those who are +trying to get it to work optimally on a given system and application +developers seeking information on the kernel's user-space APIs. + + * admin-guide/index.rst + * :doc:`The kernel build system <kbuild/index>` + * admin-guide/reporting-issues.rst + * :doc:`User-space tools <tools/index>` + * userspace-api/index.rst + +See also: the `Linux man pages <https://www.kernel.org/doc/man-pages/>`_, +which are kept separately from the kernel's own documentation. + + +Firmware-related documentation +============================== + +The following holds information on the kernel's expectations regarding the +platform firmwares. + + * firmware-guide/index.rst + * devicetree/index.rst
Documentation/index.rst +10 -55
102 lines not on this page · raw message
Jonathan Corbet
maintainerQuoted 6 lines · Akira Yokosawa
I think the patch appended below (on top of current docs-next) would have been a better approach, where each .rst file is listed only once in the whole toctree. The refurbished part of main index is moved to
index-frequent.rstand toctrees are replaced with lists of :doc: references.
Quoted 8 lines
Per-directory indexes are listed in the main index's toctree below the index-frequent.
I'm not saying this is "the" right approach.
There can be many ways to accomplish the same result, I suppose.I'll submit this change as a proper patch if I can get positive feedback.
So I applied this and built it. There may be potential in this approach, but I don't think we are there yet.
This change completely loses the organization that I wanted to put onto the front page itself. That page will be the place where people land first, so it should guide them to somewhere useful as quickly and easily as possible. With this change, we've hidden that guidance in a subsidiary page and the front is back to a random collection of unordered stuff.
The front page, I think, is more important than the sidebar.
We really need to look into the actual generation of the sidebar; it's on my list, but won't happen before the merge window. I do appreciate playing with ideas, though - please keep it up! We'll figure out something eventually...:)
Thanks,
jon
Quoted 24 lines · Jonathan Corbet
Add a new sidebar template that creates a more RTD-like "fisheye" view of the current place in the document hierarchy. It is far from ideal, but some readers may find it better for navigating through the documentation as a whole.
Signed-off-by Jonathan Corbet <[email protected]>---
Sorry it took so long to get back to this...$EXCUSES plus trying to get ready for the merge window.This version includes the suggestions Akira sent around a couple of weeks ago. I've also the sidebar TOC go one level deeper when appropriate.
There's a bit of JavaScript that attempts to scroll the sidebar appropriately. It's far from perfect but, hopefully an improvement. It could be made better, but I've managed to remain blissfully ignorant of JavaScript over the years, so it's slow going. It would sure be nice if somebody who is better at that stuff could jump in.
I think the contents of the sidebar could be improved too, but that's probably a bigger job.
Quoted 7 lines
As before, the results can be seen at:
https://static.lwn.net/kerneldoc/
This probably isn't going to get a lot further before the merge window. So I ask: is this sufficiently better that it should go into 6.3?
This is much better, thanks!
Personally, I think this fixes the problems I had with the earlier alabaster versions. It's still not quite perfect, but it's usable to me in a way the original versions weren't.
There are definitely a few pages which are nested even deeper than maxdepth=3, which become more difficult to navigate, but they seem rare enough that it might make more sense to just restructure those bits of the docs to remove some levels of nesting.
Otherwise, mostly small css issues (the main one being the font size for the 3rd level nested elements being way too small to comfortably read). Getting rid of the font-size: smaller bit works for me. In fact (at least for my normal usage pattern), the more deeply nested something is, the more useful it's likely to be: navigating to child and/or sibling pages (or back to the immediate parent page) is most common, as those pages are most related. So having the font size increase with "font-size: larger" actually works pretty well, even if it really gives a weirdly-bulging "fisheye" view to everything.
I still think RTD is a bit more usable at the moment, if only because of the higher contrast and the breadcrumbs at the top of each page. But this is good enough that I can get everywhere I need to go without constantly needing to use the browser back button. So I'd much rather this in 6.3 than the stock alabaster version, even if it could still use some tweaks.
Cheers,
-- David
Quoted 91 lines
Documentation/conf.py | 5 +++-- Documentation/sphinx-static/custom.css | 20 ++++++++++++++++++- .../sphinx/templates/kernel-toc.html | 11 ++++++++++ 3 files changed, 33 insertions(+), 3 deletions(-) create mode 100644 Documentation/sphinx/templates/kernel-toc.htmlDocumentation/conf.py +3
-2@@ -153,7 +153,7 @@ else: math_renderer = 'mathjax' # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ['sphinx/templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string:@@ -328,6 +328,7 @@ if html_theme == 'alabaster': 'description': get_cline_version(), 'page_width': '65em', 'sidebar_width': '15em', + 'fixed_sidebar': 'true', 'font_size': 'inherit', 'font_family': 'serif', }@@ -345,7 +346,7 @@ html_use_smartypants = False # Custom sidebar templates, maps document names to template names. # Note that the RTD theme ignores this -html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']} +html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']} # about.html is available for alabaster theme. Add it at the front. if html_theme == 'alabaster':Documentation/sphinx-static/custom.css +19
-1@@ -11,7 +11,9 @@ div.body h3 { font-size: 130%; } /* Tighten up the layout slightly */ div.body { padding: 0 15px 0 10px; } div.sphinxsidebarwrapper { padding: 1em 0.4em; } -div.sphinxsidebar { font-size: inherit; } +div.sphinxsidebar { font-size: inherit; + max-height: 100%; + overflow-y: auto; } /* Tweak document margins and don't force width */ div.document { margin: 20px 10px 0 10px;@@ -27,3 +29,19 @@ dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; } dl.function dt { margin-left: 10em; text-indent: -10em; } dt.sig-object { font-size: larger; } div.kernelindent { margin-left: 2em; margin-right: 4em; } + +/* + * Tweaks for our local TOC + */ +div.kerneltoc li.toctree-l1 { font-size: smaller; + text-indent: -1em; + margin-left: 1em; } +div.kerneltoc li.current {font-weight: bold; } +div.kerneltoc li.toctree-l2,li.toctree-l3 { font-size: smaller; + text-indent: -1em; + margin-left: 2em; + list-style-type: none; + } +div.kerneltoc li.current ul { margin-left: 0; } +div.kerneltoc { background-color: #eeeeee; } +div.kerneltoc li.current ul { background-color: white; }Documentation/sphinx/templates/kernel-toc.html new file +11
-1@@ -0,0 +1,11 @@ +{# Create a local TOC the kernel way #} +<p> +<h3>Contents</h3> +<div class="kerneltoc" id="kerneltoc"> +{{ toctree(maxdepth=3) }} +</div> +{# hacky script to try to position the left column #} +<script type="text/javascript"> <!-- + var sbar = document.getElementsByClassName("sphinxsidebar")[0]; + sbar.scrollTop = document.getElementsByClassName("current")[0].offsetTop; + --> </script> --2.39.1
Quoted 24 lines · Jonathan Corbet
Add a new sidebar template that creates a more RTD-like "fisheye" view of the current place in the document hierarchy. It is far from ideal, but some readers may find it better for navigating through the documentation as a whole.
Signed-off-by Jonathan Corbet <[email protected]>---
Sorry it took so long to get back to this...$EXCUSES plus trying to get ready for the merge window.This version includes the suggestions Akira sent around a couple of weeks ago. I've also the sidebar TOC go one level deeper when appropriate.
There's a bit of JavaScript that attempts to scroll the sidebar appropriately. It's far from perfect but, hopefully an improvement. It could be made better, but I've managed to remain blissfully ignorant of JavaScript over the years, so it's slow going. It would sure be nice if somebody who is better at that stuff could jump in.
I think the contents of the sidebar could be improved too, but that's probably a bigger job.
Quoted 6 lines
As before, the results can be seen at:
https://static.lwn.net/kerneldoc/
This probably isn't going to get a lot further before the merge window. So I ask: is this sufficiently better that it should go into 6.3?
Thank you very much, Jon. This version looks better than the previous one and resolves the "Where am I?" problem. As David suggested, the font size for the third-level nested heading in the sidebar should be increased; otherwise, it
is good to go for 6.3.
Regards,
Sadiya
Quoted 92 lines
Documentation/conf.py | 5 +++-- Documentation/sphinx-static/custom.css | 20 ++++++++++++++++++- .../sphinx/templates/kernel-toc.html | 11 ++++++++++ 3 files changed, 33 insertions(+), 3 deletions(-) create mode 100644 Documentation/sphinx/templates/kernel-toc.htmlDocumentation/conf.py +3
-2@@ -153,7 +153,7 @@ else: math_renderer = 'mathjax' # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ['sphinx/templates'] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string:@@ -328,6 +328,7 @@ if html_theme == 'alabaster': 'description': get_cline_version(), 'page_width': '65em', 'sidebar_width': '15em', + 'fixed_sidebar': 'true', 'font_size': 'inherit', 'font_family': 'serif', }@@ -345,7 +346,7 @@ html_use_smartypants = False # Custom sidebar templates, maps document names to template names. # Note that the RTD theme ignores this -html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']} +html_sidebars = { '**': ['searchbox.html', 'kernel-toc.html', 'sourcelink.html']} # about.html is available for alabaster theme. Add it at the front. if html_theme == 'alabaster':Documentation/sphinx-static/custom.css +19
-1@@ -11,7 +11,9 @@ div.body h3 { font-size: 130%; } /* Tighten up the layout slightly */ div.body { padding: 0 15px 0 10px; } div.sphinxsidebarwrapper { padding: 1em 0.4em; } -div.sphinxsidebar { font-size: inherit; } +div.sphinxsidebar { font-size: inherit; + max-height: 100%; + overflow-y: auto; } /* Tweak document margins and don't force width */ div.document { margin: 20px 10px 0 10px;@@ -27,3 +29,19 @@ dl.function, dl.struct, dl.enum { margin-top: 2em; background-color: #ecf0f3; } dl.function dt { margin-left: 10em; text-indent: -10em; } dt.sig-object { font-size: larger; } div.kernelindent { margin-left: 2em; margin-right: 4em; } + +/* + * Tweaks for our local TOC + */ +div.kerneltoc li.toctree-l1 { font-size: smaller; + text-indent: -1em; + margin-left: 1em; } +div.kerneltoc li.current {font-weight: bold; } +div.kerneltoc li.toctree-l2,li.toctree-l3 { font-size: smaller; + text-indent: -1em; + margin-left: 2em; + list-style-type: none; + } +div.kerneltoc li.current ul { margin-left: 0; } +div.kerneltoc { background-color: #eeeeee; } +div.kerneltoc li.current ul { background-color: white; }Documentation/sphinx/templates/kernel-toc.html new file +11
-1@@ -0,0 +1,11 @@ +{# Create a local TOC the kernel way #} +<p> +<h3>Contents</h3> +<div class="kerneltoc" id="kerneltoc"> +{{ toctree(maxdepth=3) }} +</div> +{# hacky script to try to position the left column #} +<script type="text/javascript"> <!-- + var sbar = document.getElementsByClassName("sphinxsidebar")[0]; + sbar.scrollTop = document.getElementsByClassName("current")[0].offsetTop; + --> </script> --2.39.1