docs: reorganize toctree — merge how-tos/TinyMCE into Concepts, move app docs into References

[robrap]

WARNING:

• This was planned and coded by Claude/AI with no human review.
• My local build is not working due to build issues independent of this PR.
• This PR is here for reference only, including the plan details.

Pre-merge action item

• Delete docs/decisions/toctree-reorganization-plan.md — it is a planning artifact, not an ADR. The before/after and rationale are documented in this PR description. Shipping it mixes .md with the .rst ADR convention and sets an unwanted precedent.

Summary

• Rename "Concepts and Guides" → "Concepts and "How-To" Guides"; merge how-tos (celery, use_the_api) and TinyMCE plugins into it as flat entries
• Move generated app index and app ADR index into docs/references/ as sibling items (docs - App index, docs - App ADR index) alongside the existing docs - tree
• Delete docs/how-tos/ directory; add redirects.txt entries for moved pages
• Update conf.py, repository_docs.py, toctree files, and grid cards to match new structure
• Fix incremental-build staleness: _create_index_rst_file now overwrites the root index when a custom title is provided (previously bailed on first build's file, keeping a stale title)

Plan

See docs/decisions/toctree-reorganization-plan.md for the full before/after and rationale.

Before / After (sidebar toctree)

BEFORE                                 AFTER
---------------------------------      ---------------------------------
"How-To" Guides          <- top       References
  How to write a celery task            ...existing items...
  How To Use the REST API               docs - App ADR index  <- moved, renamed
References                              docs - App index      <- moved, renamed
  ...existing items...                  docs - tree           <- title changed
  docs        <- auto-generated         Python Docstrings
  Python Docstrings                   Concepts and "How-To" Guides <- renamed
Concepts and Guides      <- top          extension_points
  extension_points                       testing/testing
  testing/testing                        frontend/*
  frontend/*                             rest_apis
  rest_apis                              TinyMCE Plugins      <- moved
TinyMCE (Visual Text/HTML                How to write a celery task  <- moved
  Editor) Plugins        <- top          How To Use the REST API     <- moved
App-Level Architecture
  Decision Records       <- top (no children)
App-Level Documentation  <- top (no children)

Test plan

• cd docs && make html builds without orphan-document warnings
• Sidebar shows docs - App ADR index, docs - App index, docs - tree as sibling items under References
• "Concepts and How-To Guides" section contains TinyMCE and the how-to pages at the same level (flat)
• "App Documentation" grid card on the homepage links correctly to the new paths

🤖 Generated with Claude Code

[robrap]

Note: This file is meant to be temporary.

[robrap]

Claude review (and fixes), so this doesn't need be duplicated. Now we just need a human author and a human reviewer.

Overview

Restructures the Sphinx/ReadTheDocs sidebar tree:

• Renames "Concepts and Guides" → Concepts and "How-To" Guides and folds how-tos/celery, how-tos/use_the_api, and
  extensions/tinymce_plugins into it as flat entries.
• Moves the auto-generated app and ADR indices from docs/apps/ and docs/decisions/app_decisions.rst into
  docs/references/app_index.rst and docs/references/app_adr_index.rst, retitling them docs - App index, docs - App
  ADR index, and the rst tree root docs - tree.
• Deletes docs/how-tos/, adds two redirects.txt entries, removes stale :doc: and toctree links from
  docs/index.rst.
• Adds a planning doc docs/decisions/toctree-reorganization-plan.md.

---

Correctness

• repository_docs.py path changes are internally consistent: build_apps_index and build_decisions_index both emit
  into docs/references/, and the relative :doc: links inside them were updated to match (docs/{rel}/index from a
  file living in docs/references/, and ../decisions/0001-courses-in-lms for the repo-wide ADR cross-ref). ✅
• docs/references/index.rst is unchanged and uses :glob: * — it will pick up the two new generated files
  automatically. ✅
• decisions/index.rst correctly drops app_decisions (no longer generated at that path; leaving it would produce a
  Sphinx toctree warning). ✅
• docs/index.rst hidden toctree no longer references how-tos/index, extensions/tinymce_plugins, or apps/index —
  all three are reachable through other toctrees, so no orphan warnings expected. ✅
• redirects.txt entries follow the existing "old.rst" "new.rst" rediraffe format. ✅
• len(title) * '=' correctly handles variable-length titles. ✅

---

Issues

1. Build was never verified (author's own warning). Given the scope of cross-reference rewiring (4 :doc: updates
   in index.rst, 2 generated-file relocations, 1 rediraffe pair), this is the dominant risk. Specifically worth
   checking:

• Whether concepts/index.rst resolves ../extensions/tinymce_plugins correctly (parent-path entries in toctrees
  are legal but sometimes generate warnings).
• Whether decisions/index.rst's pre-existing broken-title quirk causes any new warnings — with app_decisions
  removed, only the 0* glob remains.

2. _create_index_rst_file early return masked title on incremental builds. Fixed in this branch: the
   early-return guard now only applies when title is None, so an explicit root_title='docs - tree' always overwrites
   the stale file from a previous build.

3. Plan doc should not live in docs/decisions/. docs/decisions/toctree-reorganization-plan.md is a planning
   artifact, not an ADR. It is .md in an .rst-only directory, and the numbered ADR convention makes an unnumbered
   "plan" file out of place. The before/after and rationale are already in the PR description. Pre-merge action:
   delete this file.

4. Removed comment on :doc: path relativity. Restored in this branch: build_apps_index now has a comment
   noting that :doc: links are relative to docs/references/ (where the file is generated).

---

Security / performance

None applicable — pure documentation change, no runtime code paths affected.

---

Recommendation

Block on: a successful cd docs && make html with no new orphan-document or toctree-reference warnings before
merge.

Required before merge: delete docs/decisions/toctree-reorganization-plan.md.