Sphinx autodoc - Trim module name option

[Han Lazarus]

Hi there, 

I have tried using sphinx autodoc with Django projects. 

Because of how users need to add settings / structure the path for the Django project to be imported correctly, the directory to the path that is inserted is just above all the project code. 

 

Then all generated documentation includes a redundant project name :( 

I am interested in a setting to trim off the left hand project names from autodoc generated documentation. 

I think this also might be useful for nested packages, where you could just use a section heading to specify the package. 

I realize this might break other functionality though and want to ask what (indexing?). 

It could be a package on top of autodoc a package that looks at each node and modifies the module name?

It could be something like this near here:

 class Options(dict):

     """A dict/attribute hybrid that returns None on nonexisting keys."""

+

     def __getattr__(self, name: str) -> Any:

         try:

             return self[name.replace('_', '-')]

@@ -427,7 +428,15 @@ class Documenter:

         if self.objpath:

             # Be explicit about the module, this is necessary since .. class::

             # etc. don't support a prepended module name

-            self.add_line('   :module: %s' % self.modname, sourcename)

+            modname = self.get_display_modname()

+            self.add_line('   :module: %s' % modname, sourcename)

+

+    def get_display_modname(self) -> str:

+        if self.options.strip_name:

+            remove = name_to_remove_from_options

+            return self.modname.strip(remove)

+        else:

+            return self.modname

I suspect the additional package is safer but I started out by trying to understand where the module name is getting created in autodoc, and haven't figured out how to access the module name from nodes yet. Pointers welcome. 

If this sounds like it will be feasible / welcome I will try to work on it.

Thanks

[Komiya Takeshi]

Hi,

Good challenge. It seems your patch is good enough.

>I suspect the additional package is safer but I started out by trying to understand where the module name is getting created in autodoc, and haven't figured out how to access the module name from nodes yet. Pointers welcome.

The `desc_signature` node is used to represent "object description".
And python objects also use it. You can see the structure of the node
and its children at `sphinx/domain/python.py` (see
PyObject.handle_signature() method).

I hope test cases on `tests/test_domain_py.py` also helps you. There
are many examples of desc_signature node.

Thanks,
Takeshi KOMIYA


2020年7月1日(水) 17:33 Han Lazarus <han.l...@gmail.com>:

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/fb8ed348-6b0b-4c49-8083-b3785a35ab3eo%40googlegroups.com.

[Han Lazarus]

Cool! I'll take a look at those test cases and try writing it into a PR!

To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/CAFmkQANzS-1i2WeYGp1qiYkPW4ESQoLr0TArqSg8vKFxk5coVw%40mail.gmail.com.

[Daniel Scott]