From 72ca2bdffc2947d818b1cd36484debe577a25dbc Mon Sep 17 00:00:00 2001
From: Joel Nothman <joel.nothman@gmail.com>
Date: Wed, 8 Jul 2020 16:45:07 +1000
Subject: [PATCH] Add autosummary_filename_map config to avoid clashes

---
 doc/usage/extensions/autosummary.rst    |  9 ++++++
 sphinx/ext/autosummary/__init__.py      |  1 +
 sphinx/ext/autosummary/generate.py      | 12 ++++++--
 tests/roots/test-autosummary/sphinx.rst | 39 ++++++++-----------------
 tests/test_ext_autosummary.py           | 16 ++++++++++
 5 files changed, 48 insertions(+), 29 deletions(-)

diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst
index 38d18361e..c1f59170b 100644
--- a/doc/usage/extensions/autosummary.rst
+++ b/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
 ---------------------
diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py
index 0984377c5..ece16c15b 100644
--- a/sphinx/ext/autosummary/__init__.py
+++ b/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}
diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py
index d908e2088..2693c9008 100644
--- a/sphinx/ext/autosummary/generate.py
+++ b/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()
diff --git a/tests/roots/test-autosummary/sphinx.rst b/tests/roots/test-autosummary/sphinx.rst
index fc1a35a0e..7b47b2c0e 100644
--- a/tests/roots/test-autosummary/sphinx.rst
+++ b/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
+   
+   
+   
\ No newline at end of file
diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py
index 3dd90b8ce..fe16092dd 100644
--- a/tests/test_ext_autosummary.py
+++ b/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()