From e932ff5ad2f9e1241c06506d42b14c2d5ecd8b44 Mon Sep 17 00:00:00 2001
From: Kevin Keating <kevin.keating@schrodinger.com>
Date: Wed, 20 Dec 2017 15:07:33 -0500
Subject: [PATCH] Closes #947: autodoc now supports ignore-module-all to ignore
 a module's __all__

---
 CHANGES                        | 1 +
 doc/ext/autodoc.rst            | 8 +++++---
 sphinx/ext/autodoc/__init__.py | 7 ++++---
 tests/test_autodoc.py          | 7 +++++++
 4 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/CHANGES b/CHANGES
index 3023ee8c0..0206e84b5 100644
--- a/CHANGES
+++ b/CHANGES
@@ -50,6 +50,7 @@ Features added
 * #3160: html: Use ``<kdb>`` to represent ``:kbd:`` role
 * #4212: autosummary: catch all exceptions when importing modules
 * #3991, #4080: Add :confval:`math_numfig` for equation numbering by section
+* #947: autodoc now supports ignore-module-all to ignore a module's ``__all__``
 
 
 Features removed
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index bfd55c81a..09098f39c 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -103,8 +103,10 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
      will document all non-private member functions and properties (that is,
      those whose name doesn't start with ``_``).
 
-     For modules, ``__all__`` will be respected when looking for members; the
-     order of the members will also be the order in ``__all__``.
+     For modules, ``__all__`` will be respected when looking for members unless
+     you give the ``ignore-module-all`` flag option.  Without
+     ``ignore-module-all``, the order of the members will also be the order in
+     ``__all__``.
 
      You can also give an explicit list of members; only these will then be
      documented::
@@ -339,7 +341,7 @@ There are also new config values that you can set:
    This value is a list of autodoc directive flags that should be automatically
    applied to all autodoc directives.  The supported flags are ``'members'``,
    ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
-   ``'inherited-members'`` and ``'show-inheritance'``.
+   ``'inherited-members'``, ``'show-inheritance'`` and ``'ignore-module-all'``.
 
    If you set one of these flags in this config value, you can use a negated
    form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index ff161565c..ddf34a211 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -898,7 +898,7 @@ class ModuleDocumenter(Documenter):
         'platform': identity, 'deprecated': bool_option,
         'member-order': identity, 'exclude-members': members_set_option,
         'private-members': bool_option, 'special-members': members_option,
-        'imported-members': bool_option,
+        'imported-members': bool_option, 'ignore-module-all': bool_option
     }  # type: Dict[unicode, Callable]
 
     @classmethod
@@ -940,7 +940,8 @@ class ModuleDocumenter(Documenter):
     def get_object_members(self, want_all):
         # type: (bool) -> Tuple[bool, List[Tuple[unicode, object]]]
         if want_all:
-            if not hasattr(self.object, '__all__'):
+            if (self.options.ignore_module_all or not
+                    hasattr(self.object, '__all__')):
                 # for implicit module members, check __module__ to avoid
                 # documenting imported objects
                 return True, safe_getmembers(self.object)
@@ -1528,7 +1529,7 @@ class AutoDirective(Directive):
     # flags that can be given in autodoc_default_flags
     _default_flags = set([
         'members', 'undoc-members', 'inherited-members', 'show-inheritance',
-        'private-members', 'special-members',
+        'private-members', 'special-members', 'ignore-module-all'
     ])
 
     # standard docutils directive settings
diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py
index 989c367b6..fda1c561e 100644
--- a/tests/test_autodoc.py
+++ b/tests/test_autodoc.py
@@ -64,6 +64,7 @@ def setup_test():
         members = [],
         member_order = 'alphabetic',
         exclude_members = set(),
+        ignore_module_all = False,
     )
 
     directive = Struct(
@@ -736,6 +737,12 @@ def test_generate():
     else:
         assert False, 'documented CustomEx which is not in __all__'
 
+    # test ignore-module-all
+    options.ignore_module_all = True
+    assert_result_contains('.. py:class:: Class(arg)', 'module', 'test_autodoc')
+    assert_result_contains('.. py:exception:: CustomEx', 'module',
+                           'test_autodoc')
+
     # test noindex flag
     options.members = []
     options.noindex = True