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.

docs/conf.py

piptools/resolver.py

piptools/utils.py

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.

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

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.

piptools/sync.py

piptools/utils.py

chrysle · 2024-05-12T13:00:30Z

@webknjaz Addressed your comments. Unfortunately, the time-consumingly documented __init__ method of the LegacyResolver class doesn't show up in the built documentation. Do you think that could be related to sphinx-doc/sphinx#11181?

And, I was forced to add pip's IndexContent class to nitpick_ignore_regex, as Sphinx complained about a missing reference target for the same due to this inheritance:

pip-tools/piptools/_compat/pip_compat.py

Line 67 in 347fec5

class FileLink(Link): # type: ignore[misc]

I tried setting autodoc_inherit_docstrings to False in conf.py, but it hasn't helped.

chrysle · 2024-05-12T13:59:51Z

@webknjaz I really screwed up the rebasing. Now there are several redundant commits. Do you have any suggestion how to get rid of them? Please feel free to push to my branch.

webknjaz · 2024-05-13T01:05:05Z

@chrysle interactive rebase is your friend. And remember to rebase on top of upstream, not your fork. If you can't figure it out, let me know which commits you want to keep and I'll do it myself when I get to PyCon.

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

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

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

chrysle · 2024-05-13T07:08:44Z

Ah, finally I made it. It was a bit harder to do, as I had amended a merge commit... I ended up applying a patch. Could you review again?

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 2 times, most recently from 7cd0ce2 to 65913a1 Compare February 25, 2024 14:26

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

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

webknjaz reviewed Mar 2, 2024

View reviewed changes

webknjaz reviewed May 2, 2024

View reviewed changes

piptools/utils.py Outdated Show resolved Hide resolved

chrysle force-pushed the add-api-docs branch 3 times, most recently from ec56341 to 290ad20 Compare May 12, 2024 07:08

chrysle force-pushed the add-api-docs branch 2 times, most recently from 75ece2a to defad02 Compare May 12, 2024 13:30

chrysle force-pushed the add-api-docs branch from defad02 to 893f758 Compare May 12, 2024 13:53

chrysle and others added 6 commits May 13, 2024 09:04

Add API documentation

f99adda

Format docstrings according to PEP 257

647044f

Sort Sphinx extensions

322566f

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

Brighten up docstrings

2800397

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

Sort Sphinx extensions corresponding to origin

c248d3c

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

Use reST docstring formatting where appropriate

dbaaef1

chrysle force-pushed the add-api-docs branch from 7c04b8a to dbaaef1 Compare May 13, 2024 07:06

chrysle requested a review from webknjaz May 16, 2024 14:56

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

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

chrysle commented May 12, 2024

chrysle commented May 12, 2024 •

edited

webknjaz commented May 13, 2024

chrysle commented May 13, 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}

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

chrysle Feb 25, 2024

Choose a reason for hiding this comment

webknjaz Feb 25, 2024

Choose a reason for hiding this comment

webknjaz Feb 25, 2024

Choose a reason for hiding this comment

webknjaz commented Feb 25, 2024

webknjaz Feb 25, 2024

Choose a reason for hiding this comment

chrysle commented Feb 25, 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

Choose a reason for hiding this comment

chrysle Mar 2, 2024

Choose a reason for hiding this comment

webknjaz May 2, 2024

Choose a reason for hiding this comment

chrysle commented May 12, 2024

chrysle commented May 12, 2024 • edited

webknjaz commented May 13, 2024

chrysle commented May 13, 2024

webknjaz Feb 25, 2024 •

edited

chrysle commented Mar 1, 2024 •

edited

chrysle commented May 12, 2024 •

edited