Use reST docstring formatting where appropriate

docs/conf.py

@@ -81,6 +81,7 @@
     ("py:class", "_ImportLibDist"),
     ("py:class", "PackageMetadata"),
     ("py:class", "importlib.*"),
+    ("py:class", "IndexContent"),
     ("py:exc", "click.*"),
 ]
 

piptools/_compat/pip_compat.py

@@ -50,9 +50,12 @@ def _from_pkg_resources(cls, dist: _PkgResourcesDist) -> Distribution:
 
     @classmethod
     def _from_importlib(cls, dist: _ImportLibDist) -> Distribution:
-        """Mimics pkg_resources.Distribution.requires for the case of no
-        extras. This doesn't fulfill that API's `extras` parameter but
-        satisfies the needs of pip-tools."""
+        """Mimic pkg_resources.Distribution.requires for the case of no
+        extras.
+
+        This doesn't fulfill that API's ``extras`` parameter but
+        satisfies the needs of pip-tools.
+        """
         reqs = (Requirement.parse(req) for req in (dist._dist.requires or ()))
         requires = [
             req
@@ -63,6 +66,8 @@ def _from_importlib(cls, dist: _ImportLibDist) -> Distribution:
 
 
 class FileLink(Link):  # type: ignore[misc]
+    """Wrapper for ``pip``'s ``Link`` class."""
+
     _url: str
 
     @property

piptools/resolver.py

@@ -152,10 +152,10 @@ class BaseResolver(metaclass=ABCMeta):
 
     @abstractmethod
     def resolve(self, max_rounds: int) -> set[InstallRequirement]:
-        """
+        r"""
         Find concrete package versions for all the given InstallRequirements
-        and their recursive dependencies and return a set of pinned
-        ``InstallRequirement``'s.
+        and their recursive dependencies.
+        :returns: a set of pinned ``InstallRequirement``\ s.
         """
 
     def resolve_hashes(
@@ -199,9 +199,24 @@ def __init__(
         allow_unsafe: bool = False,
         unsafe_packages: set[str] | None = None,
     ) -> None:
-        """
-        Make sure the legacy resolver is enabled and no backtracking resolver
-        is present.
+        """Initialize LegacyResolver.
+
+        :param constraints: the constraints given
+        :type constraints: Iterable[InstallRequirement]
+        :param existing_constraints: constraints already present
+        :param repository: the repository to get the constraints from
+        :type repository: BaseRepository
+        :param cache: the cache to be used
+        :param prereleases: whether prereleases should be taken into account when resolving
+            (default is :py:data:`False`)
+        :param clear_caches: whether to clear repository and dependency caches before resolving
+            (default is :py:data:`False`)
+        :param allow_unsafe: whether unsafe packages should be allowed in the resulting requirements
+            (default is :py:data:`False`)
+        :param unsafe_packages: packages to be considered as unsafe
+            (default is :py:data:`None`)
+        :type unsafe_packages: set[str]
+        :raises: ``PipToolsError`` if the legacy resolver is not enabled
         """
         self.our_constraints = set(constraints)
         self.their_constraints: set[InstallRequirement] = set()
@@ -230,13 +245,15 @@ def constraints(self) -> set[InstallRequirement]:
 
     def resolve(self, max_rounds: int = 10) -> set[InstallRequirement]:
         r"""
-        Find concrete package versions for all the given InstallRequirements
+        Find concrete package versions for all the given ``InstallRequirement``\ s
         and their recursive dependencies and return a set of pinned
         ``InstallRequirement``\ s.
 
         Resolves constraints one round at a time, until they don't change
-        anymore.  Protects against infinite loops by breaking out after a max
-        number rounds.
+        anymore.
+
+        :param max_rounds: break out of resolution process after the given number of rounds
+            to prevent infinite loops (default is 10)
         """
         if self.clear_caches:
             self.dependency_cache.clear()
@@ -324,9 +341,9 @@ def _resolve_one_round(self) -> tuple[bool, set[InstallRequirement]]:
         package versions.  Some of these constraints may be new
         or updated.
 
-        Returns whether new constraints appeared in this round.  If no
-        constraints were added or changed, this indicates a stable
-        configuration.
+        :returns: whether new constraints appeared in this round.  If no
+            constraints were added or changed, this indicates a stable
+            configuration.
         """
         # Sort this list for readability of terminal output
         constraints = sorted(self.constraints, key=key_from_ireq)
@@ -536,8 +553,9 @@ def resolve(self, max_rounds: int = 10) -> set[InstallRequirement]:
         Resolve given ireqs.
 
         Find concrete package versions for all the given InstallRequirements
-        and their recursive dependencies and return a set of pinned
-        ``InstallRequirement``\ s.
+        and their recursive dependencies.
+
+        :returns: A set of pinned ``InstallRequirement``\ s.
         """
         with update_env_context_manager(
             PIP_EXISTS_ACTION="i"
@@ -644,8 +662,9 @@ def _do_resolve(
         """
         Resolve dependencies based on resolvelib ``Resolver``.
 
-        Return :py:data:`True` on successful resolution, otherwise remove problematic
-        requirements from existing constraints and return false.
+        :returns: :py:data:`True` on successful resolution, otherwise removes
+            problematic requirements from existing constraints and
+            returns :py:data:`False`.
         """
         try:
             resolver.resolve(

piptools/sync.py

@@ -43,14 +43,15 @@
 def dependency_tree(
     installed_keys: Mapping[str, Distribution], root_key: str
 ) -> set[str]:
-    """Calculate the dependency tree for a package
+    """Calculate the dependency tree for a package.
 
     Return a collection of all of the package's dependencies.
     Uses a DFS traversal algorithm.
 
     ``installed_keys`` should be a {key: requirement} mapping, e.g.
     {'django': from_line('django==1.8')}
-    ``root_key`` should be the key to return the dependency tree for.
+    :param root_key: the key to return the dependency tree for
+    :type root_key: str
     """
     dependencies = set()
     queue: Deque[Distribution] = collections.deque()
@@ -127,7 +128,7 @@ def diff_key_from_ireq(ireq: InstallRequirement) -> str:
 
     For URL requirements, only provide a useful key if the url includes
     a hash, e.g. #sha1=..., in any of the supported hash algorithms.
-    Otherwise return ireq.link so the key will not match and the package will
+    Otherwise return ``ireq.link`` so the key will not match and the package will
     reinstall. Reinstall is necessary to ensure that packages will reinstall
     if the contents at the URL have changed but the version has not.
     """

piptools/utils.py

@@ -544,7 +544,7 @@ def override_defaults_from_config_file(
     file, returning the ``pathlib.Path`` of that config file if specified or
     discovered.
 
-    Return :py:data:`None` if no such file is found.
+    :returns: :py:data:`None` if no such file is found.
 
     ``pip-tools`` will use the first config file found, searching in this order:
     an explicitly given config file, a ``.pip-tools.toml``, a ``pyproject.toml``

tox.ini

@@ -53,8 +53,9 @@ skip_install = true
 
 [testenv:pip-compile-docs]
 description = compile requirements for the documentation
+changedir = {[testenv:build-docs]changedir}
 commands_pre =
-commands = python -m piptools compile --strip-extras --allow-unsafe --quiet docs/requirements.in {posargs}
+commands = python -m piptools compile --strip-extras --allow-unsafe --quiet requirements.in {posargs}
 
 [testenv:build-docs]
 description = build the documentation