add support for nested accessors in documenter

[fraserdominicdavid]

Move AccessorDocumenter after AccessorLevelDocumenter and inherit the latter for the modified resolve_name() method which adds support for nested accessors.

This should fix import failure warnings for nested accessors documented using the autoaccessor directive which I think is the proper directive for documenting non-callable nested accessors.

[keewis]

as a heads-up, it has been a while since I understood what exactly the purpose of the class hierarchy is, so reviewing might take a while. To help with that, could you post a minimal example of the accessor you're trying to document that would work with this fix? The accessor itself doesn't have to actually do anything.

[fraserdominicdavid]

Good day, apologies for the lack of examples.

There may be instances where a user would want to document the namespace of nested accessors to explain the general usage of the subaccessor or any other relevant information.

To demonstrate this, I would modify example.py and examples.rst from this repo as follows:

# example.py
...
class SubAccessor:
    """Relevant documentation about SubAccessor shall be placed here.
    
    For instance, providing a general description to the namespace."""
    def __init__(self, obj):
        self._obj = obj
...

# in examples.rst, add
...
A summary of nested accessors:

.. autosummary::
   :toctree: generated/
   :template: autosummary/accessor.rst

   Example.test2.sub

In the current version, autdoc will raise a warning stating that it failed to import test2.sub from module Example. This is because the accessor.rst template uses the autoaccessor directive thereby using the AccessorDocumenter class. However, this documenter has not inherited the modified resolve_name() method which adds support to nested accessors.

This PR makes it so that the documenter also inherits the modified resolve_name() method. This would allow autodoc to generate properly, however, I don't know why Example.test2.sub's autosummary description is generated as alias of SubAccessor when it should instead be Relevant documentation about SubAccessor shall be placed here..

In the end, this may just be a misuse of the autoaccessor directive from my end, so if this is not the intended use of the autoaccessor directive and the corresponding template, then please feel free to reject this PR.

[keewis]

apologies for dropping the ball here. It took me a while to fully understand the change, but I agree that it makes sense if we want to support nested accessors (which I'd say is pretty untypical in itself).

For my own sake, I'll also note how the accessor template is typically used: most if not all of the templates were taken from the pandas documentation (rendered version). Here's an example for the pages this creates here: Series.cat (though obviously they don't deal with nested accessors).

We might need to add this to the docs at some point (in a different PR, though).