Documentation paths are ambiguous on case insensitive file systems

[jnothman]

Master's documentation build produces files including:

modules/generated/sklearn.cluster.dbscan.html
modules/generated/sklearn.cluster.DBSCAN.html
modules/generated/sklearn.cluster.optics.html
modules/generated/sklearn.cluster.OPTICS.html

These paths will not work well on file systems that are case insensitive. Does anyone know of a way to make the sphinx autogen functionality generate alternative names in this case? Ideally we would do so in a way that keeps sklearn.cluster.DBSCAN.html which has existed in previous releases, while sklearn.cluster.dbscan.html did not.

We could also do post-processing so that documentation packages can be shared with case insensitive platforms, even if they cannot be generated on case-insensitive platforms.

Discovered in the context of Kapeli/Dash-User-Contributions#2143

[thomasjpfan]

Glad to see I am not the only person using Dash! 👍

There does not seem to be a simple way to do this. There are issues open that relate to this issue: sphinx-doc/sphinx#4874, sphinx-doc/sphinx#2024

Matplotlib has a solution to this: matplotlib/matplotlib#11079 but I do not think we can use their solution for our use case.

[jnothman]

It actually doesn't look like it should be hard to fix:

• all paths being generated are known here (assuming they're not modified by import_by_name here, and it seems that should never happen since it is called with only name and no prefixes)
• you need some method of mangling the filename here in case of clash

[trungpham10]

Hi I'm new here. Can I take this issue?

[adrinjalali]

If you're comfortable with sphinx, sure, go ahead.

[jnothman]

I think it needs solving at sphinx, not here. Are you working on it @trungpham10

[trungpham10]

@jnothman Right now I'm not sure how to fix this ...

[jnothman]

I think the first step would be to construct a minimal example of sphinx docs that reproduces the issue, without respect to scikit-learn. Having done that, we can try find a solution.

[thomasjpfan]

If you are following @jnothman suggestion of filename mangling at: sphinx/ext/autosummary/generate.py, it would be good to look at: sphinx/ext/autosummary/__init__.py. This run function will use the name in toctree to try to find the generated file. If the name was mangled, the generated file would not be found and toctree references unknown document warning would be issued.

I suspect a patch to sphinx that introduces a warning would be hard to merge.

[thomasjpfan]

Closing because we are using autosummary_filename_map to resolve this issue.