Rework index page to take less vertical space

docs/conf.py

@@ -40,6 +40,7 @@ extensions = [
     'details',
     'exception_hierarchy',
     'attributetable',
+    'resourcelinks',
 ]
 
 autodoc_member_order = 'bysource'
@@ -91,6 +92,9 @@ with open('../discord/__init__.py') as f:
 # The full version, including alpha/beta/rc tags.
 release = version
 
+# This assumes a tag is available for final releases
+branch = 'master' if version.endswith('a') else version
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -152,6 +156,13 @@ html_context = {
   ],
 }
 
+resource_links = {
+  'discord': 'https://discord.gg/r3sSKJJ',
+  'issues': 'https://github.com/Rapptz/discord.py/issues',
+  'discussions': 'https://github.com/Rapptz/discord.py/discussions',
+  'examples': 'https://github.com/Rapptz/discord.py/tree/%s/examples' % branch,
+}
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
@@ -337,3 +348,4 @@ def setup(app):
   if app.config.language == 'ja':
     app.config.intersphinx_mapping['py'] = ('https://docs.python.org/ja/3', None)
     app.config.html_context['discord_invite'] = 'https://discord.gg/nXzj3dg'
+    app.config.resource_links['discord'] = 'https://discord.gg/nXzj3dg'

docs/extensions/resourcelinks.py

@@ -0,0 +1,44 @@
+# Credit to sphinx.ext.extlinks for being a good starter
+# Copyright 2007-2020 by the Sphinx team
+# Licensed under BSD.
+
+from typing import Any, Dict, List, Tuple
+
+from docutils import nodes, utils
+from docutils.nodes import Node, system_message
+from docutils.parsers.rst.states import Inliner
+
+import sphinx
+from sphinx.application import Sphinx
+from sphinx.util.nodes import split_explicit_title
+from sphinx.util.typing import RoleFunction
+
+
+def make_link_role(resource_links: Dict[str, str]) -> RoleFunction:
+    def role(
+        typ: str,
+        rawtext: str,
+        text: str,
+        lineno: int,
+        inliner: Inliner,
+        options: Dict = {},
+        content: List[str] = []
+    ) -> Tuple[List[Node], List[system_message]]:
+
+        text = utils.unescape(text)
+        has_explicit_title, title, key = split_explicit_title(text)
+        full_url = resource_links[key]
+        if not has_explicit_title:
+            title = full_url
+        pnode = nodes.reference(title, title, internal=False, refuri=full_url)
+        return [pnode], []
+    return role
+
+
+def add_link_role(app: Sphinx) -> None:
+    app.add_role('resource', make_link_role(app.config.resource_links))
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    app.add_config_value('resource_links', {}, 'env')
+    app.connect('builder-inited', add_link_role)
+    return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

docs/index.rst

@@ -21,41 +21,57 @@ for Discord.
 - Easy to use with an object oriented design
 - Optimised for both speed and memory
 
-Documentation Contents
+Getting started
------------------------
+-----------------
 
-.. toctree::
+Is this your first time using the library? This is the place to get started!
-   :maxdepth: 2
 
-   intro
+- **First steps:** :doc:`intro` | :doc:`quickstart` | :doc:`logging`
-   quickstart
+- **Working with Discord:** :doc:`discord` | :doc:`intents`
-   migrating
+- **Examples:** Many examples are available in the :resource:`repository <examples>`.
-   logging
+
-   api
+Getting help
+--------------
+
+If you're having trouble with something, these resources might help.
+
+- Try the :doc:`faq` first, it's got answers to all common questions.
+- Ask us and hang out with us in our :resource:`Discord <discord>` server.
+- If you're looking for something specific, try the :ref:`index <genindex>` or :ref:`searching <search>`.
+- Report bugs in the :resource:`issue tracker <issues>`.
+- Ask in our :resource:`GitHub discussions page <discussions>`.
 
 Extensions
------------
+------------
+
+These extensions help you during development when it comes to common tasks.
 
 .. toctree::
-  :maxdepth: 3
+  :maxdepth: 1
 
   ext/commands/index.rst
   ext/tasks/index.rst
 
+Manuals
+---------
 
-Additional Information
+These pages go into great detail about everything the API can do.
------------------------
 
 .. toctree::
-    :maxdepth: 2
+  :maxdepth: 1
 
-    discord
+  api
-    intents
+  discord.ext.commands API Reference <ext/commands/api.rst>
-    faq
+  discord.ext.tasks API Reference <ext/tasks/index.rst>
-    whats_new
-    version_guarantees
 
-If you still can't find what you're looking for, try in one of the following pages:
+Meta
+------
 
-* :ref:`genindex`
+If you're looking for something related to the project itself, it's here.
-* :ref:`search`
+
+.. toctree::
+  :maxdepth: 1
+
+  whats_new
+  version_guarantees
+  migrating