I am working on a project that uses aiohttp. I'm setting up my documentation using sphinx on ReadTheDocs.

I have set up the interpshinx extension in conf.py and configured the mapping as following:

extensions = [
    "sphinx.ext.intersphinx",
]


intersphinx_mapping = {
    'python': ('/', None),
    'aiohttp': ('/', None),
}

The problem is, references to python work but references to aiohttp does not work and fails my build with the following warning:

WARNING: py:class reference target not found: aiohttp.client.ClientSession [ref.class]

The objects.inv file does exist at the set location.

I tried setting the fail_on_warning to false in .readthedocs.yml file:

fail_on_warning: false

and/or tried to set nitpick to ignore this with the following in conf.py:

nitpick_ignore = [
    ("py:class", "aiohttp.client.ClientSession"),
]

Both does build my documentation successfully, but references to aiohttp, like ClientSession, does not work\appear and thus it defeats the goal of referencing them.

How should i fix this?

Source code

Documentation link

UPDATE_1:

I have extracted the contents of objects.inv file and there is no aiohttp.client.ClientSession. only aiohttp.ClientSession exists.

I'm importing like this:

from aiohttp import ClientSession

I still don't know why sphinx is searching ClientSession in aiohttp.client but not the correct aiohttp as i have explicitly imported it that way.

Maybe it's caused by the way it's written? as ClientSession is in client.py inside aiohttp See here

UPDATE_2:

I tried a lot also to reference aiohttp but it didn't work I tried creating my own objects.inv file which had the correct mappings, but it failed with:

WARNING: failed to reach any of the inventories with the following issues:
unknown or unsupported inventory version: ValueError('invalid inventory header: ')

I tried manually creating and automatically with sphobjinv, but it didn't work. The original link also fails with:

WARNING: py:class reference target not found: aiohttp.client.ClientSession [ref.class]

I know the problem is with autodoc and intersphinx but I'm tired of trying to fix it. If I could just tell it to map aiohttp.client.ClientSession to aiohttp.ClientSession somehow... which i didn't find anything on it's documentation.

It took a lot of time from me, and I'm moving on. Also, it's not all the fault of autodoc and intersphinx, aiohttp.client.ClientSession actually DOES EXIST in the source code but it's not documented and

is an implementation detail and it shouldn't be referenced or imported that way.

UPDATE_3:

I tried replacing autodoc and autosummary with autoapi and everything is working fine.

This is a problem related to autodoc, however, as autoapi is doing the job i wanted, even better, i'm passed trying to figuring it out.

I am working on a project that uses aiohttp. I'm setting up my documentation using sphinx on ReadTheDocs..

I have set up the interpshinx extension in conf.py and configured the mapping as following:

extensions = [
    "sphinx.ext.intersphinx",
]


intersphinx_mapping = {
    'python': ('https://docs.python./3/', None),
    'aiohttp': ('https://docs.aiohttp./en/stable/', None),
}

The problem is, references to python work but references to aiohttp does not work and fails my build with the following warning:

WARNING: py:class reference target not found: aiohttp.client.ClientSession [ref.class]

The objects.inv file does exist at the set location.

I tried setting the fail_on_warning to false in .readthedocs.yml file:

fail_on_warning: false

and/or tried to set nitpick to ignore this with the following in conf.py:

nitpick_ignore = [
    ("py:class", "aiohttp.client.ClientSession"),
]

Both does build my documentation successfully, but references to aiohttp, like ClientSession, does not work\appear and thus it defeats the goal of referencing them.

How should i fix this?

Source code

Documentation link

UPDATE_1:

I have extracted the contents of objects.inv file and there is no aiohttp.client.ClientSession. only aiohttp.ClientSession exists.

I'm importing like this:

from aiohttp import ClientSession

I still don't know why sphinx is searching ClientSession in aiohttp.client but not the correct aiohttp as i have explicitly imported it that way.

Maybe it's caused by the way it's written? as ClientSession is in client.py inside aiohttp See here

UPDATE_2:

I tried a lot also to reference aiohttp but it didn't work I tried creating my own objects.inv file which had the correct mappings, but it failed with:

WARNING: failed to reach any of the inventories with the following issues:
unknown or unsupported inventory version: ValueError('invalid inventory header: ')

I tried manually creating and automatically with sphobjinv, but it didn't work. The original link also fails with:

WARNING: py:class reference target not found: aiohttp.client.ClientSession [ref.class]

I know the problem is with autodoc and intersphinx but I'm tired of trying to fix it. If I could just tell it to map aiohttp.client.ClientSession to aiohttp.ClientSession somehow... which i didn't find anything on it's documentation.

It took a lot of time from me, and I'm moving on. Also, it's not all the fault of autodoc and intersphinx, aiohttp.client.ClientSession actually DOES EXIST in the source code but it's not documented and

is an implementation detail and it shouldn't be referenced or imported that way.

UPDATE_3:

I tried replacing autodoc and autosummary with autoapi and everything is working fine.

This is a problem related to autodoc, however, as autoapi is doing the job i wanted, even better, i'm passed trying to figuring it out.

• python-sphinx
• aiohttp
• read-the-docs
• autodoc

1 Answer 1

Looks like we use https://aiohttp.readthedocs.io/en/stable ourselves: https://github/aio-libs/aiohttp-session/blob/4e14245e60140825979fcc7ec9d732f5aa16663f/docs/conf.py#L345

So, I'd try that.