Merge pull request #2060 from chrysle/add-api-docs

Add private API documentation

docs/conf.py

@@ -36,7 +36,14 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["myst_parser", "sphinxcontrib.programoutput"]
+extensions = [
+    # Stdlib extensions:
+    "sphinx.ext.intersphinx",
+    # Third-party extensions:
+    "myst_parser",
+    "sphinxcontrib.apidoc",
+    "sphinxcontrib.programoutput",
+]
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -48,6 +55,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
@@ -57,4 +72,30 @@
     r"^https://img.shields.io/matrix",
 ]
 
+nitpick_ignore_regex = [
+    ("py:class", "pip.*"),
+    ("py:class", "pathlib.*"),
+    ("py:class", "click.*"),
+    ("py:class", "build.*"),
+    ("py:class", "optparse.*"),
+    ("py:class", "_ImportLibDist"),
+    ("py:class", "PackageMetadata"),
+    ("py:class", "importlib.*"),
+    ("py:class", "IndexContent"),
+    ("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_first = False
+apidoc_module_dir = "../piptools"
+apidoc_output_dir = "pkg"
+apidoc_separate_modules = True
+apidoc_toc_file = None

docs/index.md

@@ -13,3 +13,10 @@ cli/index
 contributing
 changelog
 ```
+
+```{toctree}
+:hidden:
+:caption: Private API reference
+
+pkg/modules
+```

docs/pkg/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

docs/requirements.in

@@ -2,4 +2,5 @@ furo
 myst-parser
 setuptools-scm
 sphinx
+sphinxcontrib-apidoc
 sphinxcontrib-programoutput

docs/requirements.txt

@@ -2,7 +2,7 @@
 # This file is autogenerated by pip-compile with Python 3.11
 # by the following command:
 #
-#    pip-compile --allow-unsafe --strip-extras docs/requirements.in
+#    pip-compile --allow-unsafe --strip-extras requirements.in
 #
 alabaster==0.7.13
     # via sphinx
@@ -44,6 +44,8 @@ packaging==23.1
     # via
     #   setuptools-scm
     #   sphinx
+pbr==6.0.0
+    # via sphinxcontrib-apidoc
 pygments==2.16.1
     # via
     #   furo
@@ -64,6 +66,7 @@ sphinx==7.2.2
     #   furo
     #   myst-parser
     #   sphinx-basic-ng
+    #   sphinxcontrib-apidoc
     #   sphinxcontrib-applehelp
     #   sphinxcontrib-devhelp
     #   sphinxcontrib-htmlhelp
@@ -72,6 +75,8 @@ sphinx==7.2.2
     #   sphinxcontrib-serializinghtml
 sphinx-basic-ng==1.0.0b2
     # via furo
+sphinxcontrib-apidoc==0.5.0
+    # via -r requirements.in
 sphinxcontrib-applehelp==1.0.7
     # via sphinx
 sphinxcontrib-devhelp==1.0.5

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/cache.py

@@ -21,6 +21,8 @@
 
 def _implementation_name() -> str:
     """
+    Get Python implementation and version.
+
     Similar to PEP 425, however the minor version is separated from the major to
     differentiate "3.10" and "31.0".
     """
@@ -57,7 +59,8 @@ def read_cache_file(cache_file_path: str) -> CacheDict:
 
 class DependencyCache:
     """
-    Creates a new persistent dependency cache for the current Python version.
+    Create new persistent dependency cache for the current Python version.
+
     The cache file is written to the appropriate user cache dir for the
     current platform, i.e.
 
@@ -89,7 +92,9 @@ def cache(self) -> CacheDict:
 
     def as_cache_key(self, ireq: InstallRequirement) -> CacheKey:
         """
-        Given a requirement, return its cache key. This behavior is a little weird
+        Given a requirement, return its cache key.
+
+        This behavior is a little weird
         in order to allow backwards compatibility with cache files. For a requirement
         without extras, this will return, for example:
 
@@ -108,7 +113,7 @@ def as_cache_key(self, ireq: InstallRequirement) -> CacheKey:
         return name, f"{version}{extras_string}"
 
     def write_cache(self) -> None:
-        """Writes the cache to disk as JSON."""
+        """Write the cache to disk as JSON."""
         doc = {"__format__": 1, "dependencies": self._cache}
         with open(self._cache_file, "w", encoding="utf-8") as f:
             json.dump(doc, f, sort_keys=True)
@@ -135,7 +140,7 @@ def reverse_dependencies(
         self, ireqs: Iterable[InstallRequirement]
     ) -> dict[str, set[str]]:
         """
-        Returns a lookup table of reverse dependencies for all the given ireqs.
+        Return a lookup table of reverse dependencies for all the given ireqs.
 
         Since this is all static, it only works if the dependency cache
         contains the complete data, otherwise you end up with a partial view.
@@ -149,7 +154,7 @@ def _reverse_dependencies(
         self, cache_keys: Iterable[tuple[str, str]]
     ) -> dict[str, set[str]]:
         """
-        Returns a lookup table of reverse dependencies for all the given cache keys.
+        Return a lookup table of reverse dependencies for all the given cache keys.
 
         Example input:
 

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