Add flag to skip generation of reference docs when running sphinx (#1532

)

README.md

@@ -35,8 +35,8 @@ py -3 -m pip install -U hikari
 ## Bots
 
 Hikari provides two different default bot implementations to suit your needs:
-- [GatewayBot](#GatewayBot)
-- [RESTBot](#RESTBot)
+- [GatewayBot](#gatewaybot)
+- [RESTBot](#restbot)
 
 ### GatewayBot
 

docs/conf.py

@@ -57,16 +57,22 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx.ext.mathjax",
-    # Docs generation
-    "autoapi.extension",
-    "numpydoc",
+    # Our extensions
     "myst_parser",
-    # Misc
     "sphinxext.opengraph",
     "sphinx_copybutton",
     "sphinxcontrib.towncrier.ext",
 ]
 
+if os.getenv("SKIP_REFERENCE_DOCS") is None:
+    extensions.extend(
+        (
+            "autoapi.extension",
+            "numpydoc",
+        )
+    )
+
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 

hikari/api/rest.py

@@ -2738,6 +2738,7 @@ async def set_my_user_application_role_connection(
             Depending on the time of the previously created application role
             records through `set_application_role_connection_metadata_records`,
             this mapping should contain those keys to the valid type of the record:
+
                 - `INTEGER_X`: An `int`.
                 - `DATETIME_X`: A `datetime.datetime` object.
                 - `BOOLEAN_X`: A `bool`.

pipelines/sphinx.nox.py

@@ -36,6 +36,9 @@
 @nox.session(reuse_venv=True)
 def sphinx(session: nox.Session):
     """Generate docs using sphinx."""
+    if "--no-refs" in session.posargs:
+        session.env["SKIP_REFERENCE_DOCS"] = "1"
+
     if not os.path.exists(config.ARTIFACT_DIRECTORY):
         os.mkdir(config.ARTIFACT_DIRECTORY)