[Docs] ReadTheDocs builds failing

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_zones

I 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 vvv

Details

Read the Docs project URL: https://pvlib-python.readthedocs.io/en/stable/
Build URL (if applicable): https://app.readthedocs.org/projects/pvlib-python/builds/33291002/
Read the Docs username (if applicable): NA

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:

ReadTheDocs latest release updated Ubuntu to LTS 26 https://github.com/readthedocs/readthedocs.org/releases
zoneinfo python native module relies, on Linux, on OS-installed IANA database, else on tzdata, hereby raising an exception if neither of them are available: https://docs.python.org/3/library/zoneinfo.html#data-sources
It is reported in 2023 to RTD in Celery: ZoneInfoNotFoundError on development instance readthedocs/readthedocs.org#10453
1. And incorporated in the PR fix Images: Add tzdata as explicit requirement readthedocs/readthedocs.org#10480
Then in the following PR, when Ubuntu is updated to LTS 24, it is removed Upgrade to Ubuntu 24.04 for our application readthedocs/readthedocs.org#12002

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/

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 is canonical as per the same Wikipedia table.

@echedey-ls

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_York
Asia/Calcutta → Asia/Kolkata
US/Mountain → America/Denver
US/Arizona → America/Phoenix
MST → America/Phoenix

I'll grep across docs/ and pvlib/ (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 tzdata as an explicit dependency as a safety net, or just replace the timezone strings?

Thanks!

@dgowdaan-cmyk

@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 ¹, the ones failing for us are also listed in the catalog ².

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.

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.

@echedey-ls

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 tzdata entries there, but I cannot investigate any more at the moment.

Also: great detective work @echedey-ls!

@echedey-ls

@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

https://discourse.ubuntu.com/t/ubuntu-24-04-lts-noble-numbat-release-notes/39890#p-99950-tzdata-package-split-29
https://github.com/readthedocs/readthedocs.org/pull/13020/changes
pvlib-python/pvlib/location.py

Line 108 in 0f7a205

self._zoneinfo = zoneinfo.ZoneInfo(tz_)
https://docs.python.org/3.12/library/zoneinfo.html#data-sources

I 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

https://app.readthedocs.org/projects/pvlib-python/builds/33441212/

@yonryzhu

Thanks 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

@echedey-ls my preference is to use tzdata. I agree it would be ideal to use zoneinfo but 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 zoneinfo are not compelling enough to prioritize

#2757 deprecated using the tzdata package in pvlib code in order to shift to zoneinfo. Maybe that was premature. Since zoneinfo relies (for now) on tzdata on Windows platforms. I don't think it's a choice; tzdata should 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.

@yonryzhu

#2757 deprecated using the tzdata package

tzdata should remain a dependency

Well, more precisely speaking the deprecated package was pytz, which is zoneinfo equivalent thou deprecated. pytz did come with its own timezone database information, whose equivalent would be, that's right, tzdata for zoneinfo. But yeah, I agree a 1:1 replacement to pytz would have been zoneinfo + tzdata; thou it was probably hard for us to see such best practice back then.

I've been convinced. Let's add tzdata as a hard dependency. @yonryzhu are you up for its contribution? It's exactly what you described and pushed earlier.

Well, more precisely speaking

Actually, "correctly speaking" since I was simply off track :) Thanks for seeing what I meant to say.

Navigation Menu

Repository navigation

[Docs] ReadTheDocs builds failing #2795

Details

Expected Result

Actual Result

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[Docs] ReadTheDocs builds failing #2795

Description

Details

Expected Result

Actual Result

Activity

dgowdaan-cmyk commented on Jun 28, 2026

echedey-ls commented on Jun 29, 2026

Footnotes

dgowdaan-cmyk commented on Jun 30, 2026

kandersolar commented on Jul 3, 2026

yonryzhu commented on Jul 4, 2026

yonryzhu commented on Jul 4, 2026

echedey-ls commented on Jul 5, 2026

mikofski commented on Jul 5, 2026

cwhanse commented on Jul 5, 2026

echedey-ls commented on Jul 5, 2026

cwhanse commented on Jul 6, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions