Revising the index page of the plugins section in our documentation (c…

…onda#12802)

* minor changes to code and revising the plugins index page in our documentation

* updating the license section

* making the API documentation for plugins better

* Additional documentation fixes and removal of manager.rst file

* Apply suggestions from code review

---------

Co-authored-by: Jannis Leidel <[email protected]>
Co-authored-by: Ken Odegard <[email protected]>
Co-authored-by: Bianca Henderson <[email protected]>
Co-authored-by: Katherine Kinnaman <[email protected]>

conda/plugins/__init__.py

@@ -1,5 +1,30 @@
 # Copyright (C) 2012 Anaconda, Inc
 # SPDX-License-Identifier: BSD-3-Clause
+"""
+In this module, you will find everything relevant to conda's plugin system.
+It contains all of the code that plugin authors will use to write plugins,
+as well as conda's internal implementations of plugins.
+
+**Modules relevant for plugin authors**
+
+- :mod:`conda.plugins.hookspec`: all available hook specifications are listed here, including
+  examples of how to use them
+- :mod:`conda.plugins.types`: important types to use when defining plugin hooks
+
+**Modules relevant for internal development**
+
+- :mod:`conda.plugins.manager`: includes our custom subclass of pluggy's
+  `PluginManager <https://pluggy.readthedocs.io/en/stable/api_reference.html#pluggy.PluginManager>`_ class
+
+**Modules with internal plugin implementations**
+
+- :mod:`conda.plugins.solvers`: implementation of the "classic" solver
+- :mod:`conda.plugins.subcommands.doctor`: ``conda doctor`` subcommand
+- :mod:`conda.plugins.virtual_packages`: registers virtual packages in conda
+
+"""  # noqa: E501
+
+
 from .hookspec import hookimpl  # noqa: F401
 from .types import (  # noqa: F401
     CondaPostCommand,

conda/plugins/hookspec.py

@@ -1,6 +1,12 @@
 # Copyright (C) 2012 Anaconda, Inc
 # SPDX-License-Identifier: BSD-3-Clause
-"""Pluggy hookspecs to register conda plugins."""
+"""
+Pluggy hook specifications ("hookspecs") to register conda plugins.
+
+Each hookspec defined in :class:`~conda.plugins.hookspec.CondaSpecs` contains
+an example of how to use it.
+
+"""
 from __future__ import annotations
 
 from collections.abc import Iterable
@@ -16,8 +22,17 @@
 )
 
 spec_name = "conda"
+"""Name used for organizing conda hook specifications"""
+
 _hookspec = pluggy.HookspecMarker(spec_name)
+"""
+The conda plugin hook specifications, to be used by developers
+"""
+
 hookimpl = pluggy.HookimplMarker(spec_name)
+"""
+Decorator used to mark plugin hook implementations
+"""
 
 
 class CondaSpecs:
@@ -53,7 +68,7 @@ def conda_solvers():
                     backend=VerboseSolver,
                 )
 
-        :return: An iterable of solvers entries.
+        :return: An iterable of solver entries.
         """
 
     @_hookspec
@@ -109,7 +124,7 @@ def conda_virtual_packages():
     @_hookspec
     def conda_pre_commands(self) -> Iterable[CondaPreCommand]:
         """
-        Register pre-commands functions in conda.
+        Register pre-command functions in conda.
 
         **Example:**
 
@@ -134,7 +149,7 @@ def conda_pre_commands():
     @_hookspec
     def conda_post_commands(self) -> Iterable[CondaPostCommand]:
         """
-        Register post-commands functions in conda.
+        Register post-command functions in conda.
 
         **Example:**
 

conda/plugins/manager.py

@@ -1,6 +1,12 @@
 # Copyright (C) 2012 Anaconda, Inc
 # SPDX-License-Identifier: BSD-3-Clause
-"""The conda plugin manager that loads all plugins on startup."""
+"""
+This module contains a subclass implementation of pluggy's
+`PluginManager <https://pluggy.readthedocs.io/en/stable/api_reference.html#pluggy.PluginManager>`_.
+
+Additionally, it contains a function we use to construct the ``PluginManager`` object and
+register all plugins during conda's startup process.
+"""
 from __future__ import annotations
 
 import functools
@@ -22,8 +28,7 @@
 
 class CondaPluginManager(pluggy.PluginManager):
     """
-    The conda plugin manager to implement behavior additional to
-    pluggy's default plugin manager.
+    The conda plugin manager to implement behavior additional to pluggy's default plugin manager.
     """
 
     #: Cached version of the :meth:`~conda.plugins.manager.CondaPluginManager.get_solver_backend`
@@ -44,8 +49,8 @@ def __init__(self, project_name: str | None = None, *args, **kwargs) -> None:
     def load_plugins(self, *plugins) -> list[str]:
         """
         Load the provided list of plugins and fail gracefully on error.
-        The provided list plugins can either be classes or modules with
-        :attr:`~conda.plugins.hook_impl`.
+        The provided list of plugins can either be classes or modules with
+        :attr:`~conda.plugins.hookimpl`.
         """
         plugin_names = []
         for plugin in plugins:
@@ -61,6 +66,7 @@ def load_plugins(self, *plugins) -> list[str]:
 
     def load_entrypoints(self, group: str, name: str | None = None) -> int:
         """Load modules from querying the specified setuptools ``group``.
+
         :param str group: Entry point group to load plugins.
         :param str name: If given, loads only plugins with the given ``name``.
         :rtype: int
@@ -179,8 +185,8 @@ def yield_command_hook_actions(self, hook_type: CommandHookTypes, command: str):
 @functools.lru_cache(maxsize=None)  # FUTURE: Python 3.9+, replace w/ functools.cache
 def get_plugin_manager() -> CondaPluginManager:
     """
-    Get a cached version of the :class:`~conda.plugins.manager.CondaPluginManager`
-    instance, with the built-in and the entrypoints provided plugins loaded.
+    Get a cached version of the :class:`~conda.plugins.manager.CondaPluginManager` instance,
+    with the built-in and entrypoints provided by the plugins loaded.
     """
     plugin_manager = CondaPluginManager()
     plugin_manager.add_hookspecs(CondaSpecs)

conda/plugins/types.py

@@ -1,19 +1,27 @@
 # Copyright (C) 2012 Anaconda, Inc
 # SPDX-License-Identifier: BSD-3-Clause
-"""Define types for conda plugins to be using in conjunction with the hookspecs."""
+"""
+Definition of specific return types for use when defining a conda plugin hook.
+
+Each type corresponds to the plugin hook for which it is used.
+
+"""
 from __future__ import annotations
 
 from typing import Callable, Literal, NamedTuple
 
 from ..core.solve import Solver
 
-#: These are the two different types of conda_*_commands hooks that are available
 CommandHookTypes = Literal["pre", "post"]
+"""The two different types of `conda_*_commands` hooks that are available"""
 
 
 class CondaSubcommand(NamedTuple):
     """
-    A conda subcommand.
+    Return type to use when defining a conda subcommand plugin hook.
+
+    For details on how this is used, see
+    :meth:`~conda.plugins.hookspec.CondaSpecs.conda_subcommands`.
 
     :param name: Subcommand name (e.g., ``conda my-subcommand-name``).
     :param summary: Subcommand summary, will be shown in ``conda --help``.
@@ -30,7 +38,10 @@ class CondaSubcommand(NamedTuple):
 
 class CondaVirtualPackage(NamedTuple):
     """
-    A conda virtual package.
+    Return type to use when defining a conda virtual package plugin hook.
+
+    For details on how this is used, see
+    :meth:`~conda.plugins.hookspec.CondaSpecs.conda_virtual_packages`.
 
     :param name: Virtual package name (e.g., ``my_custom_os``).
     :param version: Virtual package version (e.g., ``1.2.3``).
@@ -44,7 +55,10 @@ class CondaVirtualPackage(NamedTuple):
 
 class CondaSolver(NamedTuple):
     """
-    A conda solver.
+    Return type to use when defining a conda solver plugin hook.
+
+    For details on how this is used, see
+    :meth:`~conda.plugins.hookspec.CondaSpecs.conda_solvers`.
 
     :param name: Solver name (e.g., ``custom-solver``).
     :param backend: Type that will be instantiated as the solver backend.
@@ -56,11 +70,14 @@ class CondaSolver(NamedTuple):
 
 class CondaPreCommand(NamedTuple):
     """
-    Allows a plugin hook to execute before an invoked conda command is run.
+    Return type to use when defining a conda pre-command plugin hook.
+
+    For details on how this is used, see
+    :meth:`~conda.plugins.hookspec.CondaSpecs.conda_pre_commands`.
 
     :param name: Pre-command name (e.g., ``custom_plugin_pre_commands``).
     :param action: Callable which contains the code to be run.
-    :param run_for: Represents the command(s) this will be run on (e.g. install or create).
+    :param run_for: Represents the command(s) this will be run on (e.g. ``install`` or ``create``).
     """
 
     name: str
@@ -70,11 +87,14 @@ class CondaPreCommand(NamedTuple):
 
 class CondaPostCommand(NamedTuple):
     """
-    Allows a plugin hook to execute after an invoked conda command is run.
+    Return type to use when defining a conda post-command plugin hook.
+
+    For details on how this is used, see
+    :meth:`~conda.plugins.hookspec.CondaSpecs.conda_post_commands`.
 
     :param name: Post-command name (e.g., ``custom_plugin_post_commands``).
     :param action: Callable which contains the code to be run.
-    :param run_for: Represents the command(s) this will be run on (e.g. install or create).
+    :param run_for: Represents the command(s) this will be run on (e.g. ``install`` or ``create``).
     """
 
     name: str