Open timhoffm opened 6 days ago
Thank you @timhoffm 🙏🏽 I recognize our docs could do with a bit of TLC so I appreciate the detailed issue and suggestions.
I might have some time to work on our docs soon(ish), would it be ok if I ping you for a review when I get to improving some of this content? It is ok if you have too many things on your plate and cannot commit but I ask as I'd appreciate having a user perspective to ensure we hit the mark /fill these gaps accordingly.
Sure.
I struggle to set up a file / section structure that creates a reasonable layout. As a result, the left / right navigation sidebars can get funny. Sometimes not showing content, sometimes showing more content than expcected (e.g. "On this page" showing also top-level sections of neighboring pages). It seems a certain layout is required, which I could not find in the docs.
It would be helpful to document the expected structure and how that maps to the rendered page.
Things to document / clarify:
index.rst
is the entry page. It is liked from the logo/library name in the nav bar:index.rst
start with a top-level heading?index.rst
heading?toctree
directives for each major section. Is that mandatory, or sylistic or could I also have one toctree directive including all major sections?Edit: Reading the docs, there's also some ambiguity around the use of the term "section"; namely,
The parts of the layout (i.e. "header", "primary_sidebar" etc.) are called "section" in https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html#overview-of-theme-layout, Example:
For clarity, I suggest to rename these, e.g. to layout area or similar.
Likewise the same page uses "section" as the major content substructure. Examples
FYI, above I've used the term major sections for these.