sphinx-doc / sphinx-doc/sphinx
Can't get actual values of added config items in extension setup
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
I'm developing a custom version the autodoc extension that does some things would would probably not be candidates for inclusion in the standard version, so I've called it autodocex. It's based on the 1.8.4 codebase.
I've run into a problem in the setup() function within the init() function, which is that I want to add a configuration item to the application config and use it - that is, use the actual value in the conf.py file - in the initialization, but can't because of the way config.py and Sphinx.init() are written. The problem is that as of the time the extension setup function is called the values in the conf.py have been read and stored in the Config object as _raw_config, but they have not yet been added to the dictionary used by Config.gettattr(), which is done by a call in Sphinx.init() to Config.init_values( )after all the extensions have been loaded.
It's an easy problem to fix, and I've done so in my patched version of Sphinx 1.8.3, but I want to suggest that it be fixed in the official codebase. As far as I can see there is no statement in the docs stating that extension setup() functions can't use the actual values of their own config items, and no reason why they shouldn't be able to.
Here's the code where I encountered the problem:
def autodocex_suppress_class_signature(app, what, name, obj, options, signature, return_annotation):
if what in ('class',):
return ('','')
else:
return None
def autodocex_skip_member(app, what, name, obj, skip, options):
docString = safe_getattr_ex(obj,'doc') or ''
if docString.lstrip().startswith('NODOC'):
return True
else:
return None
def setup(app):
# type: (Sphinx) -> Dict[unicode, Any]
app.add_autodocumenter(ModuleDocumenterEx)
...
app.add_config_value('autoclass_content', 'class', True)
...
app.add_config_value('autodoc_inherit_docstrings', True, True)
# extension-specific config items
app.add_config_value('autodocex_object_description_params', {}, True)
app.add_config_value('autodocex_suppress_class_signatures', True, True)
app.add_config_value('autodocex_skip_nodoc_objects', True, True)
app.add_event('autodoc-process-docstring')
app.add_event('autodoc-process-signature')
app.add_event('autodoc-skip-member')
if app.config.autodocex_suppress_class_signatures: # <--- True (default value) even when set to False in conf.py
app.connect('autodoc-process-signature', autodocex_suppress_class_signature)
if app.config.autodocex_skip_nodoc_objects: # <--- True (default value) even when set to False in conf.py
app.connect('autodoc-skip-member', autodocex_skip_member)
app.connect('config-inited', merge_autodoc_default_flags)
return {'version': sphinx.__display_version__, 'parallel_read_safe': True}
-- John
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Trace configuration loading in config.py and Sphinx.init, focusing on when Config.getattr becomes able to return values from conf.py. Confirm that extension setup() can read the actual values of configuration items it adds, including false values, while preserving the later initialization flow.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100