0

I am running into the issue described in https://github.com/sphinx-doc/sphinx/issues/8664, in which I have a class with type-annotated members as well as Google-style Attributes: pydocs, e.g.:

class Foo(Bar):
      """Something something.

      Attributes:
           baz: A handy thing.
      """

      baz: str

When I run sphinx-apidoc over my project, I get:

docstring of my_project.Foo.baz:1:duplicate object description of my_project.Foo.baz, other instance in source/my_project, use :noindex: for one of them

I understand that this is essentially due to the automatic setting of :undoc-members: by sphinx-apidoc. That is a useful setting (since I don't always have all members documented), but in this case, it collides with my documented members. Barring an elegant solution in which I could specify how to resolve such collisions, I would be happy to just tell autodoc to turn off :undoc-members: for my class Foo.

Is there some way to do that, e.g. via an event that supports changing the options for specific members?

mzjn
  • 48,958
  • 13
  • 128
  • 248
J. Lerman
  • 83
  • 7
  • It's not sphinx-apidoc that produces the warning; it's the main Sphinx process (sphinx-build), with the autodoc extension. – mzjn Mar 24 '23 at 09:13
  • Is your goal to exclude documentation for the `Foo` class in the output? In that case you could use the `autodoc-skip-member` event. https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#event-autodoc-skip-member – mzjn Mar 24 '23 at 09:57
  • @mzjn, thanks for asking. No, I don't want to exclude `Foo` documentation altogether - rather, I want `:undoc-members:` to be disabled for that class only (and any other class/function/etc I specify), while the default applies to all other documentation. That way, my pydoc is used for `Foo` members, and it won't collide with documentation generated from my type-annotations. – J. Lerman Mar 24 '23 at 17:03
  • There is no sphinx-apidoc option that can be used as far as I can tell. sphinx-apidoc generates RST files with `automodule` directives, and there is no way to specify that specific classes should be treated differently. You would have to use `autoclass` for those classes. – mzjn Mar 24 '23 at 17:35

1 Answers1

0

I found a workaround for my problem - not a real solution but posting as an answer since it's adequate for my short-term needs and may be helpful to others too:

Since I am using the napoleon extension to generate API docs from Google-style docstrings, I found that I can set [napoleon_use_ivar][1] to True in the Sphinx conf.py to avoid the collision issue triggered by my example. Here is the relevant snippet from conf.py:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx_rtd_theme",
]
napoleon_google_docstring = True  # Enable parsing of Google-style pydocs.
napoleon_use_ivar = True  # to correctly handle Attributes header in class pydocs

The effect is to tell Napoleon to treat the Attributes: header as describing instance-variables. That effectively avoids the collision, though the resulting documentation does now list each attribute ("variable") twice (in different ways) - so not an ideal solution, but at least it avoids the (unsuppressible) warning.

J. Lerman
  • 83
  • 7