sphinx-doc/sphinx

autosummary: Autogenerating stubs on case-insensitive filesystem sometimes fails

Open

#1495 opened on Jan 3, 2015

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

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

Tech stack
python
Domain
documentationdeveloper experience
Issue type
bug
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
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
Pythonfilesystem basics
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
The bug is in sphinx/ext/autosummary/generate.py at line 135 where os.path.isfile() is called. On case insensitive filesystems, this returns True for different cased filenames, causing autogeneration to fail silently and produce warnings. A fix could check the platform or compare the filenames case sensitively. The issue has been open since 2015 with no activity, so a fresh PR would be welcome.