Messages in this thread | | | From | Jonathan Corbet <> | Subject | Re: [RFC PATCH v2] docs: rework "Working with the development community" | Date | Wed, 26 Jul 2023 13:30:58 -0600 |
| |
Costa Shulyupin <costa.shul@redhat.com> writes:
> Mission: Make the documentation more readable, organized and maintainable. > > NB: no information content is lost of changed on the rendered top page. > > This patch demonstrates rework of the only the first section > of the top page for review. The proposal is to rework all sections. > > Summary of changes: > - Heading "Working with the development community" is converted into > branch of toctree and visually moved after the text > "The essential guides for interacting ..." > - toctree list is split into separated file. Please don't worry, the > content of the list is incorporated to the top page because of > `:maxdepth: 2` > - vertical bar '|' add empty line for better visual distribution
I will repeat. I do not support carving useful stuff out of the front page in this way. The front page does not exist just to make a nice-looking sidebar.
> Technical explanations: > Template {{ toctree(maxdepth=3) }} in > Documentation/sphinx/templates/kernel-toc.html > uses directives toctree and doesn't use sections on the top page > Documentation/index.rst > to generate expandable toc on the sidebar. > > BTW, other template {{ toc }} uses only sections, and doesn't > use directives toctree.
*This* is where the problem lies. I have started looking at it again, but digging deep into the Sphinx code can be painful at times.
jon
| |