Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Allow exceptions to autoclass_content #8107

Closed
SwampFalc opened this issue Aug 12, 2020 · 3 comments
Closed

Allow exceptions to autoclass_content #8107

SwampFalc opened this issue Aug 12, 2020 · 3 comments
Labels
extensions:autodoc type:enhancement enhance or introduce a new feature
Milestone

Comments

@SwampFalc
Copy link

The fact that the autoclass_content setting is global for the whole project has become a bit of an annoyance.

I have happily set it to "both" for all my projects, but now and then I really want the option to turn it off for some classes.

The concrete example I have in front of me right now is one where I subclass NamedTuple and write an alternate constructor:

class DatasetConfiguration(NamedTuple):
    """
    Configuration relevant to this dataset.
    """

    internal_mount: Path
    external_mount: Path
    dataexport_directory: Path
    dataexport_script: Path
    dataexport_log: Path

    @classmethod
    def from_config(cls, section):
        """
        Constructor.
        """
        kwargs = {key: Path(value) for key, value in section.items()}
        return cls(**kwargs)

I like the idea of using named tuples, because this is not dynamic data, but because I needed the second constructor (as well as some additional methods that are irrelevant here), I had to go the subclass route.

Of course, the second constructor is the only one that should be used in the scope of this code, so it's the only one that should get documented. But, since my autoclass_content is set to "both", Sphinx always pulls in the default NamedTuple.__init__ docstring...

Describe the solution you'd like
I feel that leaving autoclass_content as a global directive with no way to give exceptions, is an approach that lacks flexibility, leading to situations such as this.

I feel that the most sensible solution, in line with existing code, would be to have a :content: option for autoclass directives, with the global autoclass_content being a default for this value (and possibly simply incorporated into autodoc_default_options).

For example:

autodoc_default_options = {
    "content": "both",
}
.. autoclass:: DatasetConfiguration
    :content: class

(If this sounds interesting but none of the core developpers has the time to work on it, I could try my hand at it, I'd just need some pointers on where to start.)

@SwampFalc SwampFalc added the type:enhancement enhance or introduce a new feature label Aug 12, 2020
@tk0miya tk0miya added this to the 3.3.0 milestone Aug 12, 2020
@tk0miya
Copy link
Member

tk0miya commented Aug 12, 2020

+1: Reasonable. I prefer your idea. But I feel :content: does not describe its behavior or feature. So we have to discuss a good naming for the option.

@tk0miya tk0miya modified the milestones: 3.3.0, 3.4.0 Oct 4, 2020
@tk0miya tk0miya modified the milestones: 3.4.0, 3.5.0 Dec 19, 2020
@tk0miya tk0miya modified the milestones: 3.5.0, 4.0.0 Feb 14, 2021
@shimizukawa
Copy link
Member

I think the config tells the class where to get its documentation from.
So, how about the following name?

"class-doc-from": "class"
"class-doc-from": "both"
"class-doc-from": "init"

For example, it would look like this

autodoc_default_options = {
    "class-doc-from": "both",
}

and

.. autoclass:: DatasetConfiguration
  :class-doc-from: class

@tk0miya
Copy link
Member

tk0miya commented Mar 27, 2021

@shimizukawa Thank you for your comment.

+0 for your idea.

  • The "class" prefix of the "class-doc-from" option is a bit redundant for the autoclass directive.
  • But it's worthy (explicit) if autodoc_default_options support it.
  • I think "class-doc" is a natural name for all people.
  • The "from" suffix is okay to me.

@tk0miya tk0miya modified the milestones: 4.0.0, 4.1.0 Apr 11, 2021
@tk0miya tk0miya closed this as completed in d8a9f24 May 2, 2021
tk0miya added a commit that referenced this issue May 2, 2021
Close #8107: autodoc: Add class-doc-from option to autoclass directive
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 11, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
extensions:autodoc type:enhancement enhance or introduce a new feature
Projects
None yet
Development

No branches or pull requests

3 participants