Add private API documentation #2060

chrysle · 2024-02-24T16:39:59Z

Closes #1999. Thanks for providing the example, @webknjaz!

Contributor checklist

Included tests for the changes.
PR title is short, clear, and ready to be included in the user-facing changelog.

Maintainer checklist

Verified one of these labels is present: backwards incompatible, feature, enhancement, deprecation, bug, dependency, docs or skip-changelog as they determine changelog listing.
Assign the PR to an existing or new milestone for the target version (following Semantic Versioning).

docs/conf.py

docs/requirements.txt

docs/requirements.in

webknjaz · 2024-02-25T03:21:32Z

piptools/resolver.py

@@ -161,7 +161,9 @@ def resolve(self, max_rounds: int) -> set[InstallRequirement]:
    def resolve_hashes(
        self, ireqs: set[InstallRequirement]
    ) -> dict[InstallRequirement, set[str]]:
-        """Find acceptable hashes for all of the given ``InstallRequirement``s."""
+        """
+        Find acceptable hashes for all of the given ``InstallRequirement``'s.


This change is incorrect. It's not 's but just a plural s. Just revert it.

I wouldn't have added that if Sphinx hadn't given me this strange error:

/home/user/repos/github/pip-tools/.tox/build-docs/lib/python3.9/site-packages/piptools/resolver.py:docstring of piptools.resolver.BaseResolver.resolve_hashes:1: WARNING: Inline literal start-string without end-string.

Either way, the grammar is broken. RST parser can be tricked into merging parts by adding an escaped whitespace:

Suggested change

Find acceptable hashes for all of the given ``InstallRequirement``'s.

Find acceptable hashes for all of the given ``InstallRequirement``\ s.

If that doesn't work, the only thing left is rephrasing. There are other hacks, I think, but they are rather complicated and not worth it.

webknjaz · 2024-02-25T03:24:41Z

piptools/sync.py

-    Calculate the dependency tree for the package `root_key` and return
-    a collection of all its dependencies.  Uses a DFS traversal algorithm.
+    Calculate the dependency tree for the package ``root_key`` and return
+    a collection of all its dependencies. Uses a DFS traversal algorithm.


Many people have a habit of placing two spaces in between sentences. It's an old typographic practice. I think it's also mentioned in some PEPs. Since we don't enforce one way or the other (and RST is fine with either, I think), I wouldn't attempt reformatting within this PR (maybe ever).

But talking about PEP 257-compliant docstrings, they should have exactly one title/summary sentence on a separated line. That's something that would be related.

webknjaz · 2024-02-25T03:25:38Z

I'd rename the PR title from "API" to "private API" for clarity.

webknjaz · 2024-02-25T03:26:20Z

tox.ini

 commands_pre =
-commands = python -m piptools compile --strip-extras --allow-unsafe --quiet docs/requirements.in {posargs}


I'd leave this out of this PR. It's not related to documenting things.

chrysle · 2024-02-25T14:29:38Z

I've pushed a commit following a valiant attempt to format pip-tools's docstrings properly.

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>

webknjaz · 2024-02-26T03:00:48Z

docs/conf.py

@@ -58,3 +62,27 @@
 ]

 suppress_warnings = ["myst.xref_missing"]
+
+nitpick_ignore_regex = [


Let's put this right under nitpicky above.

webknjaz · 2024-02-26T03:02:00Z

docs/conf.py

+apidoc_module_dir = "../piptools"
+apidoc_module_first = False


Sorting

Suggested change

apidoc_module_dir = "../piptools"

apidoc_module_first = False

apidoc_module_first = False

apidoc_module_dir = "../piptools"

webknjaz · 2024-02-26T03:05:49Z

piptools/resolver.py

@@ -182,6 +184,12 @@ def _filter_out_unsafe_constraints(


 class LegacyResolver(BaseResolver):
+    """
+    Resolve a given set of constraints (a collection of


It's a class, not a callable function. Classes represent static things/data. They don't do anything on their own. This is why, unlike functions/methods, their docstrings shouldn't start with a verb, because they don't perform actions, they just organize stuff. I usually recommend just stating what it is/represents in the docstring title line.

webknjaz · 2024-02-26T03:07:13Z

piptools/resolver.py

@@ -193,11 +201,6 @@ def __init__(
        allow_unsafe: bool = False,
        unsafe_packages: set[str] | None = None,
    ) -> None:
-        """
-        This class resolves a given set of constraints (a collection of


A docstring here may still be useful. It could describe what this initializer method does.

webknjaz · 2024-02-26T03:11:10Z

piptools/resolver.py

@@ -416,6 +423,8 @@ def _iter_dependencies(
        self, ireq: InstallRequirement
    ) -> Iterator[InstallRequirement]:
        """
+        Collect all secondary dependencies for an ireq.


I usually go for "emit" in generator functions' docstrings. I feel like this word represents better that it can produce/stream more data, than just a single return instruction does.

Suggested change

Collect all secondary dependencies for an ireq.

Emit all secondary dependencies for an ireq.

webknjaz · 2024-02-26T03:12:06Z

piptools/resolver.py

-        Return true on successful resolution, otherwise remove problematic
+        Actual resolution process.
+
+        Return True on successful resolution, otherwise remove problematic


Things like this are linkable

Suggested change

Return True on successful resolution, otherwise remove problematic

Return :py:data:`True` on successful resolution, otherwise remove problematic

webknjaz · 2024-02-26T03:12:57Z

piptools/resolver.py

@@ -629,7 +640,9 @@ def _do_resolve(
        compatible_existing_constraints: dict[str, InstallRequirement],
    ) -> bool:
        """
-        Return true on successful resolution, otherwise remove problematic
+        Actual resolution process.


This should still start with a verb. Although, this specific phrase seems like a comment rather than a docstring.

webknjaz · 2024-02-26T03:15:34Z

piptools/utils.py

    file, returning the ``pathlib.Path`` of that config file if specified or
    discovered.

-    ``None`` is returned if no such file is found.


The original phrase was fine since it's not the title line and is in the middle of the prose / details.

chrysle · 2024-02-26T09:27:46Z

Addressed your suggestions, thanks! I also moved the tox session change into another PR (#2061).

Things like this are linkable

I think the :py:data: role is only suited for module-level variables? At least Sphinx gives my a corresponding error.

webknjaz · 2024-02-27T05:09:39Z

I think the :py:data: role is only suited for module-level variables? At least Sphinx gives my a corresponding error.

The role is correct: https://webknjaz.github.io/intersphinx-untangled/docs.python.org/. The problem is that intersphinx isn't integrated (which I didn't realize), meaning that Sphinx can't look up any foreign objects from the CPython docs.

Also remove unrelated `tox.ini` change. Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>

chrysle · 2024-03-01T14:49:10Z

The problem is that intersphinx isn't integrated (which I didn't realize), meaning that Sphinx can't look up any foreign objects from the CPython docs.

I didn't think of that, too. Now done! ~~Strangely GH doesn't update this PR after my force-push to this branch?~~ Ah, looks like it works, now.

webknjaz · 2024-03-01T22:38:56Z

~~Strangely GH doesn't update this PR after my force-push to this branch?~~ Ah, looks like it works, now.

Sometimes, GitHub is drunk and messes up internal state due to its eventual consistency. It's happening around their outages, usually.

It's good it caught up with the changes. Sometimes, it doesn't and a PR may remain in a weird state forever. Such cases are only fixed with a new PR.

docs/conf.py

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>

for more information, see https://pre-commit.ci

webknjaz · 2024-03-02T08:48:02Z

piptools/resolver.py

-        This class resolves a given set of constraints (a collection of
-        InstallRequirement objects) by consulting the given Repository and the
-        DependencyCache.
+        Make sure the legacy resolver is enabled and no backtracking resolver


This new phrasing feels weird. That's not what the initializer seems to do...

I have no expertise in writing docstrings for __init__ functions. What would you expect it to contain? A listing of all the parameters?

That's not what the initializer seems to do...

Well, it does raise PipToolsError if the user didn't enable the legacy resolver, and removes an entry for the 2020 resolver from the enabled features?

I have no expertise in writing docstrings for __init__ functions. What would you expect it to contain? A listing of all the parameters?

Yes, listing :param:, :raises: and other entries is something that belongs here. The original docstring could partially augment the class level one.

As for the initializer docstring title, I usually go for Initialize ClassName. — this is what the initializer (any __init__()) does — it's called right after the constructor (__new__()) with a pre-created object and has to prepare it and turn into the usable state.

That's not what the initializer seems to do...

Well, it does raise PipToolsError if the user didn't enable the legacy resolver, and removes an entry for the 2020 resolver from the enabled features?

Yeah, but exceptions are side effects for signaling errors. While the main purpose of an initializer is to set up the instance, making it ready for the later use.

webknjaz · 2024-03-02T08:49:19Z

piptools/sync.py

-    """
-    Calculate the dependency tree for the package `root_key` and return
-    a collection of all its dependencies.  Uses a DFS traversal algorithm.
+    """Calculate the dependency tree for a package


Suggested change

"""Calculate the dependency tree for a package

"""Calculate the dependency tree for a package.

webknjaz · 2024-05-02T14:05:26Z

piptools/utils.py

    file, returning the ``pathlib.Path`` of that config file if specified or
    discovered.

-    ``None`` is returned if no such file is found.
+    Return :py:data:`None` if no such file is found.


It's possible to use the param list markup for this:

Suggested change

Return :py:data:`None` if no such file is found.

:returns: :py:data:`None` if no such file is found.

chrysle added docs Documentation related skip-changelog Avoid listing in changelog labels Feb 24, 2024

webknjaz reviewed Feb 25, 2024

View reviewed changes

docs/conf.py Outdated Show resolved Hide resolved

webknjaz reviewed Feb 25, 2024

View reviewed changes

docs/requirements.txt Show resolved Hide resolved

webknjaz reviewed Feb 25, 2024

View reviewed changes

docs/requirements.in Outdated Show resolved Hide resolved

webknjaz reviewed Feb 25, 2024

View reviewed changes

chrysle changed the title ~~Add API documentation~~ Add private API documentation Feb 25, 2024

chrysle force-pushed the add-api-docs branch from 663b618 to 7cd0ce2 Compare February 25, 2024 14:24

chrysle added 2 commits February 25, 2024 15:26

Add API documentation

13bd810

Format docstrings according to PEP 257

02d9041

chrysle force-pushed the add-api-docs branch from 7cd0ce2 to 65913a1 Compare February 25, 2024 14:26

Sort Sphinx extensions

cb783cc

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>

chrysle force-pushed the add-api-docs branch from 65913a1 to cb783cc Compare February 25, 2024 14:33

webknjaz reviewed Feb 26, 2024

View reviewed changes

Brighten up docstrings

34e9b20

Also remove unrelated `tox.ini` change. Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>

chrysle force-pushed the add-api-docs branch from 5823c44 to 34e9b20 Compare March 1, 2024 15:25

chrysle requested a review from webknjaz March 1, 2024 19:23

webknjaz reviewed Mar 1, 2024

View reviewed changes

docs/conf.py Outdated Show resolved Hide resolved

chrysle and others added 2 commits March 2, 2024 08:25

Sort Sphinx extensions corresponding to origin

78ecd0a

Co-authored-by: Sviatoslav Sydorenko (Святослав Сидоренко) <wk.cvs.github@sydorenko.org.ua>

[pre-commit.ci] auto fixes from pre-commit.com hooks

2421c64

for more information, see https://pre-commit.ci

webknjaz reviewed Mar 2, 2024

View reviewed changes

webknjaz reviewed May 2, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add private API documentation #2060

Add private API documentation #2060

chrysle commented Feb 24, 2024

webknjaz Feb 25, 2024 •

edited

chrysle Feb 25, 2024

webknjaz Feb 25, 2024

webknjaz Feb 25, 2024

webknjaz commented Feb 25, 2024

webknjaz Feb 25, 2024

chrysle commented Feb 25, 2024

webknjaz Feb 26, 2024

webknjaz Feb 26, 2024

webknjaz Feb 26, 2024

webknjaz Feb 26, 2024

webknjaz Feb 26, 2024

webknjaz Feb 26, 2024

webknjaz Feb 26, 2024

webknjaz Feb 26, 2024

chrysle commented Feb 26, 2024

webknjaz commented Feb 27, 2024

chrysle commented Mar 1, 2024 •

edited

webknjaz commented Mar 1, 2024

webknjaz Mar 2, 2024

chrysle Mar 2, 2024

webknjaz May 2, 2024

webknjaz Mar 2, 2024

webknjaz May 2, 2024

	Find acceptable hashes for all of the given ``InstallRequirement``'s.
	Find acceptable hashes for all of the given ``InstallRequirement``\ s.

		commands_pre =
		commands = python -m piptools compile --strip-extras --allow-unsafe --quiet docs/requirements.in {posargs}

		apidoc_module_dir = "../piptools"
		apidoc_module_first = False

	Collect all secondary dependencies for an ireq.
	Emit all secondary dependencies for an ireq.

	Return True on successful resolution, otherwise remove problematic
	Return :py:data:`True` on successful resolution, otherwise remove problematic

	"""Calculate the dependency tree for a package
	"""Calculate the dependency tree for a package.

	Return :py:data:`None` if no such file is found.
	:returns: :py:data:`None` if no such file is found.

Add private API documentation #2060

Are you sure you want to change the base?

Add private API documentation #2060

Conversation

chrysle commented Feb 24, 2024

Contributor checklist

Maintainer checklist

webknjaz Feb 25, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webknjaz commented Feb 25, 2024

Choose a reason for hiding this comment

chrysle commented Feb 25, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrysle commented Feb 26, 2024

webknjaz commented Feb 27, 2024

chrysle commented Mar 1, 2024 • edited

webknjaz commented Mar 1, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webknjaz Feb 25, 2024 •

edited

chrysle commented Mar 1, 2024 •

edited