sphinx-doc/sphinx

autosummary: Autogenerating stubs on case-insensitive filesystem sometimes fails

Open

#1,495 opened on Jan 3, 2015

View on GitHub
 (5 comments) (0 reactions) (0 assignees)Python (1,985 forks)batch import
extensions:autosummaryhelp wantedtype:bug

Repository metrics

Stars
 (5,625 stars)
PR merge metrics
 (Avg merge 10d 11h) (11 merged PRs in 30d)

Description

If I attempt to autogenerate API docs for a class that has two method names that are identical except for uppercase/lowercase, autogeneration will fail on case-insenstive filesystems.

I ran into this today generating documentation for a class that sublcasses Sympy's Expr class. Expr defines both as_coeff_Add and as_coeff_add as member functions.

When the autosummary extension tries to autogenerate stub .rst files for these two functions, it fails on the second one because the os.path.isfile() call here will return True.

I'd ignore the issue except for the fact that it generates thousands of warning messages in my builds logs, since sphinx still tries to access the nonexistent file every time it traverses the toctree.

Contributor guide

Research direction
Examine the autosummary generate.py code, specifically the os.path.isfile() call at line 135, and modify it to handle case insensitive filesystems by using a case sensitive comparison or checking for duplicates.
Tech stack
python
Domain
documentation
Issue type
Bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
PythonGit
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
65