commit 0354799f583ecdda814349d2fc57a7fb9494a200 Author: Damian Johnson atagar@torproject.org Date: Wed May 13 18:07:47 2020 -0700
Ignore __all__ attributes when bulding site
Sphinx emits the following warnings...
WARNING: missing attribute mentioned in :members: or __all__: module stem, attribute directory WARNING: missing attribute mentioned in :members: or __all__: module stem, attribute process WARNING: missing attribute mentioned in :members: or __all__: module stem.descriptor, attribute remote WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute getinfo WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute getconf WARNING: missing attribute mentioned in :members: or __all__: module stem.response, attribute authchallenge WARNING: missing attribute mentioned in :members: or __all__: module stem.util, attribute lru_cache WARNING: missing attribute mentioned in :members: or __all__: module stem.util, attribute ordereddict WARNING: missing attribute mentioned in :members: or __all__: module stem.util, attribute term WARNING: missing attribute mentioned in :members: or __all__: module stem.util, attribute test_tools
These submodules all exist, but importlib.import_module() does not have attributes corresponding to them unless we've transitively imported its code prior to Sphinx's attempt to reference it.
Honestly I don't fully grok the nuance behind how importlib works, but this configuration flag resolves these warnings so calling it good. --- docs/conf.py | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+)
diff --git a/docs/conf.py b/docs/conf.py index 03268c57..aef0ff93 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -33,6 +33,30 @@ autodoc_default_options = { 'member-order': 'bysource', 'show-inheritance': True, 'undoc-members': True, + + # Without this Sphinx emits several warnings of the form... + # + # WARNING: missing attribute mentioned in :members: or __all__: module stem, attribute directory + # + # This is because Sphinx expects modules from importlib.import_module() to + # have attributes for its submodules. These attributes might or might not be + # present depending on what other modules have been imported. + # + # Said another way... + # + # % print(importlib.import_module('stem').__dict__.keys()) + # dict_keys(['__name__', '__doc__', '__package__', ...]) <= doesn't have submodules + # + # But if instead we call... + # + # % importlib.import_module('stem.connection') + # % print(importlib.import_module('stem').__dict__.keys()) + # dict_keys(['__name__', '__doc__', '__package__', ..., 'descriptor', 'control', 'connection']) <= includes submodules refernced by stem.connection + # + # By telling it to ignore our '__all__' attributes Sphinx will import in a + # fashon that doesn't emit these warnings. + + 'ignore-module-all': True, }
# Add any paths that contain templates here, relative to this directory.