fyi an important change was made with Sphinx 5.2+ over 5.1: toctree includes classes, methods and function now. See https://doc.wikimedia.org/pywikibot/master/api_ref/index.html vs. https://doc.wikimedia.org/pywikibot/stable/api_ref/index.html or https://doc.wikimedia.org/pywikibot/master/api_ref/pywikibot.page.html vs. https://doc.wikimedia.org/pywikibot/stable/api_ref/pywikibot.page.html

furo (I guess this is latin) moves the new toc entries to the right navi bar which looks great.

Change 860879 had a related patch set uploaded (by KBach; author: KBach):

[pywikibot/core@tests] [docs] Improve basic content structure and navigation

https://gerrit.wikimedia.org/r/860879

In T323812#8421531, @Xqt wrote:

fyi an important change was made with Sphinx 5.2+ over 5.1: toctree includes classes, methods and function now. See https://doc.wikimedia.org/pywikibot/master/api_ref/index.html vs. https://doc.wikimedia.org/pywikibot/stable/api_ref/index.html or https://doc.wikimedia.org/pywikibot/master/api_ref/pywikibot.page.html vs. https://doc.wikimedia.org/pywikibot/stable/api_ref/pywikibot.page.html

furo (I guess this is latin) moves the new toc entries to the right navi bar which looks great.

Yea, these are very cool changes :)

I uploaded a new patch with content/structure/navigation changes for review. I've also provided some reasoning behind my changes in the comments. Looking forward to hearing your thoughts, especially on some of the more significant ones.

In T323812#8421689, @KBach wrote:

I uploaded a new patch with content/structure/navigation changes for review. I've also provided some reasoning behind my changes in the comments. Looking forward to hearing your thoughts, especially on some of the more significant ones.

I've added some comments but it looks good overall.

Change 860879 merged by jenkins-bot:

[pywikibot/core@tests] [docs] Improve basic content structure and navigation

https://gerrit.wikimedia.org/r/860879

Change 860982 had a related patch set uploaded (by Xqt; author: KBach):

[pywikibot/core@master] [docs] Improve basic content structure and navigation

https://gerrit.wikimedia.org/r/860982

Change 860982 merged by jenkins-bot:

[pywikibot/core@master] [docs] Improve basic content structure and navigation

https://gerrit.wikimedia.org/r/860982

Change 861831 had a related patch set uploaded (by KBach; author: KBach):

[pywikibot/core@tests] [doc] Clean up content structure and unify headline syntax

https://gerrit.wikimedia.org/r/861831

Added changes intended to unify the usage of headline syntax in the docs. The rules I tried to apply are:

• Every index page should use the headline syntax in the following order:
  1. # with overline
  2. * with overline
  3. =
  4. -
  5. ^
  6. "
• Every other page should use the headline syntax in the following order (essentially the same, but without #):
  1. * with overline
  2. =
  3. -
  4. ^
  5. "

I think this is relatively simple and should be easy to pick up for new contributors. This order is also consistent with Python Developer Guidelines, though it does not assign specific purpose (e.g. part, chapter, section, etc.) to each level.

The current patch does not apply these changes to the docs/tests_ref folder (apart from its index.rst file). I'll add this if this change gets positive feedback.

Change 861831 merged by jenkins-bot:

[pywikibot/core@tests] [doc] Clean up content structure and unify headline syntax

https://gerrit.wikimedia.org/r/861831

Change 862220 had a related patch set uploaded (by KBach; author: KBach):

[pywikibot/core@tests] [doc] Unify heading syntax in docs/tests_ref

https://gerrit.wikimedia.org/r/862220

Change 862220 merged by jenkins-bot:

[pywikibot/core@tests] [doc] Unify heading syntax in docs/tests_ref

https://gerrit.wikimedia.org/r/862220