docs: Improve toctrees & sidebar formatting (#1773)

* docs: Improve toctrees & sidebar formatting

* Undo font change

I'm not sure if this change should be made yet, so I'm not going to include it in this PR

* Add collapsing attribute lists

Co-authored-by: Lala Sabathil <[email protected]>

Author: BobDotCom

docs/_static/css/custom.css

@@ -159,3 +159,13 @@ img[src="_images/snake_dark.svg"] {
 .sidebar-logo {
   max-width: 60%;
 }
+
+/*.sidebar-tree {*/
+/*  font-family: "Saira", monospace;*/
+/*}*/
+
+.has-selector-alternative {
+  transition: max-height 0.2s ease-out;
+  max-height: 0;
+  overflow: hidden;
+}

docs/_static/js/custom.js

@@ -6,4 +6,50 @@ document.addEventListener("DOMContentLoaded", () => {
     // insert ourselves after the element
     parent.insertBefore(table, element.nextSibling);
   });
+
+  // This can be replaced once the css :has() selector is mainstream
+  // https://developer.mozilla.org/en-US/docs/Web/CSS/:has
+  // .reference.internal:has(code) + ul
+  const tocObjects = document.querySelectorAll(
+    ".toc-tree li > .reference.internal:not(:only-child) code",
+  );
+  tocObjects.forEach((e) => {
+    e.parentElement.parentElement
+      .querySelector(".reference.internal + ul")
+      .classList.add("has-selector-alternative");
+  });
+});
+
+// We could use this css instead, but it doesn't allow for the transition
+// :not(.scroll-current) > .reference.internal:has(code) + ul:not(:has(.scroll-current))
+
+const getCurrentTocObject = (e) => {
+  let target = null;
+  let next = e.target;
+  while (true) {
+    if (
+      next.firstElementChild.classList.contains("reference") &&
+      next.firstElementChild.firstElementChild?.localName === "code"
+    ) {
+      target = next;
+      next = target.parentElement.parentElement;
+    } else {
+      break;
+    }
+  }
+  return target?.querySelector("ul");
+};
+
+document.addEventListener("gumshoeActivate", (e) => {
+  const target = getCurrentTocObject(e);
+  if (target) {
+    target.style.maxHeight = target.scrollHeight + "px";
+  }
+});
+
+document.addEventListener("gumshoeDeactivate", (e) => {
+  const target = getCurrentTocObject(e);
+  if (target) {
+    target.style.maxHeight = "0px";
+  }
 });

docs/ext/bridge/index.rst

@@ -1,7 +1,7 @@
 .. _discord_ext_bridge:
 
-``discord.ext.bridge`` -- A module that bridges slash commands to prefixed commands
-===================================================================================
+discord.ext.bridge
+==================
 
 .. versionadded:: 2.0
 

docs/ext/commands/index.rst

@@ -1,7 +1,7 @@
 .. _discord_ext_commands:
 
-``discord.ext.commands`` -- Bot commands framework
-==================================================
+discord.ext.commands
+====================
 
 ``Pycord`` offers a lower level aspect on interacting with Discord. Often times, the library is used for the creation of
 bots. However this task can be daunting and confusing to get correctly the first time. Many times there comes a repetition in

docs/ext/pages/index.rst

@@ -1,7 +1,7 @@
 .. _discord_ext_pages:
 
-``discord.ext.pages`` -- A pagination extension module
-======================================================
+discord.ext.pages
+=================
 
 .. versionadded:: 2.0
 

docs/ext/tasks/index.rst

@@ -1,7 +1,7 @@
 .. _discord_ext_tasks:
 
-``discord.ext.tasks`` -- asyncio.Task helpers
-=============================================
+discord.ext.tasks
+=================
 
 .. versionadded:: 1.1.0
 

docs/index.rst

@@ -59,22 +59,36 @@ Extensions
 These extensions help you during development when it comes to common tasks.
 
 .. toctree::
+  :caption: Extensions
   :maxdepth: 1
+  :hidden:
 
   ext/commands/index.rst
   ext/tasks/index.rst
   ext/pages/index.rst
   ext/bridge/index.rst
 
+- :doc:`ext/commands/index` - Bot commands framework
+- :doc:`ext/tasks/index` - asyncio.Task helpers
+- :doc:`ext/pages/index` - A pagination extension module
+- :doc:`ext/bridge/index` - A module that bridges slash commands to prefixed commands
+
 Meta
 ----
 
 If you're looking for something related to the project itself, it's here.
 
 .. toctree::
+  :caption: Meta
   :maxdepth: 1
+  :hidden:
 
   changelog
   version_guarantees
   migrating_to_v1
   migrating_to_v2
+
+- :doc:`changelog` - The changelog for the library.
+- :doc:`version_guarantees` - The version guarantees for the library.
+- :doc:`migrating_to_v1` - How to migrate from v0.x to v1.x.
+- :doc:`migrating_to_v2` - How to migrate from v1.x to v2.x.