fix: make docs warnings

Author: Muhammad Faraz Maqsood

docs/conf.py

@@ -53,12 +53,26 @@
     ("py:class", "click.core.Command"),
     # Python 3.12
     ("py:class", "FilterCallbackFunc"),
+    # Sphinx internals that may leak through rendered type hints
+    ("py:class", "TypeAliasForwardRef"),
+    # ParamSpec objects are not classes but may be referenced as such
+    ("py:class", "tutor.core.hooks.actions.T"),
+    ("py:class", "typing_extensions.ParamSpec"),
 ]
+
+# Even outside nitpicky mode, some type-hint rendering can produce "ref.class"
+# warnings for typing-related objects that are not meaningfully documentable here.
+# These warnings are not actionable for Tutor maintainers and would otherwise fail
+# the build because `make docs` runs with `-W`.
+suppress_warnings = ["ref.class"]
 # Resolve type aliases here
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_type_aliases
 autodoc_type_aliases: dict[str, str] = {
     # python 3.10
-    "T": "tutor.core.hooks.actions.T",
+    # ParamSpec instances (like `tutor.core.hooks.actions.T`) are not classes, and Sphinx
+    # will attempt to resolve them as `py:class` when rendering type hints. Point to the
+    # ParamSpec type itself to avoid unresolved references.
+    "T": "typing_extensions.ParamSpec",
     "T2": "tutor.core.hooks.filters.T2",
     # # python 3.12
     "L": "tutor.core.hooks.filters.L",

docs/gettingstarted/installation.rst

@@ -1,4 +1,5 @@
 .. _installation:
+.. _install:
 
 Installation
 ============

docs/gettingstarted/quickstart.rst

@@ -1,3 +1,5 @@
+.. _quickstart:
+
 Quickstart (1-click install)
 ============================
 

docs/plugins/index.rst

@@ -64,4 +64,9 @@ To disable an index, for instance "contrib", use the ``plugins index remove`` co
 
     tutor plugins index remove contrib
 
-For more information about these indexes, check the `official Tutor plugin indexes (TPI) <https://github.com/overhangio/tpi/>`__ repository.
+For more information about these indexes, check the `official Tutor plugin indexes (TPI) <https://github.com/overhangio/tpi/>`__ repository.
+
+Development
+===========
+
+For information on developing your own Tutor plugins, see the :ref:`plugin_development` guide.

docs/reference/api/hooks/actions.rst

@@ -10,5 +10,6 @@ Actions are one of the two types of hooks (the other being :ref:`filters`) that
     :members:
 
 .. The following are only to ensure that the docs build without warnings
-.. class:: tutor.core.hooks.actions.T
-.. class:: tutor.types.Config
+.. py:class:: tutor.core.hooks.actions.T
+.. py:class:: tutor.types.Config
+.. py:class:: typing_extensions.ParamSpec

docs/sysadmin/index.rst

@@ -4,6 +4,7 @@ System administration
 .. toctree::
    :maxdepth: 1
 
+   edx-platform
    scale
    portainer
    podman

docs/tutor.rst

@@ -1,4 +1,5 @@
 .. _tutor:
+.. _development:
 
 Tutor development
 =================