Merge pull request #6412 from tk0miya/refactor_apidoc

refactor apidoc: Add is_skipped_module()

sphinx/ext/apidoc.py

@@ -135,7 +135,7 @@ def create_package_file(root, master_package, subroot, py_files, opts, subs, is_
                    for pkgname in subpackages]
     # build a list of sub modules
     submodules = [path.splitext(sub)[0] for sub in py_files
-                  if not shall_skip(path.join(root, sub), opts, excludes) and
+                  if not is_skipped_module(path.join(root, sub), opts, excludes) and
                   sub != INITPY]
     submodules = [module_join(master_package, subroot, modname)
                   for modname in submodules]
@@ -207,6 +207,19 @@ def shall_skip(module, opts, excludes=[]):
     return False
 
 
+def is_skipped_module(filename, opts, excludes):
+    # type: (str, Any, List[str]) -> bool
+    """Check if we want to skip this module."""
+    if not path.exists(filename):
+        # skip if the file doesn't exist
+        return True
+    elif path.basename(filename).startswith('_') and not opts.includeprivate:
+        # skip if the module has a "private" name
+        return True
+    else:
+        return False
+
+
 def recurse_tree(rootpath, excludes, opts):
     # type: (str, List[str], Any) -> List[str]
     """
@@ -264,7 +277,7 @@ def recurse_tree(rootpath, excludes, opts):
             # if we are at the root level, we don't require it to be a package
             assert root == rootpath and root_package is None
             for py_file in py_files:
-                if not shall_skip(path.join(rootpath, py_file), opts):
+                if not is_skipped_module(path.join(rootpath, py_file), opts, excludes):
                     module = path.splitext(py_file)[0]
                     create_module_file(root_package, module, opts)
                     toplevels.append(module)

tests/test_ext_apidoc.py

@@ -401,6 +401,21 @@ def test_subpackage_in_toc(make_app, apidoc):
     assert (outdir / 'parent.child.foo.rst').isfile()
 
 
+def test_private(tempdir):
+    (tempdir / 'hello.py').write_text('')
+    (tempdir / '_world.py').write_text('')
+
+    # without --private option
+    apidoc_main(['-o', tempdir, tempdir])
+    assert (tempdir / 'hello.rst').exists()
+    assert not (tempdir / '_world.rst').exists()
+
+    # with --private option
+    apidoc_main(['--private', '-o', tempdir, tempdir])
+    assert (tempdir / 'hello.rst').exists()
+    assert (tempdir / '_world.rst').exists()
+
+
 def test_toc_file(tempdir):
     outdir = path(tempdir)
     (outdir / 'module').makedirs()