Repository navigation
[Docs] ReadTheDocs builds failing #2795
Description
Activity
Hi @echedey-ls! I'd like to work on fixing this.
After reading through the issue, I think the fix is straightforward — replace all "link" type timezone aliases in the repo with their canonical equivalents:
US/Eastern→America/New_YorkAsia/Calcutta→Asia/KolkataUS/Mountain→America/DenverUS/Arizona→America/PhoenixMST→America/Phoenix
I'll grep across
docs/andpvlib/(including.py,.rst, and notebook files) to catch all occurrences and open a focused PR.A couple of questions before I start:
- Is anyone already working on this?
- Should I also add
tzdataas an explicit dependency as a safety net, or just replace the timezone strings?
Thanks!
@dgowdaan-cmyk I rather have a definitive answer on how to verify if these timezones were removed or not from Ubuntu 26.04 LTS internal timezone database (or whatever docker image RTD uses).
Cause in their docs, while "link" timezones are deprecated 1, the ones failing for us are also listed in the catalog 2.I guess we could go straight ahead with my suggested changes. However, tracing the root cause is specially important to notify users not only of changes we may do to documentation and examples, but to make a reminder for all of them with more automatic approaches that can encounter the same problem.
Footnotes
Thanks for the pointer to DateTime::TimeZone::Catalog — that confirms US/Eastern and similar are still valid IANA aliases in general.
My hypothesis is that Ubuntu 26.04's tzdata package may have dropped the /usr/share/zoneinfo/US/* link files specifically. I don't have a Ubuntu 26.04 environment handy to confirm this directly, but it should be visible in RTD's build logs if someone with access can check ls /usr/share/zoneinfo/US.
Either way, I think replacing with canonical names is the safer fix regardless of root cause, since it removes the dependency on the OS providing those link files at all.
I've opened #2798 with the replacement for plot_discontinuous_tracking.py, kept intentionally scoped to one file for easier review. Planned follow-ups: the remaining affected files (docs/examples, docs/tutorials, docs/sphinx), and adding tzdata as an explicit dependency as a safety net.- changed the title
[-]ReadTheDocs builds failing[/-][+][Docs] ReadTheDocs builds failing[/+]on Jul 2, 2026 I searched through Ubuntu's LTS changelog 24 -> 26 but couldn't locate changes to timezone databases: https://documentation.ubuntu.com/release-notes/26.04/summary-for-lts-users/
#2803 shows that the relevant change happened between 22 and 24. I see some
tzdataentries there, but I cannot investigate any more at the moment.Also: great detective work @echedey-ls!
Ubuntu 24.04 split tzdata and moved legacy symlinks (like US/*) into tzdata-legacy [1]. Readthedocs moved Ubuntu LTS from 22.04 -> 26.04 inheriting this change [2].
Instead of code changes, I suggest adding tzdata as a runtime dependency. We explicitly depend on it [3] and this ensures the package is self-contained and follows guidance from the docs [4].
The zoneinfo module does not directly provide time zone data, and instead pulls time zone information from the system time zone database or the first-party PyPI package tzdata, if available. Some systems, including notably Windows systems, do not have an IANA database available, and so for projects targeting cross-platform compatibility that require time zone data, it is recommended to declare a dependency on tzdata.
@kandersolar since you already have a draft PR for testing, would you mind trying the following:
- Add tzdata to pyproject.toml dependencies
- Revert readthedocs.yml to os: ubuntu-lts-latest
- Verify the build completes and tests pass
References
Reacted by Mark Mikofski and Echedey LuisI tested on my branch and verified adding tzdata fixes the doc build [1]. I have since reverted in the spirit of keeping that PR focused.
References
Reacted by Echedey LuisThanks for such a deep research @yonryzhu ❣️
I have mixed feelings for the possible fixes. I kind of like using up-to-date timezones for reliability, making the package lighter to install and out-of-the-box compatible with slimmer OS runner images. But I guess timezones are so common in pvlib use cases that making all available can be beneficial.
@pvlib/maintainer, I summon you. I'm neutral leaning a bit towards using non-link type timezones and adding an admonition in the timezones user guide.
@echedey-ls my preference is to use tzdata. I agree it would be ideal to use
zoneinfobut in reality, I think- the tzdata IANA files are more reliable & more often updated than system files.
- the tzdata package is very small, only 200kB
- tzdata is more complete and easier to use
IMHO user experience is better with tzdata, & reasons for
zoneinfoare not compelling enough to prioritizeReacted by Echedey Luis#2757 deprecated using the
tzdatapackage in pvlib code in order to shift tozoneinfo. Maybe that was premature. Sincezoneinforelies (for now) ontzdataon Windows platforms. I don't think it's a choice;tzdatashould remain a dependency.If pvlib does something so that link timezones no longer work, then we'll hear about it. For that reason I think its better to support them.
Reacted by Echedey Luis and Mark Mikofski#2757 deprecated using the
tzdatapackagetzdatashould remain a dependencyWell, more precisely speaking the deprecated package was
pytz, which iszoneinfoequivalent thou deprecated.pytzdid come with its own timezone database information, whose equivalent would be, that's right,tzdataforzoneinfo. But yeah, I agree a 1:1 replacement topytzwould have beenzoneinfo+tzdata; thou it was probably hard for us to see such best practice back then.I've been convinced. Let's add
tzdataas a hard dependency. @yonryzhu are you up for its contribution? It's exactly what you described and pushed earlier.Reacted by Kevin Anderson, Yonry Zhu and Mark MikofskiWell, more precisely speaking
Actually, "correctly speaking" since I was simply off track :) Thanks for seeing what I meant to say.
Reacted by Echedey LuisReacted by Echedey Luis
Describe the bug
RTD build of PRs #2787 and #2793 are failing.
I'm attaching a comment I had prepared to submit to RTD issues. But to sum it up, seems like the only timezones failing are those whose type is
link(of any type), as per wikipedia table: https://en.wikipedia.org/wiki/List_of_tz_database_time_zonesI haven't been able to understand whether "link" type is an euphemism for "deprecated", or a reason for OSes to not bundle them. I'll defer opening an issue to RTD in case anybody of you @pvlib/pvlib-maintainer are more knowledgeable than me in this topic - which is almost 100% the case.
Down below is my nearly-completed comment that I was about to upload to RTD when I found some of the timezones did in fact work. Maybe the solution is just to go ahead with canonical timezones, but what I don't quite understand is that Ubuntu changelog does not have any mention to timezone database changes. And I haven't dug Ubuntu's source code to see exactly which database version they ship, with or without link type timezones.
vvv Comment as written to upload to RTD vvvDetails
Expected Result
Documentation to build successfully.
Actual Result
See log (trimmed):
../../examples/solar-tracking/plot_discontinuous_tracking.py failed leaving traceback: Traceback (most recent call last): File "/home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/checkouts/2787/docs/examples/solar-tracking/plot_discontinuous_tracking.py", line 53, in <module> times = pd.date_range('2019-06-01', '2019-06-02', freq='1min', tz='US/Eastern') ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/envs/2787/lib/python3.12/site-packages/pandas/core/indexes/datetimes.py", line 1491, in date_range dtarr = DatetimeArray._generate_range( ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/envs/2787/lib/python3.12/site-packages/pandas/core/arrays/datetimes.py", line 461, in _generate_range tz = _infer_tz_from_endpoints(start, end, tz) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "/home/docs/checkouts/readthedocs.org/user_builds/pvlib-python/envs/2787/lib/python3.12/site-packages/pandas/core/arrays/datetimes.py", line 2878, in _infer_tz_from_endpoints tz = timezones.maybe_get_tz(tz) ^^^^^^^^^^^^^^^^^^^^^^^^^^ File "pandas/_libs/tslibs/timezones.pyx", line 134, in pandas._libs.tslibs.timezones.maybe_get_tz File "pandas/_libs/tslibs/timezones.pyx", line 159, in pandas._libs.tslibs.timezones.maybe_get_tz File "/home/docs/.asdf/installs/python/3.12.12/lib/python3.12/zoneinfo/_common.py", line 24, in load_tzdata raise ZoneInfoNotFoundError(f"No time zone found with key {key}") zoneinfo._common.ZoneInfoNotFoundError: 'No time zone found with key US/Eastern'This error appeared for the first time yesterday (that I'm aware of), presumably because we had not triggered other documentation builds earlier. But this coincides with latest release of RTD that updates Ubuntu to 26 LTS.
Here is other context, specially a previous issue on this repo:
zoneinfopython native module relies, on Linux, on OS-installed IANA database, else ontzdata, hereby raising an exception if neither of them are available: https://docs.python.org/3/library/zoneinfo.html#data-sourcesI searched through Ubuntu's LTS changelog 24 -> 26 but couldn't locate changes to timezone databases: https://documentation.ubuntu.com/release-notes/26.04/summary-for-lts-users/
I must say the timezones that don't work for us are:
US/Eastern(type: link)Asia/Calcutta(type: link)MST(type: link†)US/Mountain(type: link)US/Arizona(type: link)type link: Alternative names for canonical zones. † indicates zones that were canonical in the past but are no longer.
The previous statement, as is from Wikipedia: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
I wonder if the issue has something to do with these timezones being of such type.
We have other tz strings in our project that seem to work without any issues:
Etc/GMT+5,Etc/GMT+7,UTC,America/Denver,America/Phoenix. All previous timezones type iscanonicalas per the same Wikipedia table.