Fix broken references in `docs/client_reference.rst` #5620

l1storez · 2021-04-15T22:46:48Z

What do these changes do?

This change corrects multiple unrendered intersphinx class reference in the client_reference.rst document.

Are there changes in behavior for the user?

NO

Related issue number

#5518

Checklist

I think the code is well written
Unit tests for the changes exist
Documentation reflects the changes
If you provide code modification, please add yourself to CONTRIBUTORS.txt
- The format is <Name> <Surname>.
- Please keep alphabetical order, the file is sorted by names.
Add a new news fragment into the CHANGES folder
- name it <issue_id>.<type> for example (588.bugfix)
- if you don't have an issue_id change it to the pr id after creating the pr
- ensure type is one of the following:
  - .feature: Signifying a new feature.
  - .bugfix: Signifying a bug fix.
  - .doc: Signifying a documentation improvement.
  - .removal: Signifying a deprecation or removal of public API.
  - .misc: A ticket has been closed, but it is not of interest to users.
- Make sure to use full sentences with correct case and punctuation, for example: "Fix issue with non-ascii contents in doctest text files."

l1storez · 2021-04-15T22:47:05Z

There are some fixes of "warnings". When I finalize PR, I will change commit messages. PR shows my progress
Looking for:
home/alexe/aiohttp/docs/client_reference.rst:779: WARNING: py:class reference target not found: callable
/home/alexe/aiohttp/docs/client_reference.rst:: WARNING: py:class reference target not found: abc.Mapping
/home/alexe/aiohttp/docs/client_reference.rst:516: WARNING: py:meth reference target not found: aiohttp.ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:534: WARNING: py:meth reference target not found: aiohttp.ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:541: WARNING: py:meth reference target not found: aiohttp.ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:554: WARNING: py:meth reference target not found: aiohttp.ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:561: WARNING: py:meth reference target not found: aiohttp.ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:574: WARNING: py:meth reference target not found: aiohttp.ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:589: WARNING: py:meth reference target not found: aiohttp.ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:607: WARNING: py:meth reference target not found: aiohttp.ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:626: WARNING: py:meth reference target not found: aiohttp.ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:632: WARNING: py:meth reference target not found: aiohttp.ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:: WARNING: py:class reference target not found: aiohttp.protocol.HttpVersion
/home/alexe/aiohttp/docs/client_reference.rst:991: WARNING: py:class reference target not found: aiohttp.ClientRequest
/home/alexe/aiohttp/docs/client_reference.rst:1137: WARNING: py:class reference target not found: aiohttp.abc.AbstractResolver
/home/alexe/aiohttp/docs/client_reference.rst:1216: WARNING: py:meth reference target not found: ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:1232: WARNING: py:class reference target not found: HttpVersion
/home/alexe/aiohttp/docs/client_reference.rst:1441: WARNING: py:class reference target not found: callable
/home/alexe/aiohttp/docs/client_reference.rst:1444: WARNING: py:class reference target not found: ClientRequest
/home/alexe/aiohttp/docs/client_reference.rst:1467: WARNING: py:func reference target not found: aiohttp.ws_connect
/home/alexe/aiohttp/docs/client_reference.rst:1483: WARNING: py:meth reference target not found: start
/home/alexe/aiohttp/docs/client_reference.rst:1580: WARNING: py:class reference target not found: callable
/home/alexe/aiohttp/docs/client_reference.rst:1641: WARNING: py:class reference target not found: callable
/home/alexe/aiohttp/docs/client_reference.rst:1713: WARNING: py:class reference target not found: ClientRequest
/home/alexe/aiohttp/docs/client_reference.rst:1747: WARNING: py:meth reference target not found: ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:1920: WARNING: py:class reference target not found: Payload
/home/alexe/aiohttp/docs/client_reference.rst:2105: WARNING: py:meth reference target not found: aiohttp.ClientSession.request
/home/alexe/aiohttp/docs/client_reference.rst:2166: WARNING: py:exc reference target not found: aiohttp.ServerDisconnectionError
/home/alexe/aiohttp/docs/client_reference.rst:2195: WARNING: py:exc reference target not found: ClientHttpProxyError

webknjaz · 2021-04-15T22:49:44Z

PR shows my progress

I'm marking this as a draft then.

l1storez · 2021-04-15T22:52:24Z

have troubles with callable and abc.Mapping they are not in the designated place

webknjaz · 2021-04-15T22:57:11Z

docs/client_reference.rst


   :param aiohttp.BasicAuth auth: an object that represents HTTP Basic
                                  Authorization (optional)

   :param version: supported HTTP version, ``HTTP 1.1`` by default.

-   :param cookie_jar: Cookie Jar, :class:`AbstractCookieJar` instance.
+   :param cookie_jar: Cookie Jar, :class:`aiohttp.abc.aiohttp.abc.AbstractCookieJar` instance.


This prefix is wrong as discussed in another PR.

I have warning with aiohttp.abc.AbstractCookieJar and AbstractCookieJar. with a double prefix I don't have a warning. If you insist, I'll leave it as you want

You need to fix this warning by removing the prefix from the respective .. class:: definition. It's only duplicated because it's both in the class definition and .. currentmodule:: at the top of the document — they are merged.

I try it later

webknjaz · 2021-04-15T22:57:34Z

have troubles with callable and abc.Mapping they are not in the designated place

What do you mean?

l1storez · 2021-04-16T07:59:23Z

I did not find callable in 779, 1441, 1580, 1641. mapping has no string binding

webknjaz · 2021-04-16T09:10:25Z

Point mapping at https://docs.python.org/3/glossary.html#term-mapping and callable to https://docs.python.org/3/reference/datamodel.html#callable-types.

l1storez · 2021-04-16T09:12:21Z

you don't understand, I did not find it in client_reference.rst Like here

https://github.com/aio-libs/aiohttp/blame/576862b1f2cb919c347851f40807caf7a9b80807/docs/client_reference.rst#L1431

webknjaz · 2021-04-16T09:19:09Z

By the way, this reference is wrong

      :param callable loads: :func:`callable` used for loading *JSON*

it should point to the term instead.

I don't see other places you're talking about. Maybe you forgot to update the list of warnings...

l1storez · 2021-04-16T09:21:39Z

#5620 (comment) actual version of warnings. Other places have the same situation

l1storez · 2021-04-16T09:27:41Z

https://github.com/aio-libs/aiohttp/blame/576862b1f2cb919c347851f40807caf7a9b80807/docs/client_reference.rst#L1565
https://github.com/aio-libs/aiohttp/blame/576862b1f2cb919c347851f40807caf7a9b80807/docs/client_reference.rst#L1641

webknjaz · 2021-04-16T09:27:44Z

Just fix the others then.

l1storez · 2021-04-16T09:28:50Z

good

l1storez · 2021-05-12T23:33:01Z

fix aiohttp.abc prefix in accordance with #5610

webknjaz · 2021-05-13T12:32:13Z

docs/client_reference.rst


   :param aiohttp.BasicAuth auth: an object that represents HTTP Basic
                                  Authorization (optional)

   :param version: supported HTTP version, ``HTTP 1.1`` by default.

-   :param cookie_jar: Cookie Jar, :class:`AbstractCookieJar` instance.
+   :param cookie_jar: Cookie Jar, :class:`aiohttp.abc.AbstractCookieJar` instance.


Let's maybe prefix this with a tilde?

Suggested change

:param cookie_jar: Cookie Jar, :class:`aiohttp.abc.AbstractCookieJar` instance.

:param cookie_jar: Cookie Jar, :class:`~aiohttp.abc.AbstractCookieJar` instance.

maybe, original without tilde

The original was rendered as a class name w/o a prefix

webknjaz · 2021-05-13T15:11:05Z

docs/client_reference.rst

@@ -2163,7 +2163,7 @@ Connection errors

   Server disconnected.

-   Derived from :exc:`ServerDisconnectionError`
+   Derived from :exc:`aiohttp.ServerDisconnectionError`


Suggested change

Derived from :exc:`aiohttp.ServerDisconnectionError`

Derived from :exc:`~aiohttp.ServerDisconnectionError`

l1storez · 2021-05-17T21:34:39Z

Remaining warnings:

/docs/client_reference.rst:779: WARNING: py:class reference target not found: callable
/docs/client_reference.rst:1137: WARNING: py:class reference target not found: aiohttp.abc.AbstractResolver
/docs/client_reference.rst:1467: WARNING: py:func reference target not found: aiohttp.ws_connect
/docs/client_reference.rst:1483: WARNING: py:meth reference target not found: start
/docs/client_reference.rst:2166: WARNING: py:exc reference target not found: aiohttp.ServerDisconnectionError
/docs/client_reference.rst:2195: WARNING: py:exc reference target not found: ClientHttpProxyError

l1storez · 2021-05-18T21:37:01Z

I think the remaining warnings go to ignore. (callable L779 not found)

webknjaz · 2021-05-19T05:17:02Z

I think the remaining warnings go to ignore. (callable L779 not found)

I think it's on line 111

l1storez · 2021-05-19T10:02:43Z

Okay, I try to fix it in l111, another warnings add to ignore list and make the PR ready

l1storez · 2021-05-19T20:48:41Z

Ready for review

webknjaz · 2021-05-19T20:50:40Z

There's a button for that

webknjaz · 2021-05-19T20:54:26Z

docs/client_reference.rst

@@ -1213,7 +1213,7 @@ Response object

 .. class:: ClientResponse

-   Client response returned by :meth:`ClientSession.request` and family.
+   Client response returned by :meth:`~aiohttp.ClientSession.request` and family.


Let's preserve the original rendering

Suggested change

Client response returned by :meth:`~aiohttp.ClientSession.request` and family.

Client response returned by :meth:`ClientSession.request() <aiohttp.ClientSession.request>` and family.

webknjaz · 2021-05-19T20:55:24Z

docs/client_reference.rst

@@ -1229,7 +1229,7 @@ Response object

   .. attribute:: version

-      Response's version, :class:`HttpVersion` instance.
+      Response's version, :class:`aiohttp.protocol.HttpVersion` instance.


Suggested change

Response's version, :class:`aiohttp.protocol.HttpVersion` instance.

Response's version, :class:`~aiohttp.protocol.HttpVersion` instance.

l1storez · 2021-05-19T20:56:35Z

It's just a comment

webknjaz · 2021-05-19T20:57:17Z

So it's not really ready for review because it's a draft, right?

l1storez · 2021-05-19T20:58:21Z

I forgot to push the button:)

webknjaz · 2021-05-19T21:03:07Z

docs/conf.py

+    ("py:meth", "aiohttp.ClientSession.request"),  # undocumented
+    ("py:class", "aiohttp.protocol.HttpVersion"),  # undocumented
+    ("py:class", "aiohttp.ClientRequest"),  # undocumented
+    ("py:class", "Payload"),  # undocumented


This should be a full importable string, not just a class name.

Do you mean full string "payload"?

package_name.module_name.ClassName, just like others.

Example:

Suggested change

("py:class", "Payload"), # undocumented

("py:class", "aiohttp.payload.Payload"), # undocumented

(

aiohttp/aiohttp/payload.py

Line 135 in e8b9dbc

class Payload(ABC):

)

webknjaz · 2021-05-19T21:05:20Z

docs/conf.py

+    ("py:class", "Payload"),  # undocumented
+    ("py:class", "aiohttp.abc.AbstractResolver"),  # undocumented
+    ("py:func", "aiohttp.ws_connect"),  # undocumented
+    ("py:meth", "start"),  # undocumented


Same here: it should have the full context.

aiohttp.start.start?

No, the thing this refers to should actually exist in the code.

Hmm, It will be quite hard for me, but I try

Find what it refers to in the context where it's used and that should be it

Opposite :meth:(close) refers to aiohttp.WSCloseCode.OK. Not enough context to define start for me

Alright, I did some research and it is indeed unobvious what this refers to. So let's leave it be for now.

webknjaz · 2021-05-19T21:05:43Z

docs/conf.py

+    ("py:func", "aiohttp.ws_connect"),  # undocumented
+    ("py:meth", "start"),  # undocumented
+    ("py:exc", "aiohttp.ServerDisconnectionError"),  # undocumented
+    ("py:exc", "ClientHttpProxyError"),  # undocumented


Same: it's not clear where it's defined.

aiohttp. ClientHttpProxyError?

Maybe, check via REPL

l1storez · 2021-05-19T21:11:05Z

Can you show an example, please?

docs/client_reference.rst

patchback · 2021-05-24T23:14:07Z

Backport to 3.8: 💚 backport PR created

✅ Backport PR branch: patchback/backports/3.8/ff9c117083d3d82d257dfad6242d7a5ac821f241/pr-5620

Backported as #5734

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.

Co-authored-by: Sviatoslav Sydorenko <[email protected]> (cherry picked from commit ff9c117)

Co-authored-by: Sviatoslav Sydorenko <[email protected]> (cherry picked from commit ff9c117) Co-authored-by: Olexiy Pohorely <[email protected]>

l1storez requested review from asvetlov and webknjaz as code owners April 15, 2021 22:46

webknjaz marked this pull request as draft April 15, 2021 22:49

This comment has been minimized.

Sign in to view

webknjaz reviewed Apr 15, 2021

View reviewed changes

l1storez force-pushed the 5518-fix-client-reference branch from 576862b to b1fdece Compare May 12, 2021 23:24

webknjaz reviewed May 13, 2021

View reviewed changes

l1storez force-pushed the 5518-fix-client-reference branch 2 times, most recently from 5b7f7e7 to 5cf3b9d Compare May 17, 2021 21:32

l1storez force-pushed the 5518-fix-client-reference branch from 5cf3b9d to 967f23d Compare May 19, 2021 20:41

webknjaz reviewed May 19, 2021

View reviewed changes

l1storez marked this pull request as ready for review May 19, 2021 20:57

webknjaz added the documentation Improvements or additions to documentation label May 19, 2021

webknjaz reviewed May 19, 2021

View reviewed changes

l1storez mentioned this pull request May 19, 2021

Fix missing references in docs #5518

Closed

l1storez force-pushed the 5518-fix-client-reference branch from 967f23d to 098830a Compare May 24, 2021 21:18

l1storez added 2 commits May 25, 2021 00:19

Fix broken references

f88254b

Add 9 warnings to ignore

fd2aa05

l1storez force-pushed the 5518-fix-client-reference branch from 098830a to fd2aa05 Compare May 24, 2021 21:20

webknjaz reviewed May 24, 2021

View reviewed changes

docs/client_reference.rst Outdated Show resolved Hide resolved

webknjaz added backport-3.8 bot:chronographer:skip This PR does not need to include a change note labels May 24, 2021

Render exc name short

ad0dbdc

webknjaz reviewed May 24, 2021

View reviewed changes

docs/client_reference.rst Outdated Show resolved Hide resolved

Restyle client session request ref

329e711

webknjaz enabled auto-merge (squash) May 24, 2021 23:04

webknjaz merged commit ff9c117 into aio-libs:master May 24, 2021

patchback bot pushed a commit that referenced this pull request May 24, 2021

Fix broken references in docs/client_reference.rst (#5620)

25442f8

Co-authored-by: Sviatoslav Sydorenko <[email protected]> (cherry picked from commit ff9c117)

patchback bot mentioned this pull request May 24, 2021

[PR #5620/ff9c1170 backport][3.8] Fix broken references in docs/client_reference.rst #5734

Merged

5 tasks

webknjaz pushed a commit that referenced this pull request May 25, 2021

Fix broken references in docs/client_reference.rst (#5620) (#5734)

2e25d38

Co-authored-by: Sviatoslav Sydorenko <[email protected]> (cherry picked from commit ff9c117) Co-authored-by: Olexiy Pohorely <[email protected]>

	:param cookie_jar: Cookie Jar, :class:`aiohttp.abc.AbstractCookieJar` instance.
	:param cookie_jar: Cookie Jar, :class:`~aiohttp.abc.AbstractCookieJar` instance.

	Derived from :exc:`aiohttp.ServerDisconnectionError`
	Derived from :exc:`~aiohttp.ServerDisconnectionError`

	Client response returned by :meth:`~aiohttp.ClientSession.request` and family.
	Client response returned by :meth:`ClientSession.request() <aiohttp.ClientSession.request>` and family.

	Response's version, :class:`aiohttp.protocol.HttpVersion` instance.
	Response's version, :class:`~aiohttp.protocol.HttpVersion` instance.

	("py:class", "Payload"), # undocumented
	("py:class", "aiohttp.payload.Payload"), # undocumented

Fix broken references in docs/client_reference.rst #5620

Fix broken references in docs/client_reference.rst #5620

Conversation

l1storez commented Apr 15, 2021

What do these changes do?

Are there changes in behavior for the user?

Related issue number

Checklist

l1storez commented Apr 15, 2021 • edited Loading

webknjaz commented Apr 15, 2021

This comment has been minimized.

l1storez commented Apr 15, 2021

Choose a reason for hiding this comment

l1storez Apr 16, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webknjaz commented Apr 15, 2021

l1storez commented Apr 16, 2021

webknjaz commented Apr 16, 2021

l1storez commented Apr 16, 2021 • edited Loading

webknjaz commented Apr 16, 2021 • edited Loading

l1storez commented Apr 16, 2021

l1storez commented Apr 16, 2021 • edited Loading

webknjaz commented Apr 16, 2021

l1storez commented Apr 16, 2021

l1storez commented May 12, 2021

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

l1storez commented May 17, 2021

l1storez commented May 18, 2021

webknjaz commented May 19, 2021

l1storez commented May 19, 2021

l1storez commented May 19, 2021

webknjaz commented May 19, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

l1storez commented May 19, 2021

webknjaz commented May 19, 2021

l1storez commented May 19, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webknjaz May 19, 2021 • edited Loading

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

l1storez commented May 19, 2021

patchback bot commented May 24, 2021 • edited Loading

Backport to 3.8: 💚 backport PR created

Fix broken references in `docs/client_reference.rst` #5620

Fix broken references in `docs/client_reference.rst` #5620

l1storez commented Apr 15, 2021 •

edited

Loading

l1storez Apr 16, 2021 •

edited

Loading

l1storez commented Apr 16, 2021 •

edited

Loading

webknjaz commented Apr 16, 2021 •

edited

Loading

l1storez commented Apr 16, 2021 •

edited

Loading

webknjaz May 19, 2021 •

edited

Loading

patchback bot commented May 24, 2021 •

edited

Loading