sphinx-doc / sphinx-doc/sphinx

Can't get actual values of added config items in extension setup

Open
#6,002 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

api type:proposal
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.