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 sys
 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, Type, Union
 
 from jinja2 import TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
@@ -393,6 +393,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 +426,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-autosummary/sphinx.rst

@@ -1,31 +1,16 @@
-Autosummary test
-================
+sphinx
+======
 
-.. autosummary::
-   :toctree: generated
+.. automodule:: sphinx
 
-   sphinx.application.Sphinx
+   
+   
+   
 
-.. currentmodule:: sphinx.application
+   
+   
+   
 
-.. autoclass:: TemplateBridge
-
-   Basic test
-
-   .. autosummary::
-
-      render                    -- some ignored stuff goes here
-      render_string             More ignored stuff
-
-   Test with tildes
-
-   .. autosummary::
-
-      ~TemplateBridge.render
-      ~TemplateBridge.render_string
-
-   Methods:
-
-  .. automethod:: render
-
-  .. automethod:: render_string
+   
+   
+   

tests/test_ext_autosummary.py

@@ -386,6 +386,22 @@ def test_autosummary_recursive(app, status, warning):
     assert 'package.package.module' in content
 
 
+@pytest.mark.sphinx('dummy', testroot='ext-autosummary-recursive',
+                    confoverrides={'autosummary_filename_map':
+                                   {"package": "package_mangled",
+                                    "package.package": "package_package_mangled"}})
+def test_autosummary_filename_map(app, status, warning):
+    app.build()
+
+    assert (app.srcdir / 'generated' / 'package_mangled.rst').exists()
+    assert not (app.srcdir / 'generated' / 'package.rst').exists()
+    assert (app.srcdir / 'generated' / 'package.module.rst').exists()
+    assert (app.srcdir / 'generated' / 'package.module_importfail.rst').exists() is False
+    assert (app.srcdir / 'generated' / 'package_package_mangled.rst').exists()
+    assert not (app.srcdir / 'generated' / 'package.package.rst').exists()
+    assert (app.srcdir / 'generated' / 'package.package.module.rst').exists()
+
+
 @pytest.mark.sphinx('latex', **default_kw)
 def test_autosummary_latex_table_colspec(app, status, warning):
     app.builder.build_all()