Bug description

When using autoclass (not autoconfigurable), traits with help strings are treated as undocumented. That means they are excluded from :members:, but included with :undoc-members:. When they are included with :undoc-members:, they are all represented with their class docstring instead of their help string, like:

Expected behaviour

members/undoc-members should recognize the help string of traitlets as being documented, and be included/excluded accordingly.

Actual behaviour

all traits are treated as undocumented members, help strings are not extracted, and all traits are represented as configurable, even when they are not.

How to reproduce

..  autoclass:: test_module.TestConfigurable
   :noindex:
   :members:
   # :undoc-members:

produces output like

    trait_noconfig = Bool(
        help="""trait_noconfig help text""",
    )

into

trait_noconfig c.SampleConfigurable.trait_noconfig = Bool(False)
    A boolean (True, False) trait.

Note:

• help string is wrong
• formatting is for a config trait, which is also wrong

More info

Issue prompted by #28 (comment)

This is a low priority issue, since most things should use autoconfigurable, which does this right. But good general autoclass support for HasTraits would be nice, if possible.

@willingc I noted that we need to cut a release of this project for jupyterhub/oauthenticator to be able to use Sphinx 4 without installing it via a git reference. That made me motivated to setup some common JupyterHub org automation with regards to releases etc in this repo. What do you think?

Goals

• Add release automation and a RELEASE.md file
  Practically, this would be a copy-paste from another repo that publishes to PyPI.
  Example automation: https://github.com/jupyterhub/oauthenticator/blob/master/.github/workflows/publish.yml
  Example RELEASE.md: https://github.com/jupyterhub/oauthenticator/blob/master/RELEASE.md
• Add badges to the README.md
  Example badges: https://github.com/jupyterhub/oauthenticator/blob/master/README.md
• Initialize a CHANGELOG.md file

Action points

• @willingc could you review the goals and action points?
• @willingc could you add jupyterhubbot and perhaps another human or two (consideratio) to the associated PyPI project (https://pypi.org/project/autodoc-traits/) ?
• I'll go ahead and work towards all the goals if found to be acceptable

Update

I missed that @minrk has opened #4 already! There are some steps to take with documentation to follow that up with.

It seems that the help strings for traits of type Dict, List, Instance are missing since ipython/traitlets#818 released with traitlets 5.10.0 in september, but they aren't missing for Bool, Integer, Unicode.

I've added a test to capture this in #54, but I don't have an understanding on what happened in ipython/traitlets#818 that caused this.

Related code

It would be nice to have some primitive tests for this project.

The sphinx.ext.autodoc provided directives support a inherited-members option, and acts as an opt-in option - defaulting to not including inherited members.

But I think we have implemented it backwards, so that we by default include inherited members, and when inherited-members is passed we don't include them.

A first step to address this issue could be to setup basic tests (#17), and/or investigate it further to verify how things work with and without the inherited-members directive option.

I understand it as autodoc_traits will influence sphinx.ext.autodoc, which in turn will emit rST, which makes the autodoc directives need to be parsed as rST and not MyST.

I think this is relevant to document clearly in autodoc_traits README file, and if possible, link to an issue upstream where we can track effort to resolve this in a sensible way.

So practically:

# this will work in a MyST parsed .md file
```{eval-rst}
.. automodule:: kubespawner.utils
```

# this won't work in a MyST parsed .md file
# it will emit rST directives like `.. py:module:: kubespawner.utils`
# and docstrings in raw format, which then also should be in rST
```{automodule} kubespawner.utils

```

So this example MyST markdown file:

# Utilities

```{automodule} kubespawner.utils

```

Will end up looking like this as rendered HTML:

Related

• executablebooks/team-compass#6

In this sphinx example on how to write an extension for sphinx.ext.autodoc, they register the sphinx.ext.autodoc extension in the extension itself like this:

def setup(app: Sphinx) -> None:
    app.setup_extension('sphinx.ext.autodoc')  # Require autodoc extension
    app.add_autodocumenter(IntEnumDocumenter)

Should we do the same in this extension? That would make someone able to just add autodoc_traits as a sphinx extensions in their sphinx conf.py file.

I've realized that the autoclass directive is not the same as autoconfigurable.

1. We should update the README.md for now to not mention autoclass, but autoconfigurable.
2. We should consider providing a can_document_member function also for the TraitsletsDocumenter class, and perhaps increase the priority or similar. That is whats done for the other class for Attributes.

Unsure, but more investigations are needed.

I think having a "How it works" section (example from jupyterhub-idle-culler) in the readme would be great. I'm currently debugging an issue where I look to determine if its an issue with autodoc_traits, sphinx.ext.autodoc, myst_parser, or something else. Not understanding how all the pieces work makes me unable to figure out what my problem is.

Current understanding of autodoc_traits

• autodoc_traits registeres two new "autodocumenter" classes that sphinx.ext.autodoc will honor using add_autodocumenter
  

  autodoc-traits/autodoc_traits/autodoc_traits.py

  Lines 60 to 62 in d618d9e

  	def setup(app):
  	app.add_autodocumenter(ConfigurableDocumenter)
  	app.add_autodocumenter(TraitDocumenter)

• autodoc_trait's autodocumenter classes include details like below, which helps the sphinx.ext.autodoc directives decide if and when the autodocumenter is relevent. The best documentation of these I've found are in this example
  

  autodoc-traits/autodoc_traits/autodoc_traits.py

  Lines 36 to 40 in d618d9e

  	class TraitDocumenter(AttributeDocumenter):
  	objtype = "trait"
  	directivetype = "attribute"
  	member_order = 1
  	priority = 100

• From here on, autodoc_traits work is done, and sphinx.ext.autodoc takes over using the added autodocumenter classes when suitable
• sphinx.ext.autodoc will generate .. py: directives with provided docstrings etc.

To summarize, autodoc_traits will register autodocumenter classes with sphinx.ext.autodoc, which in turn will scan source code and emit rST declarations of .. py: directives.

Request for review

I can document this in the README, but I'd love some input/review of this understanding. Review questions could be:

• is it accurate?
• does it capture how things work?
• is there other things to include or link out to?

When a class' traits are documented with autodoc_traits, all of the traits are presented. That is quite unexpected in my mind, but also quite useful as it could often be that you want to present all configurable options while not presenting all functions etc.

Maybe we should keep doing this, just wanted to have an issue open about it for visibility for now.

PyClassmember has been obsoleted as of Sphinx 4.0. I found this while trying to build docs for OAuthenticator.

Bug description

Hi, I hate to pester (and apologies if this isn't an appropriate place to put this request!), but please could you put a new release on PyPi, or create a new tag here on github? The version on PyPi doesn't work with sphinx v4, due to the removal of PyClassmember. There have been additional autodoc-traits fixes too (eg. regarding duplicate documentation of configurable properties), since the last PyPi release. I ask because I'd rather not have to either pin to a sphinx version < 4, and/or put the git+git:// ref in a docs/requirements.txt file.

Thanks, A