Add autosummary_filename_map config to avoid clashes

[jnothman]

Subject: Add autosummary_filename_map config to allow users to configure alternative filenames for autodoc objects, avoiding name clashes on case-insensitive file systems.

Feature or Bugfix

• Feature
• Bugfix

Purpose

• This allows the user to configure the mapping between object name and filename when performing autodoc generation of HTML files. It adds a config param called autosummary_filename_map to do so. It is a simple dict between name and filename to be generated.
• The intention is that this will allow renames on case-insensitive file systems (per Autodoc may overwrite where functions and classes with different case exist #2024), albeit requiring users to manually identify filenames that might result in name clashes, and propose an alternative filename for the generated docs.

Relates

• Fixes Autodoc may overwrite where functions and classes with different case exist #2024
• Documentation paths are ambiguous on case insensitive file systems scikit-learn/scikit-learn#12712 ping @thomasjpfan

[jnothman]

[fixed branching and force-pushed.]

[tk0miya]

LGTM with nits! I'll merge this after your update soon :-)

[jnothman]

Thank you for the review. I hope I have addressed all comments.

[tk0miya]

You don't need to check the value is dict here. The Sphinx automatically checks the given value is the same type as the default value. But it does not check the contents of the dict. I think the default check is enough.

Note: If you'd like to add more careful validations, please use a hook for the config-inited event to validate user configurations.

sphinx/sphinx/builders/latex/__init__.py

Lines 498 to 503 in 98a854d

	def validate_latex_theme_options(app: Sphinx, config: Config) -> None:
	for key in list(config.latex_theme_options):
	if key not in Theme.UPDATABLE_KEYS:
	msg = __("Unknown theme option: latex_theme_options[%r], ignored.")
	logger.warning(msg % (key,))
	config.latex_theme_options.pop(key)

sphinx/sphinx/builders/latex/__init__.py

Line 558 in 98a854d

app.connect('config-inited', validate_latex_theme_options, priority=800)

[tk0miya]

It is better to add a new config variable alphabetically. Could you move this above?
(I noticed autosummary_imported_members is not. I'll fix it later)

[thomasjpfan]

Tried this for scikit-learn and got an expected warning:

checking consistency... /Users/thomasfan/Repos/scikit-learn-1/doc/modules/generated/dbscan-lowercase.rst: 
WARNING: document isn't included in any toctree
done

[tk0miya]

Oops. Autosummary.run() is also fixed using the new configuration. It constructs a toctree node as a reference to the document file.

[jnothman]

I don't really understand... Is there something I should change?

[tk0miya]

I think some fix is needed to here. Is my understanding incorrect?

sphinx/sphinx/ext/autosummary/__init__.py

Lines 255 to 257 in 03e1070

	for name, sig, summary, real_name in items:
	docname = posixpath.join(tree_prefix, real_name)
	docname = posixpath.normpath(posixpath.join(dirname, docname))

[jnothman]

I think some fix is needed to here. Is my understanding incorrect?

Seems reasonable. I suppose I need to come up with a test case.

[jnothman]

This is ready for review.

[tk0miya]

LGTM with nits. I'll merge this after the fix soon.

[tk0miya]

Just merged. Thank you for your contribution!