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

docs/concepts/index.rst

@@ -1,5 +1,5 @@
-Concepts and Guides
-###################
+Concepts and "How-To" Guides
+############################
 
 .. toctree::
     :maxdepth: 2
@@ -11,3 +11,6 @@ Concepts and Guides
     frontend/bootstrap
     frontend/static_assets
     rest_apis
+    ../extensions/tinymce_plugins
+    celery
+    use_the_api

docs/conf.py

@@ -339,9 +339,9 @@ def on_init(app):  # pylint: disable=redefined-outer-name, unused-argument
     """
     repo_docs_build_path = f'{root}/docs/references/docs'
     repo_docs = RepositoryDocs(root, repo_docs_build_path)
-    repo_docs.build_rst_docs()
-    repo_docs.build_apps_index(root / 'docs' / 'apps' / 'index.rst')
-    repo_docs.build_decisions_index(root / 'docs' / 'decisions' / 'app_decisions.rst')
+    repo_docs.build_rst_docs(root_title='docs - tree')
+    repo_docs.build_apps_index(root / 'docs' / 'references' / 'app_index.rst')
+    repo_docs.build_decisions_index(root / 'docs' / 'references' / 'app_adr_index.rst')
 
     docs_path = root / 'docs'
     apidoc_path = 'sphinx-apidoc'

docs/decisions/index.rst

@@ -2,4 +2,3 @@
 
 .. toctree::
    0*
-   app_decisions

docs/decisions/toctree-reorganization-plan.md

@@ -0,0 +1,154 @@
+# Plan: Re-organize ReadTheDocs Tree
+
+## 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)
+```
+
+(Full TinyMCE title: "TinyMCE (Visual Text/HTML Editor) Plugins")
+
+Note: `decisions/index.rst` has no valid RST title (`# edx-platform Technical
+Decisions` lacks an underline), so Sphinx drops its toctree children entirely.
+The numbered decisions (0000-0026) are not in the sidebar. `app_decisions` appears
+because `docs/index.rst` also references it directly via an inline `:doc:` link in
+the "App Documentation" grid card. Fixing `decisions/index.rst` is out of scope here.
+
+---
+
+## Context
+
+The docs tree has two structural issues to fix:
+1. How-To Guides and TinyMCE plugins are top-level sections, but belong under Concepts.
+2. App-Level Documentation and App-Level ADRs are top-level items, but belong under References.
+
+Generated files are produced during the Sphinx `builder-inited` hook (`docs/conf.py` ->
+`on_init()` -> `docs/repository_docs.py`). They must not be edited statically.
+
+---
+
+## Changes
+
+### 1. `docs/repository_docs.py`
+
+**a. `_create_index_rst_file()`** -- add optional `title` parameter so the root
+`docs/references/docs/index.rst` can have a custom title instead of just "docs":
+```python
+def _create_index_rst_file(self, directory_path, title=None):
+    ...
+    if title is None:
+        title = directory_name
+    file_content = f"""{title}\n{len(title) * '='}\n\n..."""
+```
+
+**b. `build_rst_docs()`** -- accept and forward `root_title`:
+```python
+def build_rst_docs(self, root_title=None):
+    os.makedirs(self.build_path, exist_ok=True)
+    self._create_index_rst_file(self.build_path, title=root_title)
+    ...
+```
+
+**c. `build_apps_index()`** -- output moves to `docs/references/` directly. Update:
+- Title: `"docs - App index"`
+- `:doc:` links: relative from `docs/references/` -> `docs/{rel}/index`
+
+**d. `build_decisions_index()`** -- same path move. Update:
+- Title: `"docs - App ADR index"`
+- Intro sentence: `'Links to per-app Architecture Decision Records (ADR) directories, supplementing the top-level'`
+- Cross-ref to repo-wide decisions: `../decisions/0001-courses-in-lms`
+- `:doc:` links: relative from `docs/references/` -> `docs/{rel_from_root}/index`
+
+### 2. `docs/conf.py` (`on_init`)
+
+```python
+repo_docs.build_rst_docs(root_title='docs - tree')
+repo_docs.build_apps_index(root / 'docs' / 'references' / 'app_index.rst')
+repo_docs.build_decisions_index(root / 'docs' / 'references' / 'app_adr_index.rst')
+```
+Old paths `docs/apps/` and `docs/decisions/app_decisions.rst` are removed.
+
+No changes needed to `docs/references/index.rst` -- its existing `*` glob picks up
+the new files automatically; `docs/index` and `docstrings/index` are already there.
+
+### 3. Move how-to files; delete `docs/how-tos/`
+
+Physically move:
+- `docs/how-tos/celery.rst` -> `docs/concepts/celery.rst`
+- `docs/how-tos/use_the_api.rst` -> `docs/concepts/use_the_api.rst`
+
+Delete `docs/how-tos/` entirely (its `index.rst` was a bare glob toctree with no content).
+
+### 4. `docs/concepts/index.rst`
+
+- Rename title: `Concepts and Guides` -> `Concepts and "How-To" Guides`
+- Add to toctree (flat -- no subsection wrapper):
+  ```
+  ../extensions/tinymce_plugins
+  celery
+  use_the_api
+  ```
+
+### 5. `docs/decisions/index.rst`
+
+Remove `app_decisions` from the toctree (it is no longer generated at that path).
+
+### 6. `docs/index.rst`
+
+**Hidden toctree** -- remove these entries (now included via other sections):
+- `how-tos/index` (now under concepts)
+- `extensions/tinymce_plugins` (now under concepts)
+- `apps/index` (no longer generated at this path)
+
+**Grid cards** (independent of toctree navigation, but `:doc:` links inside them are
+validated by Sphinx and must point to existing files):
+- Remove **"How-tos"** card (merged into Concepts).
+- Rename **"Concepts"** card -> **"Concepts and How-To Guides"**.
+- Remove the `:doc:` line for `extensions/tinymce_plugins` from **"Hooks and Extensions"** (external link stays).
+- **"App Documentation"** card stays, but update its `:doc:` references to new paths:
+  - `:doc:`decisions/app_decisions`` -> `:doc:`references/app_adr_index``
+  - `:doc:`apps/index`` -> `:doc:`references/app_index``
+  - `button-ref:: apps/index` -> `button-ref:: references/app_index`
+
+### 7. `docs/redirects.txt`
+
+The repo uses `sphinxext.rediraffe` for internal page moves (see existing entries).
+Add two entries for the moved how-tos:
+
+```
+"how-tos/celery.rst" "concepts/celery.rst"
+"how-tos/use_the_api.rst" "concepts/use_the_api.rst"
+```
+
+(`redirects` dict in `conf.py` is for external URL redirects only.)
+
+---
+
+## Verification
+
+```
+cd docs && make html
+```
+- "Concepts and How-To Guides" section contains TinyMCE and the how-to pages (flat).
+- References sidebar shows `docs - App ADR index`, `docs - App index`, `docs - tree`
+  as sibling items alongside the existing references.
+- No orphan-document Sphinx warnings.
+- "App Documentation" grid card on the homepage links correctly to the new paths.

docs/index.rst

@@ -30,28 +30,14 @@ locations.
 .. toctree::
     :hidden:
 
-    how-tos/index
     references/index
     concepts/index
-    extensions/tinymce_plugins
     decisions/index
-    apps/index
 
 .. grid:: 1 2 2 2
    :gutter: 3
    :padding: 0
 
-   .. grid-item-card:: How-tos
-      :class-card: sd-shadow-md sd-p-2
-      :class-footer: sd-border-0
-
-      * :doc:`how-tos/celery`
-      +++
-      .. button-ref:: how-tos/index
-         :color: primary
-         :outline:
-         :expand:
-
    .. grid-item-card:: References
       :class-card: sd-shadow-md sd-p-2
       :class-footer: sd-border-0
@@ -65,7 +51,7 @@ locations.
          :outline:
          :expand:
 
-   .. grid-item-card:: Concepts
+   .. grid-item-card:: Concepts and How-To Guides
       :class-card: sd-shadow-md sd-p-2
       :class-footer: sd-border-0
 
@@ -83,7 +69,6 @@ locations.
       :class-footer: sd-border-0
 
       * `Hooks Extensions Framework`_
-      * :doc:`extensions/tinymce_plugins`
       +++
       .. button-link:: https://docs.openedx.org/en/latest/developers/concepts/hooks_extension_framework.html
          :color: primary
@@ -96,10 +81,10 @@ locations.
       :class-card: sd-shadow-md sd-p-2
       :class-footer: sd-border-0
 
-      * :doc:`apps/index`
-      * :doc:`decisions/app_decisions`
+      * :doc:`references/app_index`
+      * :doc:`references/app_adr_index`
       +++
-      .. button-ref:: apps/index
+      .. button-ref:: references/app_index
          :color: primary
          :outline:
          :expand:

docs/redirects.txt

@@ -1,2 +1,4 @@
 "featuretoggles.rst" "references/featuretoggles.rst"
 "settings.rst" "references/settings.rst"
+"how-tos/celery.rst" "concepts/celery.rst"
+"how-tos/use_the_api.rst" "concepts/use_the_api.rst"

docs/repository_docs.py

@@ -34,9 +34,9 @@ def __init__(
         self.patterns_to_exclude_dirs = patterns_to_exclude_dirs
         self.patterns_to_exclude_files = patterns_to_exclude_files
 
-    def build_rst_docs(self):
+    def build_rst_docs(self, root_title=None):
         os.makedirs(self.build_path, exist_ok=True)
-        self._create_index_rst_file(self.build_path)
+        self._create_index_rst_file(self.build_path, title=root_title)
         rst_files = self._find_rst_files()
         self._copy_files(rst_files)
 
@@ -62,13 +62,15 @@ def _get_directories_list_on_path(self, path):
             path = os.path.dirname(path)
         return directory_paths
 
-    def _create_index_rst_file(self, directory_path):
+    def _create_index_rst_file(self, directory_path, title=None):
         directory_name = os.path.basename(directory_path)
         file_path = os.path.join(directory_path, "index.rst")
-        if os.path.exists(file_path):
+        if os.path.exists(file_path) and title is None:
             return
-        file_content = f"""{directory_name}
-{len(directory_name) * '='}
+        if title is None:
+            title = directory_name
+        file_content = f"""{title}
+{len(title) * '='}
 
 .. toctree::
    :glob:
@@ -113,8 +115,8 @@ def build_apps_index(self, output_path):
         Written to output_path (overwritten on each build).
         """
         lines = [
-            'App-Level Documentation',
-            '=======================',
+            'docs - App index',
+            '================',
             '',
             'Quick-scan index of Django apps that have README files or documentation.',
             'Each link opens the auto-generated index for that app.',
@@ -134,7 +136,7 @@ def build_apps_index(self, output_path):
                 has_readme = os.path.isfile(os.path.join(app_path, 'README.rst'))
                 has_docs = os.path.isdir(os.path.join(app_path, 'docs'))
                 if has_readme or has_docs:
-                    # Path relative to docs/references/docs/ (where the generated tree lives)
+                    # :doc: links below are relative to docs/references/ (where this file is generated)
                     rel = f'{service_dir}/{app_name}'
                     app_entries.append((app_name, rel))
 
@@ -144,7 +146,7 @@ def build_apps_index(self, output_path):
             heading = service_dir
             lines += [heading, '-' * len(heading), '']
             for app_name, rel in app_entries:
-                lines.append(f'* :doc:`{app_name} <../references/docs/{rel}/index>`')
+                lines.append(f'* :doc:`{app_name} <docs/{rel}/index>`')
             lines.append('')
 
         os.makedirs(os.path.dirname(output_path), exist_ok=True)
@@ -178,21 +180,19 @@ def build_decisions_index(self, output_path):
                 decisions_by_service[service_dir] = sorted(entries)
 
         lines = [
-            'App-Level Architecture Decision Records',
-            '========================================',
+            'docs - App ADR index',
+            '====================',
             '',
-            'Links to per-app ADR directories, supplementing the top-level',
-            ':doc:`repo-wide decisions <0001-courses-in-lms>`.',
+            'Links to per-app Architecture Decision Records (ADR) directories, supplementing the top-level',
+            ':doc:`repo-wide decisions <../decisions/0001-courses-in-lms>`.',
             '',
         ]
 
         for service_dir, entries in decisions_by_service.items():
             heading = service_dir
             lines += [heading, '-' * len(heading), '']
             for label, rel_from_root in entries:
-                # Path relative to docs/decisions/ (where this file lives)
-                link = f'../references/docs/{rel_from_root}/index'
-                # Normalise to forward slashes
+                link = f'docs/{rel_from_root}/index'
                 link = link.replace(os.sep, '/')
                 lines.append(f'* :doc:`{label} <{link}>`')
             lines.append('')