docs: Re-organize docs a bit

pawamoy · pawamoy · commit d37a137e1642 · 2023-05-01T16:32:16.000+02:00
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -48,7 +48,7 @@ when it should be `[Section][pytkdocs.parsers.docstrings.Section]`.
 ## Some objects are not rendered (they do not appear in the generated docs)
 
 - Make sure the configuration options of the handler are correct.
-  Check the documentation for [Handlers](handlers/overview.md) to see the available options for each handler.
+  Check the documentation for [Handlers](usage/handlers.md) to see the available options for each handler.
 - Also make sure your documentation in your source code is formatted correctly.
   For Python code, check the [supported docstring styles](https://mkdocstrings.github.io/python/usage/#supported-docstrings-styles) page.
 - Re-run the Mkdocs command with `-v`, and carefully read any traceback.
@@ -116,13 +116,13 @@ use this workaround.
 
 Please open an ticket on the [bugtracker][bugtracker] with a detailed
 explanation and screenshots of the bad-looking parts.
-Note that you can always [customize the look](theming.md) of *mkdocstrings* blocks -- through both HTML and CSS.
+Note that you can always [customize the look](usage/theming.md) of *mkdocstrings* blocks -- through both HTML and CSS.
 
 ## Warning: could not find cross-reference target
 
 TIP: **New in version 0.15.**  
 Cross-linking used to include any Markdown heading, but now it's only for *mkdocstrings* identifiers by default.
-See [Cross-references to any Markdown heading](usage.md#cross-references-to-any-markdown-heading) to opt back in.
+See [Cross-references to any Markdown heading](usage/index.md#cross-references-to-any-markdown-heading) to opt back in.
 
 Make sure the referenced object is properly rendered: verify your configuration options.
 
diff --git a/docs/usage/handlers.md b/docs/usage/handlers.md
@@ -5,8 +5,8 @@ A handler is what makes it possible to collect and render documentation for a pa
 ## Available handlers
 
 - <a class="external" href="https://mkdocstrings.github.io/crystal/">Crystal</a>
+- <a class="external" href="https://mkdocstrings.github.io/python/">Python</a>
 - <a class="external" href="https://mkdocstrings.github.io/python-legacy/">Python (Legacy)</a>
-- <a class="external" href="https://mkdocstrings.github.io/python/">Python (Experimental)</a>
 
 ## About the Python handlers
 
diff --git a/docs/usage/index.md b/docs/usage/index.md
@@ -142,7 +142,7 @@ The above is equivalent to:
     ```
 
 Some handlers accept additional global configuration.
-Check the documentation for your handler of interest in [Handlers](handlers/overview.md).
+Check the documentation for your handler of interest in [Handlers](handlers.md).
 
 ## Cross-references
 
diff --git a/docs/usage/theming.md b/docs/usage/theming.md
diff --git a/mkdocs.insiders.yml b/mkdocs.insiders.yml
@@ -1,4 +1,5 @@
 INHERIT: mkdocs.yml
 
-plugins:
-  typeset: {}
+# waiting for https://github.com/squidfunk/mkdocs-material/issues/5446
+# plugins:
+#   typeset: {}
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -15,15 +15,16 @@ nav:
   - Credits: credits.md
   - License: license.md
 - Usage:
-  - usage.md
-  - Theming: theming.md
-  - Handlers:
-    - handlers/overview.md
+  - usage/index.md
+  - Theming: usage/theming.md
+  - Handlers: usage/handlers.md
+  - All handlers:
     - Crystal: https://mkdocstrings.github.io/crystal/
+    - Python: https://mkdocstrings.github.io/python/
     - Python (Legacy): https://mkdocstrings.github.io/python-legacy/
-    - Python (Experimental): https://mkdocstrings.github.io/python/
-  - Recipes: recipes.md
-  - Troubleshooting: troubleshooting.md
+  - Guides:
+    - Recipes: recipes.md
+    - Troubleshooting: troubleshooting.md
 # defer to gen-files + literate-nav
 - Code Reference: reference/
 - Development:
@@ -91,6 +92,7 @@ markdown_extensions:
 - pymdownx.emoji:
     emoji_index: !!python/name:materialx.emoji.twemoji
     emoji_generator: !!python/name:materialx.emoji.to_svg
+- pymdownx.details
 - pymdownx.magiclink
 - pymdownx.snippets:
     check_paths: true
@@ -129,6 +131,10 @@ plugins:
   git-committers:
     enabled: !ENV [DEPLOY, false]
     repository: mkdocstrings/mkdocstrings
+  redirects:
+    redirect_maps:
+      theming.md: usage/theming.md
+      handlers/overview.md: usage/handlers.md
   minify:
     minify_html: !ENV [DEPLOY, false]
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -77,6 +77,7 @@ docs = [
     "mkdocs-literate-nav>=0.4",
     "mkdocs-material>=7.3",
     "mkdocs-minify-plugin>=0.6.4",
+    "mkdocs-redirects>=1.2.0",
     "mkdocstrings-python>=0.5.1",
     "toml>=0.10",
 ]
diff --git a/scripts/gen_redirects.py b/scripts/gen_redirects.py

Original file line number	Diff line number	Diff line change
`@@ -77,6 +77,7 @@ docs = [`
`77`	`77`	`"mkdocs-literate-nav>=0.4",`
`78`	`78`	`"mkdocs-material>=7.3",`
`79`	`79`	`"mkdocs-minify-plugin>=0.6.4",`
	`80`	`+ "mkdocs-redirects>=1.2.0",`
`80`	`81`	`"mkdocstrings-python>=0.5.1",`
`81`	`82`	`"toml>=0.10",`
`82`	`83`	`]`