Skip to content

Documentation paths are ambiguous on case insensitive file systems #12712

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
jnothman opened this issue Dec 2, 2018 · 9 comments
Closed

Documentation paths are ambiguous on case insensitive file systems #12712

jnothman opened this issue Dec 2, 2018 · 9 comments
Labels
Documentation help wanted

Comments

@jnothman
Copy link
Member

jnothman commented Dec 2, 2018

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
Copy link
Member

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
Copy link
Member Author

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
Copy link

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

@adrinjalali
Copy link
Member

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

@jnothman
Copy link
Member Author

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

@trungpham10
Copy link

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

@jnothman
Copy link
Member Author

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
Copy link
Member

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 thomasjpfan mentioned this issue Jan 13, 2019
Closed
@thomasjpfan thomasjpfan mentioned this issue Jan 21, 2019
Merged
@jnothman jnothman mentioned this issue Jul 8, 2020
Merged
@thomasjpfan
Copy link
Member

Closing because we are using autosummary_filename_map to resolve this issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation help wanted
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

[MRG] Patches sphinx's autosummary to handle case insensitive file systems thomasjpfan/scikit-learn
4 participants
@jnothman @adrinjalali @thomasjpfan @trungpham10