Autodoc may overwrite where functions and classes with different case exist

[jnothman]

It's possible to have a function and a class in the same module whose names differ only in their case. In fact, scikit-learn includes a few:

• sklearn.cluster.DBSCAN vs sklearn.cluster.dbscan
• sklearn.covariance.OAS vs sklearn.covariance.OAS
• sklearn.decomposition.FastICA vs sklearn.decomposition.fastica

Corresponding files are generated by autodoc and the handling of their different is system dependent: they may be overwritten, or may be distinguished by the OS/filesystem. Is it possible to identify such lowercase duplicates and munge the filenames to avoid conflict?

[jnothman]

What would be the right way to tackle this in Sphinx? It prohibits packaging docs for Windows.

In scikit-learn's doc build, we introduced a config parameter in scikit-learn/scikit-learn#13022 which allows the doc maintainer to specify renames for paths to generated docs:

# Used by custom extension: `custom_autosummary_new_suffix` to change the
# suffix of the following functions. This works around the issue with
# `sklearn.cluster.dbscan` overlapping with `klearn.cluster.DBSCAN`  on
# case insensitive file systems.
custom_autosummary_names_with_new_suffix = {
    'sklearn.cluster.dbscan',
    'sklearn.cluster.optics',
    'sklearn.covariance.oas',
    'sklearn.decomposition.fastica'
}
custom_autosummary_new_suffix = '-lowercase.rst'
custom_autosummary_generated_dirname = os.path.join('modules', 'generated')

The implementation relied on a monkey-patch to os.path.join that would affect the behaviour of autodoc generation. We landed up having to revert it after warnings like:

WARNING: autosummary: stub file not found 'sklearn.cluster.dbscan'. Check your autosummary_generate setting. 

Where/how is the right place to implement a fix?

[tk0miya]

Here is where autosummary determines the filename of the stub files.

sphinx/sphinx/ext/autosummary/generate.py

Line 421 in 533b4ac

filename = os.path.join(path, name + suffix)

[jnothman]

Hurrah! Thank you for the review!