How to break down (debug) " Cannot find link target for XYZ" errors? about pydoctor

[tristanlatr]

Also note that I'm working on issue #609 and I hope to fix this limitation in a 24.x version.

But regarding this issue, if the packages are not listed in the inventory at all, there is nothing we can really do that wouldn't be hack.

[adiroiban]

Hi

Thanks for the report.

Can you provide a full example for this error?

The full error code and the source python code?

Maybe this is an issue with pydoctor failing to find the "canonical" name of an object

Regards

[buhtz]

# foobar.py
"""Docstring pointing to `seaborn`
and `docx`
or `python-docx`
"""

I do run pydoctor from an extra script that determine the package meta data itself. In the beginning you see the used command (via subprocess.run()). The branch is fix/analyboolean. Error is shown in this output near the end.

$ ./hey_doc.py
INFO    -  Run pydoctor with arguments:
        --project-name=buhtzology (0.2.0.dev0)
        --project-version=0.2.0.dev0
        --project-url=https://codeberg.org/buhtz/buhtzology
        --html-viewsource-base=https://codeberg.org/buhtz/buhtzology/src/branch/fix/analyboolean

        --docformat=google
        --make-html
        --process-types
        --warnings-as-errors
        --project-base-dir=..
        --html-output=html
        --intersphinx=https://docs.python.org/3/objects.inv
        --intersphinx=https://pandas.pydata.org/docs/objects.inv
        --intersphinx=https://seaborn.pydata.org/objects.inv
        --intersphinx=https://numpy.org/doc/stable/objects.inv
        --intersphinx=https://matplotlib.org/stable/objects.inv
        --intersphinx=https://pillow.readthedocs.io/en/stable/objects.inv
        --intersphinx=https://openpyxl.readthedocs.io/en/stable/objects.inv
        --intersphinx=https://python-docx.readthedocs.io/en/stable/objects.inv
        --intersphinx=https://webcolors.readthedocs.io/en/stable/objects.inv
        /home/user/goodCloud/my.work/buhtzology/src/buhtzology
adding directory /home/user/goodCloud/my.work/buhtzology/src/buhtzology
2/10 modules processed, 0 warnings
moving 'buhtzology._buhtzology.generate_filepath' into 'buhtzology'
moving 'buhtzology._buhtzology.runtime_as_string' into 'buhtzology'
moving 'buhtzology._buhtzology.how_much_elements_per_piece' into 'buhtzology'
moving 'buhtzology._buhtzology.setup_logging' into 'buhtzology'
moving 'buhtzology._buhtzology.shorten_strings_but_unique' into 'buhtzology'
4/10 modules processed, 0 warnings
moving 'buhtzology._datacontainer.DataContainer' into 'buhtzology.bandas'
10/10 modules processed, 0 warnings
writing html to html using pydoctor.templatewriter.writer.TemplateWriter
starting ModuleIndexPage ...took 0.036934s
starting ClassIndexPage ...took 0.034875s
starting NameIndexPage ...took 0.135736s
starting UndocumentedSummaryPage ...took 0.022510s
starting AllDocuments ...took 2.990770s
starting lunr search index ...took 0.874862s
7/24 pages written
/home/user/goodCloud/my.work/buhtzology/src/buhtzology/foobar.py:1: Cannot find link target for "seaborn"
/home/user/goodCloud/my.work/buhtzology/src/buhtzology/foobar.py:2: Cannot find link target for "docx"
/home/user/goodCloud/my.work/buhtzology/src/buhtzology/foobar.py:3: Cannot find link target for "python-docx"
24/24 pages written
Generating objects inventory at html/objects.inv
ERROR   -  Something went wrong. Check the output.

[adiroiban]

I don't think that pyhon-docx is a valid intersphinx target

Can you try to reference docx.document.Document or seaborn.objects.Plot?

I did a quick look at the object inventory for docx and I was not able to find a link for the exact docx object.

I am not familiar with the Google docstring format and how intersphinx targets are defined.
... but that part looks ok.

[buhtz]

"""Docstring pointing to `seaborn`
and `docx`
or `python-docx`
  
Try `docx.document.Document`
or `seaborn.objects.Plot`
"""

I am surprised. The links are working well.

So the problem is that the package name is somehow not linked. I do get errors only for the first three lines.

[adiroiban]

Happy to here it works.

You can use a tool like https://github.com/bskinn/sphobjinv to inspect the content of the object.inv file.

On a quick look, the linked projects don't include a refernce for the "root" package.

Also, pydoctor will only work the object inventory links starting with :py:.
It will not work with arbitrary sphinx references like :std:doc:

:py:function:`seaborn.violinplot`
:py:function:`seaborn.xkcd_palette`
:std:label:`faq_seaborn_sucks`
:std:doc:`generated/seaborn.FacetGrid`
:std:doc:`generated/seaborn.FacetGrid.__init__`
:std:doc:`generated/seaborn.FacetGrid.add_legend`

In this case, pydoctor is expected to give this error.

I think that this can be closed as this is not an issue with pydoctor.

If you think there should be a link to the root package, please check with the maintainers of those projects to update their object.inv files to include those references.

Note that interphinx is designed for API linked ... so by default, Sphinx apidoc generated links only for functions, methods, classes ..etc

[buhtz]

Thanks. I understand now why my problem occur. And think the issue can be closed.

I don't understand all other details discussed at #609.

But could we somehow improve the error message to better guide users like me? I thought it was a bug because the URL was valid and it should work.

[buhtz]

I might not be able to describe the problem the right way. Seaborn do not see a problem and closed the issue.
And even the Sphinx folks them selfs are not able to explain where the problem could be. https://github.com/orgs/sphinx-doc/discussions/12027#discussioncomment-8653396

[buhtz]

I assume that pydoctor do look for entries like this in the objects.inv

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