[tor-commits] [stem/master] Ignore __all__ attributes when bulding site

[atagar@xxxxxxxxxxxxxx]

commit 0354799f583ecdda814349d2fc57a7fb9494a200
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
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.



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits