pdoc3 / pdoc

:snake: :arrow_right: :scroll: Auto-generate API documentation for Python projects
https://pdoc3.github.io/pdoc/
GNU Affero General Public License v3.0
1.11k stars 143 forks source link

Wrong search hyperlinks to page sections for inherited classes #416

Open josip-milic opened 1 year ago

josip-milic commented 1 year ago

Hello, I'm using pdoc3 with lunr_search, it helps me a lot and produces very nice documentation without much effort, many thanks to the developers. I just have one problem with it. Search results show found documentation part for both the original class and the classes that inherit it. This is fine and all of them actually link to the same part in the documentation for the original class, but the section parts in the links (the #<section name> parts) actually contain the names of the child classes instead of the parent class that actually contains the documentation which results in not being able to jump to the correct section of the page when clicking on the link (in short, each result with the child class leads to the right page, but it's unable to jump to the right part of it).

Here is a demonstration:

Structure:

module_example
- __init__.py
- class1.py
- class2.py

Content of 'class1.py'

class Class1:
    def __init__(self, a):
        self.a = a

    def get_a(self):
        """This method returns value of `a`

        Returns: value of `a`

        """
        return self.a

Content of 'class2.py'

from module_example.class1 import Class1

class Class2(Class1):
    pass

Creation of html pages:

pdoc3 --html module_example -c lunr_search={} -o ./docs

Opening 'http://localhost:63342/project/docs/module_example/' shows the generated pages for both classes. When searching for 'get_a', it shows two results

module_example.class1.Class1.get_a() http://localhost:63342/project/docs/module_example/class1.html#module_example.class1.Class1.get_a module_example.class2.Class2.get_a() http://localhost:63342/project/docs/module_example/class1.html#module_example.class2.Class2.get_a

The first link is fine and it leads to the correct section of the page. The second link leads to a non-existing section of the page. The generated link should be the same as the first one.

In this case, the first link leads to the parent class which is fine, but when having a larger project, the parent class is not necessarily at the top of the search results. Also, in this case, the searched method is clearly visible, but if the class has many methods, it requires one additional awkward step of searching again on the page for the method.

If there is no easy fix for this, is there an existing option that would mitigate this, such as showing only the result for the parent class?

kernc commented 1 year ago

The link is constructed here: https://github.com/pdoc3/pdoc/blob/80af5d40d3ca39e2701c44941c1003ae6a280799/pdoc/templates/search.mako#L104 dobj.url is assigned here from dobj.module: https://github.com/pdoc3/pdoc/blob/80af5d40d3ca39e2701c44941c1003ae6a280799/pdoc/cli.py#L391-L414 which points to the parent module for members that aren't overridden.

I'm not sure what is best to do here. Why not just skip those members from search?