Correct handling of `__init__.pyi`

Closes #405

autoapi/mappers/python/mapper.py

@@ -268,6 +268,7 @@ class PythonSphinxMapper(SphinxMapperBase):
             dir_root = dir_
             if (
                 os.path.exists(os.path.join(dir_, "__init__.py"))
+                or os.path.exists(os.path.join(dir_, "__init__.pyi"))
                 or self._use_implicit_namespace
             ):
                 dir_root = os.path.abspath(os.path.join(dir_, os.pardir))

autoapi/mappers/python/parser.py

@@ -24,7 +24,7 @@ class Parser:
     def _parse_file(self, file_path, condition):
         directory, filename = os.path.split(file_path)
         module_parts = []
-        if filename != "__init__.py":
+        if filename != "__init__.py" and filename != "__init__.pyi":
             module_part = os.path.splitext(filename)[0]
             module_parts = [module_part]
         module_parts = collections.deque(module_parts)
@@ -40,7 +40,10 @@ class Parser:
     def parse_file(self, file_path):
         return self._parse_file(
             file_path,
-            lambda directory: os.path.isfile(os.path.join(directory, "__init__.py")),
+            lambda directory: (
+                os.path.isfile(os.path.join(directory, "__init__.py"))
+                or os.path.isfile(os.path.join(directory, "__init__.pyi"))
+            ),
         )
 
     def parse_file_in_namespace(self, file_path, dir_root):

docs/changes/398.bugfix

@@ -0,0 +1 @@
+Fix submodule with `__init__.pyi` documented as `__init__` instead of submodule name

tests/python/pyisubmoduleinit/conf.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+
+templates_path = ["_templates"]
+source_suffix = ".rst"
+master_doc = "index"
+project = "pyisubmoduleinit"
+copyright = "2015, readthedocs"
+author = "readthedocs"
+version = "0.1"
+release = "0.1"
+language = "en"
+exclude_patterns = ["_build"]
+pygments_style = "sphinx"
+todo_include_todos = False
+html_theme = "alabaster"
+htmlhelp_basename = "pyisubmoduleinitdoc"
+extensions = ["sphinx.ext.autodoc", "autoapi.extension"]
+autoapi_dirs = ["example"]

tests/python/pyisubmoduleinit/example/submodule_foo/__init__.pyi

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+"""Example __init__ in submodule foo
+
+Documentation generated for this file
+should be titled submodule_foo instead of __init__
+
+This is a description
+"""
+
+class Foo(object):
+    """
+    This is a description
+    """
+
+    def bar(self, a: int) -> None:
+        """
+        This is a description
+        """
+        ...

tests/python/pyisubmoduleinit/index.rst

@@ -0,0 +1,15 @@
+Welcome to pyisubmoduleinit's documentation!
+============================================
+
+.. toctree::
+
+   autoapi/index
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

tests/python/test_pyintegration.py

@@ -300,6 +300,20 @@ class TestSimpleStubModuleNotPreferred:
         assert foo_sig
 
 
+class TestStubInitModuleInSubmodule:
+    @pytest.fixture(autouse=True, scope="class")
+    def built(self, builder):
+        builder("pyisubmoduleinit", warningiserror=True)
+
+    def test_integration(self, parse):
+        example_file = parse("_build/html/autoapi/example/index.html")
+
+        # Documentation should list
+        # submodule_foo instead of __init__
+        assert example_file.find(title="submodule_foo")
+        assert not example_file.find(title="__init__")
+
+
 class TestPy3Module:
     @pytest.fixture(autouse=True, scope="class")
     def built(self, builder):