Add private API documentation

jazzband / pip-tools

A set of tools to keep your pinned Python dependencies fresh.

https://pip-tools.rtfd.io

BSD 3-Clause "New" or "Revised" License

7.67k stars 608 forks source link

Add private API documentation #2060

Open chrysle opened 6 months ago

chrysle commented 6 months ago

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

[x] 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).

webknjaz commented 6 months ago

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

chrysle commented 6 months ago

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

chrysle commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

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 commented 6 months ago

~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.

chrysle commented 3 months ago

@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:

https://github.com/jazzband/pip-tools/blob/347fec59b418b6239e47dee8429e8401ac4330e6/piptools/_compat/pip_compat.py#L67

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

chrysle commented 3 months ago

@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 commented 3 months ago

@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.

chrysle commented 3 months ago

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 commented 1 month ago

@webknjaz?

webknjaz commented 1 month ago

Ping we in like a week for another review.