Documentation: structural improvements

[cspotcode]

I wanted to make a bunch of improvements to our docs. The resulting diff would have been way too big and overlapping to review in a single PR.

So I used "stacked PRs." A PR stack is a single chain of commits. This means each subset of code changes can be reviewed in isolation, but the end of the chain includes all code changes.

For reviewers

Do not merge any of these PRs! Only review!
It's a PR stack, so you will definitely break something if you click "merge" Please don't!

To see the end result of all these PRs combined:
https://api.arcade.academy/en/doc_structural_improvements/

To review a single PR, look at the description for that PR in the list below.

Quick list

All PRs, same as the ones linked in the list below:

• doc_stack/fix_readthedocs #1856 [already merged]
• doc_stack/sidebar #1863
• doc_stack/docstring_misc #1859
• doc_stack/ux_polish #1860
• doc_stack/sphinx_manual_doc_layout #1861
• doc_stack/no_types_in_docstrings #1862
• doc_stack/google_style_docstrings #1858
• doc_stack/special_methods #1855

PR Descriptions

PR: Fix website rendering #1856

• fix readthedocs rendering by re-adding docs dependency group

PR: Sidebar #1863

• Sidebar reorg
  • @pushfoo and @cspotcode are iterating on a new sidebar here: https://docs.google.com/document/d/19rXXlUdtSk80IwCWbwSwvz1yh7TXWJ5dUryWos6HdQM/edit#
    See also: this issue outlines a hierarchy Documentation Reorganization #1194
  • split "Programming" guide into "User Guide" and "Contributing"
  • Fix "Arcade Programming Guide Index" duplication of pages
• Fix duplicated headers on right-hand sidebar
• cleanup unnecessary suffixes on doc titles: "API Docs" -> "API", "Quick API Index" -> "Index", "Game Controller Support" -> "Game Controller", remove "Tutorial" from a bunch of tutorial titles cuz it's already absent from others

PR: Docstring standards: Misc #1859

• Replace all lingering "Attributes" tables with standard autodoc for attributes, properties, methods
  Already done, Convert tilemap attribute docs to docstrings which produce better autodocs #1785 was the last one(?)
• show inheritance for all classes via :show-inheritance:
• Add from __future__ import annotations to all files so that we can use | union syntax everywhere, forward references work without quoting
• group members by type (method, attribute) then alphabetically
• Disable "property" prefix on properties in the API docs, so they render identical to attributes. Reduces visual noise in docs

PR: UX Polish #1860

• "Quick index" page: Collapse 3x tables into 1
  Currently, is 3x, but the split hurts rather than helps readers.
  Try using that page yourself, and see the kind of scrolling you need to do to understand what is shown. Not clear there are additional text boxes.
  • The arcade module (but also includes many other things: arcade.easing, arcade.geometry, arcade.isometric, arcade.math, etc)
  • The arcade.gui module
  • The arcade.tilemap module
• Always show grey highlight behind signatures, makes the doc sections easier to visually navigate, removes need for redundant headers
• Remove all those redundant headers from API doc pages
• Hide ClassName. prefix from members in right-hand TOC navigation

PR: Sphinx infra: manual doc layout #1861

Empty PR! At first I created this PR, but then I decided not to do it; it's einarf's baby. I only mention it here in case anyone is confused why the PR exists. Yes, it's in the stack, no it does not have any code changes.

• einarf's revamp: control doc layout manually, use coverage to ensure we include everything
  https://github.com/moderngl/moderngl-window/blob/master/tests/test_docs.py

PR: Sphinx infra: no types in docstrings #1862

• Remove all typehints from docstrings, convert to real typehints
  vanilla sphinx already renders typehints in signatures
• [wont do] sphinx_autodoc_typehints can copy types into reST
• Use cspotcode's config to strip -> None from __init__
-> None in docs is wrong from the user's perspective, because calling a class returns an instance of the class, not None

PR: Docstring standards: Google-style #1858

This PR only enables the napoleon plugin, it does not rewrite any docstrings. I talked to pushfoo and we agreed he'll do the docstring changes in separate PRs.

• Configure napoleon plugin to render Google-style docstrings
• [wontdo] Convert to Google-style docstrings everywhere
  Related: Differences in parameter docs #1684

PR: Sphinx infra: special method docs #1855

• Render special methods as their usage from user perspective
  • if SpriteList class declares __len__, docs should talk about len(sprite_list)
  • https://github.com/sphinx-contrib/prettyspecialmethods

---

https://github.com/yoloseem/awesome-sphinxdoc

readthedocs render status: https://readthedocs.org/projects/arcade-library/builds

[cspotcode]

Here is the git machete config I'm using for this PR stack:

To rebase and re-push all branches in the stack, I do this:
Set env var GIT_MACHETE_REBASE_OPTS="--keep-empty"
git checkout doc_structural_improvements
git machete traverse -w
It'll prompt me for all the necessary rebasing and pushing to update the full stack. It does all the work. It also created the PRs using git machete github pr-create but no need to do that again.

development
	doc_stack/fix_readthedocs PR #1856
		doc_stack/sidebar PR #1857
			doc_stack/google_style_docstrings PR #1858
				doc_stack/docstring_misc PR #1859
					doc_stack/ux_polish PR #1860
						doc_stack/sphinx_manual_doc_layout PR #1861
							doc_stack/no_types_in_docstrings PR #1862
								doc_stack/special_methods PR #1855
									doc_structural_improvements