List of countries / providers

[iquito]

What I really missed in the documentation was a list of providers that can be chosen. Ideally, there would be a list of all providers with:

• Number of holidays in that provider
• Some hint about how the holidays were chosen / how the holidays work in that country, as somebody might try to use the library for a country they do not know super well
• Possible caveats. A good example is Switzerland, as explained in my other issue, where holidays are highly regional, yet there are some common denominators across the country

That would make the usage of this library easier and less error-prone, and it could be a good short documentation of holidays in different countries in general, which can be useful even to people not using the library (just as a bonus).

[stelgenhof]

Thank you for highlighting this. Definitely the documentation could be improved in the areas you've mentioned. Let me make a note of this and see if I can incorporate this in a next release.

Cheers! Sacha

[stelgenhof]

@iquito Had some more thoughts about your question and points:

• The number of holidays for each provider can vary per year. Some holidays are cancelled or replaced, and some new ones get introduced.
• That would be indeed good to have. At the moment the best source for this is the source code
• There will be indeed many countries with such construction of holidays.

I feel that creating and maintaining such information manually can be pretty time consuming. Having this automatically generated would be my preference. Just need to think how that could be done in a good, systematic manner.

Cheers! Sacha

[iquito]

I would also not handle this information separately from the code. The best way, in my opinion, would be to add some description/explanation as PHPDoc blocks to the providers, so the information is right there in the class with the logic, but can be extracted to a succint list. "How the holidays were chosen" and "possible caveats" would be my suggestions for additions there, as a high level overview of how the provider works and for documentation.

The number of holidays could be calculated with the provider (by executing it), and one can even add a note if it ever changes according to year (in many cases it probably won't). An easy first step could be to show the number of holidays in the current year.

Nice would be a list of holidays for each provider (maybe showing on a details page, or by clicking "Show more" in the documentation). This could also be done in an automated way, as you use identifying strings for each holiday as far as I saw, like "easter", "easterMonday", "pentecostMonday" and so on. One would just need the whole list of all holiday identifiers, a useable name for each (for the documentation), and a link to look it up on Wikipedia ideally, then you could calculate the holidays for a provider and list those with references. You could also show if they differ depending on year, by just calculating them for the last 100 years or so, showing the still valid ones first and the past ones after that (although that sounds like a next step after having the initial list of current holidays for each provider).

Once this kind of processing is in place, it would be easy to add it for more providers, or adjust it according to changes. And the documentation could be empty for many countries in the beginning (except the calculated parts) and could be added by people who use the library or have knowledge of the holidays, as needed (doesn't need to be perfect right away - having something instead of nothing would already be a nice big step).

[stelgenhof]

@iquito That would be my approach as well :)

[github-actions[bot]]

This issue has been open 60 days with no activity. Please remove the stale label or comment, or this will be closed in 10 days.

[stelgenhof]

@iquito Not answering all your questions but the new Yasumi Documentation site has a list of all the countries and the holidays for this year documented. You can have a look here: https://www.yasumi.dev/docs/providers/

Cheers! Sacha

[stelgenhof]

@iquito Going forward with the new documentation site, please submit any new issues or requests regarding the documentation to the Gitlab Repository here: https://gitlab.com/azuyalabs/yasumi/docs

[github-actions[bot]]

This issue has been open 60 days with no activity. Please remove the stale label or comment, or this will be closed in 10 days.

[stelgenhof]

Transferred to: https://gitlab.com/azuyalabs/yasumi/docs/-/issues/3