Brighten up docstrings

Also remove unrelated `tox.ini` change.

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>

docs/conf.py

@@ -39,6 +39,7 @@
 extensions = [
     "myst_parser",
     "sphinxcontrib.apidoc",
+    "sphinx.ext.intersphinx",
     "sphinxcontrib.programoutput",
 ]
 
@@ -52,6 +53,14 @@
 html_title = f"<nobr>{project}</nobr> documentation v{release}"
 
 
+# -- Options for intersphinx ----------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+
 # -------------------------------------------------------------------------
 default_role = "any"
 nitpicky = True
@@ -61,8 +70,6 @@
     r"^https://img.shields.io/matrix",
 ]
 
-suppress_warnings = ["myst.xref_missing"]
-
 nitpick_ignore_regex = [
     ("py:class", "pip.*"),
     ("py:class", "pathlib.*"),
@@ -75,14 +82,17 @@
     ("py:exc", "click.*"),
 ]
 
+suppress_warnings = ["myst.xref_missing"]
+
 # -- Apidoc options -------------------------------------------------------
+
 apidoc_excluded_paths: list[str] = []
 apidoc_extra_args = [
     "--implicit-namespaces",
     "--private",  # include “_private” modules
 ]
-apidoc_module_dir = "../piptools"
 apidoc_module_first = False
+apidoc_module_dir = "../piptools"
 apidoc_output_dir = "pkg"
 apidoc_separate_modules = True
 apidoc_toc_file = None

piptools/repositories/local.py

@@ -21,7 +21,7 @@ def ireq_satisfied_by_existing_pin(
     ireq: InstallRequirement, existing_pin: InstallationCandidate
 ) -> bool:
     """
-    Return True if the given InstallationRequirement is satisfied by the
+    Return :py:data:`True` if the given ``InstallRequirement`` is satisfied by the
     previously encountered version pin.
     """
     version = next(iter(existing_pin.req.specifier)).version

piptools/resolver.py

@@ -185,9 +185,7 @@ def _filter_out_unsafe_constraints(
 
 class LegacyResolver(BaseResolver):
     """
-    Resolve a given set of constraints (a collection of
-    InstallRequirement objects) by consulting the given Repository and the
-    DependencyCache.
+    Wrapper for the (deprecated) legacy dependency resolver.
     """
 
     def __init__(
@@ -201,6 +199,10 @@ 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.
+        """
         self.our_constraints = set(constraints)
         self.their_constraints: set[InstallRequirement] = set()
         self.repository = repository
@@ -423,7 +425,7 @@ def _iter_dependencies(
         self, ireq: InstallRequirement
     ) -> Iterator[InstallRequirement]:
         """
-        Collect all secondary dependencies for an ireq.
+        Emit all secondary dependencies for an ireq.
 
         Given a pinned, url, or editable InstallRequirement, collects all the
         secondary dependencies for them, either by looking them up in a local
@@ -640,9 +642,9 @@ def _do_resolve(
         compatible_existing_constraints: dict[str, InstallRequirement],
     ) -> bool:
         """
-        Actual resolution process.
+        Resolve dependencies based on resolvelib ``Resolver``.
 
-        Return True on successful resolution, otherwise remove problematic
+        Return :py:data:`True` on successful resolution, otherwise remove problematic
         requirements from existing constraints and return false.
         """
         try:

piptools/utils.py

@@ -113,9 +113,9 @@ def make_install_requirement(
 
 def is_url_requirement(ireq: InstallRequirement) -> bool:
     """
-    Return True if requirement was specified as a path or URL.
+    Return :py:data:`True` if requirement was specified as a path or URL.
 
-    ireq.original_link will have been set by InstallRequirement.__init__
+    ``ireq.original_link`` will have been set by ``InstallRequirement.__init__``
     """
     return bool(ireq.original_link)
 
@@ -526,7 +526,7 @@ def override_defaults_from_config_file(
     file, returning the ``pathlib.Path`` of that config file if specified or
     discovered.
 
-    Return ``None`` if no such file is found.
+    Return :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

@@ -52,9 +52,8 @@ 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 requirements.in {posargs}
+commands = python -m piptools compile --strip-extras --allow-unsafe --quiet docs/requirements.in {posargs}
 
 [testenv:build-docs]
 description = build the documentation