objects.inv miss root package reference

[buhtz]

I am not a Sphinx user but depend on extern docu (seaborn) generated via Sphinx. Their problem is that there objects.inv file do not contain a reference to the root package. I can not use the package name in my docstrings because of that because my doc system (PyDoctor) do not know the URL to the package.

How can Sphinx be tweaked to do this? See there conf.py and the related issue.

[picnixz]

I think the issue is not related to Sphinx but rather PyDoctor. AFAICT, you want in your docstrings to use something like

see :mod:`seaborn`

but it's not possible for some reason. If you were to use Sphinx, then you would need to specify the intersphinx_mapping in your configuration file and Sphinx would take of the references it can find. However, since you are using another tool, we cannot help you. I think you should have a look at https://pydoctor.readthedocs.io/en/latest/sphinx-integration.html.

[buhtz]

PyDoctor do use intersphinx the same way Sphinx does.
On commandline you simply use --intersphinx=URL with pydoctor. Works very well with matplotlib, python itself and several other packages providing a objects.inv.

Anyway my question is not about my package but about seaborn. Seaborn does use Sphinx. And that Sphinx do generate a objects.inv file. And that file miss the reference to the root package that other packages (python, matplotlib, etc) do have.

The question breaks down to how Sphinx do generate that objects.inv and how can someone configure this generation process. I repeat myself: Some projects using Sphinx do have an ojbects.inv with a reference to root project but others don't. So where is the difference between this Sphinx configs?

[picnixz]

Then it is something you need to ask seaborn instead to fix (which apparently they did not consider to be on their side).

At least, I would like to know why it would work for other projects but not this specific one. Could you check the differences of the inventories between the working projects and theirs?

[buhtz]

For example numpy has this two lines

py:module
	numpy                                    reference/index.html#module-numpy

but seaborn do miss the py:module section.

Here in this Sphinx discussion section I don't ask for a fix. I do build on your expertise and try to learn how Sphinx interferes with the creation of that objects.inv file. Isn't it generated by Sphinx?

[picnixz]

Yes it is, but it depends on the structure of the project being documented. For instance, numpy does have a documentation for the module itself (see https://raw.githubusercontent.com/numpy/numpy/main/doc/source/reference/index.rst) using .. module:: numpy. However, if the other project does not have that then we will not know where the "main" module should point to.

[picnixz]

Note that, while Sphinx documents a Python project, it can also be used to document non-python projects. In particular, we cannot be really sure that "index.rst" points to the "root" package if there is none. You might have "index.rst" being the main entrypoint for different sub-projects as well so we cannot say that this or that project should point there (if there is no explicit .. module:: project).