Add autosummary_filename_map config to avoid clashes

doc/usage/extensions/autosummary.rst

@@ -195,6 +195,15 @@ also use these config values:
 
    .. versionadded:: 2.1
 
+.. confval:: autosummary_filename_map
+
+   A dict mapping object names to filenames. This is necessary to avoid
+   filename conflicts where multiple objects have names that are
+   indistinguishable when case is ignored, on file systems where filenames
+   are case-insensitive.
+
+   .. versionadded:: 3.2
+
 
 Customizing templates
 ---------------------

sphinx/ext/autosummary/__init__.py

@@ -790,5 +790,6 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('autosummary_mock_imports',
                          lambda config: config.autodoc_mock_imports, 'env')
     app.add_config_value('autosummary_imported_members', [], False, [bool])
+    app.add_config_value('autosummary_filename_map', {}, 'html')
 
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

sphinx/ext/autosummary/generate.py

@@ -28,7 +28,7 @@
 import warnings
 from gettext import NullTranslations
 from os import path
-from typing import Any, Callable, Dict, List, NamedTuple, Set, Tuple, Union
+from typing import Any, Callable, Dict, List, Mapping, NamedTuple, Set, Tuple, Union
 
 from jinja2 import TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -74,6 +74,7 @@ def __init__(self, translator: NullTranslations) -> None:
         self.warningiserror = False
 
         self.config.add('autosummary_context', {}, True, None)
+        self.config.add('autosummary_filename_map', {}, True, None)
         self.config.init_values()
 
     def emit_firstresult(self, *args: Any) -> None:
@@ -393,6 +394,14 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
     # keep track of new files
     new_files = []
 
+    if app:
+        filename_map = app.config.autosummary_filename_map
+        if not isinstance(filename_map, Mapping):
+            raise TypeError('autosummary_filename_map should be a mapping from '
+                            'strings to strings')
+    else:
+        filename_map = {}
+
     # write
     for entry in sorted(set(items), key=str):
         if entry.path is None:
@@ -418,7 +427,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None,
                                                imported_members, app, entry.recursive, context,
                                                modname, qualname)
 
-        filename = os.path.join(path, name + suffix)
+        filename = os.path.join(path, filename_map.get(name, name) + suffix)
         if os.path.isfile(filename):
             with open(filename, encoding=encoding) as f:
                 old_content = f.read()

tests/roots/test-ext-autosummary-filename-map/autosummary_dummy_module.py

@@ -0,0 +1,21 @@
+from os import path  # NOQA
+from typing import Union
+
+
+class Foo:
+    class Bar:
+        pass
+
+    def __init__(self):
+        pass
+
+    def bar(self):
+        pass
+
+    @property
+    def baz(self):
+        pass
+
+
+def bar(x: Union[int, str], y: int = 1) -> None:
+    pass

tests/roots/test-ext-autosummary-filename-map/conf.py

@@ -0,0 +1,11 @@
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('.'))
+
+extensions = ['sphinx.ext.autosummary']
+autosummary_generate = True
+autosummary_filename_map = {
+    "autosummary_dummy_module": "module_mangled",
+    "autosummary_dummy_module.bar": "bar"
+}

tests/roots/test-ext-autosummary-filename-map/index.rst

@@ -0,0 +1,14 @@
+
+:autolink:`autosummary_dummy_module.Foo`
+
+:autolink:`autosummary_importfail`
+
+.. autosummary::
+   :toctree: generated
+   :caption: An autosummary
+
+   autosummary_dummy_module
+   autosummary_dummy_module.Foo
+   autosummary_dummy_module.Foo.Bar
+   autosummary_dummy_module.bar
+   autosummary_dummy_module.qux

tests/test_ext_autosummary.py

@@ -386,6 +386,17 @@ def test_autosummary_recursive(app, status, warning):
     assert 'package.package.module' in content
 
 
+@pytest.mark.sphinx('dummy', testroot='ext-autosummary-filename-map')
+def test_autosummary_filename_map(app, status, warning):
+    app.build()
+
+    assert (app.srcdir / 'generated' / 'module_mangled.rst').exists()
+    assert not (app.srcdir / 'generated' / 'autosummary_dummy_module.rst').exists()
+    assert (app.srcdir / 'generated' / 'bar.rst').exists()
+    assert not (app.srcdir / 'generated' / 'autosummary_dummy_module.bar.rst').exists()
+    assert (app.srcdir / 'generated' / 'autosummary_dummy_module.Foo.rst').exists()
+
+
 @pytest.mark.sphinx('latex', **default_kw)
 def test_autosummary_latex_table_colspec(app, status, warning):
     app.builder.build_all()