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.

Sign up for GitHub

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

Jump to bottom

Local autodoc options override or extend autodoc_default_options. #8297

Merged
merged 12 commits into from Feb 4, 2021
Merged

Local autodoc options override or extend autodoc_default_options. #8297

merged 12 commits into from Feb 4, 2021

Conversation

pbudzyns
Copy link
Contributor

@pbudzyns pbudzyns commented Oct 6, 2020

Subject: local :exclude-members: extends global option instead of being replaced by it

Feature or Bugfix

  • Feature

Purpose

  • Currently it is impossible to exclude members of a single class when global exclude-members is defined. After change local exclude-members extends the list provided by global options.

@tk0miya tk0miya added extensions:autodoc type:enhancement enhance or introduce a new feature labels Jan 24, 2021
@tk0miya tk0miya added this to the 3.5.0 milestone Jan 24, 2021
tk0miya
tk0miya requested changes Jan 24, 2021
View reviewed changes
Copy link
Member

@tk0miya tk0miya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still debating it would be better to add a way "not" to extend the global option too. How about a hint notation "+"?

.. automodule::
   :exclude-members: +foo,bar,baz

sphinx/ext/autodoc/directive.py Outdated Show resolved Hide resolved
sphinx/ext/autodoc/directive.py Outdated Show resolved Hide resolved
@pbudzyns
Copy link
Contributor Author

pbudzyns commented Jan 25, 2021 •
edited

I'm still debating it would be better to add a way "not" to extend the global option too. How about a hint notation "+"?

.. automodule::
   :exclude-members: +foo,bar,baz

That is interesting suggestion, by "not" extending you mean to simply override it? Hint notation with "+" looks good to me. What about to make it "+/-" ?

@pbudzyns pbudzyns requested a review from tk0miya January 25, 2021 13:20
@tk0miya
Copy link
Member

tk0miya commented Jan 27, 2021

That is interesting suggestion, by "not" extending you mean to simply override it? Hint notation with "+" looks good to me. What about to make it "+/-" ?

Yes. My thought is

  • a plus sign like +foo means an enhancement; foo + autodoc_default_options. It works as you proposed at first.
  • Not prefixed; foo means an override; only foo is used (and autodoc_default_options is ignored).

About a minus sign, it's not late to write a code if somebody will request it.

@pbudzyns pbudzyns changed the title local :exclude-members: option extends global one Local autodoc options override or extend global config. Jan 29, 2021
@pbudzyns pbudzyns changed the title Local autodoc options override or extend global config. Local autodoc options override or extend autodoc_default_options. Jan 29, 2021
@shimizukawa
Copy link
Member

+1 to @tk0miya 's idea.
I feel that introducing the ｰ sign would make it harder to understand what the current option is.

tk0miya
tk0miya requested changes Jan 30, 2021
View reviewed changes
Copy link
Member

@tk0miya tk0miya left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with nits for the code. Addition to this, could you update document for autodoc (doc/usage/extensions/autodoc.rst)?

sphinx/ext/autodoc/directive.py
if name in options:
# take value from options if present or extend it
# with autodoc_default_options if necessary
if name in AUTODOC_EXTENDABLE_OPTIONS:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please check autodoc_default_options[name] is string here. It can take boolean value or None also. When it equals to True or None, it matches all of members. So enhancement is meaningless.

sphinx/ext/autodoc/directive.py Outdated
else:
options[name] = config.autodoc_default_options[name]

elif isinstance(options.get(name), str) and options[name].startswith('+'):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You don't need to check the options.get(name) via isinstance because it's always a string if given. It's enough to check options.get(name) is not None only.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense, so there were mistakes in already existing tests I think:
https://github.com/sphinx-doc/sphinx/blob/3.x/tests/test_ext_autodoc.py#L940
https://github.com/sphinx-doc/sphinx/blob/3.x/tests/test_ext_autodoc.py#L868
etc.

I replaced these True's with None.

@tk0miya
Copy link
Member

tk0miya commented Jan 30, 2021

@shimizukawa Thank you for comment.

@tk0miya tk0miya merged commit 0d50b97 into sphinx-doc:3.x Feb 4, 2021
@tk0miya
Copy link
Member

tk0miya commented Feb 4, 2021

Merged. Thank you for your great contribution!

tk0miya added a commit that referenced this pull request Feb 4, 2021
@tk0miya
Update CHANGES for PR #8297
572c9a4
timobrembeck added a commit to timobrembeck/sphinxcontrib-django2 that referenced this pull request Mar 2, 2021
@timobrembeck
Make tests compatible with sphinx 3.5.0
6adf829 
The function sphinx.ext.autodoc.directive.process_documenter_options() used in do_autodoc() changed its option processing.
See sphinx-doc/sphinx#8297 for more information.
timobrembeck added a commit to timobrembeck/sphinxcontrib-django2 that referenced this pull request Mar 2, 2021
@timobrembeck
Make tests compatible with sphinx 3.5.0
23aa48b 
The function sphinx.ext.autodoc.directive.process_documenter_options() used in do_autodoc() changed its option processing.
See sphinx-doc/sphinx#8297 for more information.
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 15, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@tk0miya tk0miya tk0miya approved these changes

Assignees
No one assigned
Labels
extensions:autodoc type:enhancement enhance or introduce a new feature
Projects
None yet
Milestone
3.5.0
Development

Successfully merging this pull request may close these issues.

None yet
3 participants
@pbudzyns @tk0miya @shimizukawa