Document expected file and section structure

[timhoffm]

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:

• The top-level index.rst is the entry page. It is liked from the logo/library name in the nav bar:
  
  Question:
  • Must / should index.rst start with a top-level heading?
• Next / below to this, the documentation is grouped into major sections (which appear in the nav bar):
  
  Questions:
  • How do I have to create these sections? - Likely a separate page for each.
  • Do I have to take care of section levels? i.e. must these pages have a top-level section heading that is one less than the index.rst heading?
  • How do I integrate these into the main document? - https://github.com/pydata/pydata-sphinx-theme/blob/main/docs/user_guide/index.md?plain=1 uses separate toctree directives for each major section. Is that mandatory, or sylistic or could I also have one toctree directive including all major sections?
• Are there further constaints for the structure within the 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:

  "Take a look at the diagram to understand what the major sections are called"

  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

  Section links

  Links between pages in the active section

  FYI, above I've used the term major sections for these.

• Sphinx / docutils uses "section" as the general structural hierarchy element of the content on any level. They are defined by headings.

[trallard]

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.

[timhoffm]

Sure.