Trouble using intersphinx to link to my project's documentation

[CalMacCQ]

The intersphinx extension seems like a really useful tool to link between projects.

I have a python project and am trying to link to link to the documentation from the user manual. Both the API docs for my project and the user manual are built using sphinx (in separate builds).

I am having trouble getting interpshinx to generate links from the manual to various classes and fucntions in the API docs.

My project has a python class called Backend. In the manual I have the refernece

:py:class:`Backend`

I was hoping that when I build the manual that the link to the API docs is generated. Unfortunately the link is not generated.

My conf.py file for the manual contains the following lines

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

and

pytketdoc_base = "https://tket.quantinuum.com/api-docs/"

intersphinx_mapping = {
    "python": ("https://docs.python.org/3/", None),
    "pytket": (pytketdoc_base, None),
}

In my attempts to debug this issue I first tried looking at the objects.inv generated by my sphinx build

python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv

As expected, I see a lot of python references in the output.

If I add the following reference in the manual source...

:py:class:`list`

This links to the python 3 docs without issue.

However if I try the same thing with my project (EDIT: typo here - see comment below)

 python -m sphinx.ext.intersphinx https://tket.quantinuum.com/api-docs/objects/inv

I get this error message which I am not sure how to resolve.

Unknown error: HTTPError('intersphinx inventory %r not fetchable due to %s: %s', 'https://tket.quantinuum.com/api-docs/objects/inv', <class 'requests.exceptions.HTTPError'>, '404 Client Error: Not Found for url: https://tket.quantinuum.com/api-docs/objects/inv')

It seems there is an issue with the objects.inv file for the pytket project. Seems I have not done something correctly.

In case it is needed here is the link for the conf.py file for the pytket project

Any pointers would be greatly appreaciated. Thanks in advance.

[CalMacCQ]

There was an annoying typo in one of the commands above

the command should be

python -m sphinx.ext.intersphinx https://tket.quantinuum.com/api-docs/objects.inv

Note .inv rather than /inv.

The inventory for my package now shows up as output in the terminal however the links to the API docs are still not generated in the built html as I would expect.

Also running in nitpicky mode with

sphinx-build -n -b html . build

Now gives a bunch of warnings like

py:class reference target not found: Backend

[CalMacCQ]

Aha! Now resolved.

Seems the correct syntax to use in the manual source files is

py:class:`~pytket.backends.Backend`

or equivalently

.. currentmodule:: pytket.backends
    
:py:class:`Backend`

Writing this out actually made it easier to find the solution.