Migrate Documentation from Sphinx to MkDocs by Roshan-1024 · Pull Request #2289 · vacanza/holidays

Roshan-1024 · 2025-02-12T13:59:52Z

Proposed change

This Draft PR migrates the documentation from Sphinx to MkDocs for simplicity and maintainability.

Changes so far:

Removed Sphinx-based docs/ folder.
Converted .rst files (CONTRIBUTING.rst, README.rst, RELEASE.rst) to Markdown (.md).
Added initial MkDocs setup (mkdocs.yml).
Cleaned up documentation formatting and added tips/warnings.
Updated Makefile to align with MkDocs.
Fixed Tables in README.md
Added feature: open external links in new tab with noopener noreferrer
Updated # Version to ## Version in Changelog.md
Added permalinks
Added site_description, site_author, site_name in mkdocs.yml
Added feature: show root heading
Converted all docstrings of countries, financial, holiday_base, utils, mixins files manually to Google-style
Removed the previous, next buttons under the toc
Added scripts to generate the nav for mkdocs-literate-nav to list all the countries and financial files
Removed deprecated functions and those starting with underscores
Included the documentation for undocumented members as well
Changed documentation member order to source for consistency

Type of change

New country/market holidays support (thank you!)
Supported country/market holidays update (calendar discrepancy fix, localization)
Existing code/documentation/test/process quality improvement (best practice, cleanup, refactoring, optimization)
Dependency update (version deprecation/pin/upgrade)
Bugfix (non-breaking change which fixes an issue)
Breaking change (a code change causing existing functionality to break)
New feature (new holidays functionality in general)

Checklist

I've followed the contributing guidelines
I've successfully run make check, all checks and tests are green

…oc and deleted the md ones

…index.md, examples.md, CONTRIBUTING.md

KJhellico · 2025-02-14T15:11:07Z

@Roshan-1024, use merge instead of rebase next time, please.

codecov · 2025-02-14T15:25:49Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (1a81d99) to head (151809c).
Report is 1 commits behind head on dev.

Additional details and impacted files

@@            Coverage Diff            @@
##               dev     #2289   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          204       204           
  Lines        12853     12853           
  Branches      1817      1817           
=========================================
  Hits         12853     12853

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Roshan-1024 · 2025-02-15T03:50:52Z

okay

…les.md

coderabbitai

Actionable comments posted: 17

🔭 Outside diff range comments (1)

pyproject.toml (1)
40-40: 🛠️ Refactor suggestion

Update documentation URL

The Documentation URL still points to ReadTheDocs with Sphinx. This should be updated to reflect the new MkDocs location.
-Documentation = "https://holidays.readthedocs.io/en/latest/"
+Documentation = "https://vacanza.github.io/holidays/" # or the appropriate MkDocs URL

♻️ Duplicate comments (3)

holidays/countries/timor_leste.py (1)

32-32: 🧹 Nitpick (assertive)

Remove trailing whitespace on blank line.

There is trailing whitespace on line 32 which should be removed to maintain clean code.
-    
+

docs/js/custom.js (2)

1-119: 🧹 Nitpick (assertive)

Consider adding section comments for better organization.

The JavaScript file handles multiple distinct functionalities. Adding clear section comments would improve maintainability.

document.addEventListener("DOMContentLoaded", () => {

+   // SECTION: External Links Handling
    // Opens external links in a new tab with security attributes
    document.querySelectorAll("a[href]").forEach(link => {
        if (link.hostname !== window.location.hostname) {
            link.setAttribute("target", "_blank");
            link.setAttribute("rel", "noopener noreferrer");
        }
    });

+   // SECTION: File Name Styling
    // Style File Name in the Webpage
    document.querySelectorAll(".doc.doc-object.doc-module").forEach(module => {
        // ... existing code
    });

+   // SECTION: Class Name Handling
    // Append "class" Before Class Names
    document.querySelectorAll(".doc.doc-object.doc-class").forEach(classElem => {
        // ... existing code
    });

+   // SECTION: Class Headers Styling
    // Style Class Headers
    document.querySelectorAll(".doc.doc-object.doc-class").forEach(classElem => {
        // ... existing code
    });

+   // SECTION: Class Contents Styling
    // Style Class Contents
    document.querySelectorAll(".doc.doc-object.doc-class").forEach(classElem => {
        // ... existing code
    });

+   // SECTION: Function Headers Styling
    // Style Function Headers
    document.querySelectorAll(".doc.doc-object.doc-function").forEach(funcElem => {
        // ... existing code
    });
});

28-64: 🧹 Nitpick (assertive)

Consider refactoring repetitive styling code.

The class headers styling section contains repetitive style application logic that could be extracted into a helper function for better maintainability.

+ // Utility function for applying styles
+ function applyStyles(element, styles) {
+     if (!element) return;
+     Object.assign(element.style, styles);
+ }

  // Style Class Headers
  document.querySelectorAll(".doc.doc-object.doc-class").forEach(classElem => {
      const codeElem = classElem.querySelector("h3 code");
      if (!codeElem) return;

      // Style "class" keyword
      const classKeyword = codeElem.querySelector(".class");
-     if (classKeyword) classKeyword.style.color = "#2980b9";
+     if (classKeyword) applyStyles(classKeyword, { color: "#2980b9" });
      
      // Style parameters inside class definition
      ["n", "o", "p", "kc"].forEach(cls => {
          codeElem.querySelectorAll(`.${cls}`).forEach((elem, index) => {
              if (cls === "n" && index === 0) return; // Skip first occurrence (class name)
-             elem.style.color = "#2980b9";
+             applyStyles(elem, { color: "#2980b9" });
          });
      });

      // Ensure class name is black
      const firstParam = codeElem.querySelector(".p");
      if (firstParam) {
          const firstN = codeElem.querySelector(".n");
-         if (firstN) firstN.style.color = "#000";
+         if (firstN) applyStyles(firstN, { color: "#000" });
      } else {
-         codeElem.style.color = "#000";
+         applyStyles(codeElem, { color: "#000" });
      }

      // Set background and border styles for class headers
      const h3Elem = classElem.querySelector("h3");
-     if (h3Elem) {
-         h3Elem.style.borderTop = "3px solid #6ab0de";
-         h3Elem.style.background = "#e7f2fa";
-         h3Elem.style.width = "fit-content";
-         h3Elem.style.paddingRight = "3px";
-     }
+     applyStyles(h3Elem, {
+         borderTop: "3px solid #6ab0de",
+         background: "#e7f2fa",
+         width: "fit-content",
+         paddingRight: "3px"
+     });
-     codeElem.style.background = "#e7f2fa";
-     codeElem.style.border = "none";
+     applyStyles(codeElem, {
+         background: "#e7f2fa",
+         border: "none"
+     });
  });

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 45b6dbc and a8a10b5.

📒 Files selected for processing (174)

.pre-commit-config.yaml (0 hunks)
CHANGES.md (80 hunks)
Makefile (1 hunks)
docs/js/custom.js (1 hunks)
holidays/countries/afghanistan.py (2 hunks)
holidays/countries/albania.py (2 hunks)
holidays/countries/algeria.py (2 hunks)
holidays/countries/american_samoa.py (1 hunks)
holidays/countries/andorra.py (1 hunks)
holidays/countries/angola.py (1 hunks)
holidays/countries/argentina.py (1 hunks)
holidays/countries/armenia.py (1 hunks)
holidays/countries/aruba.py (1 hunks)
holidays/countries/australia.py (1 hunks)
holidays/countries/austria.py (1 hunks)
holidays/countries/azerbaijan.py (3 hunks)
holidays/countries/bahamas.py (1 hunks)
holidays/countries/bahrain.py (2 hunks)
holidays/countries/bangladesh.py (1 hunks)
holidays/countries/barbados.py (1 hunks)
holidays/countries/belarus.py (2 hunks)
holidays/countries/belgium.py (1 hunks)
holidays/countries/belize.py (1 hunks)
holidays/countries/bolivia.py (1 hunks)
holidays/countries/bosnia_and_herzegovina.py (2 hunks)
holidays/countries/botswana.py (1 hunks)
holidays/countries/brazil.py (1 hunks)
holidays/countries/brunei.py (2 hunks)
holidays/countries/bulgaria.py (1 hunks)
holidays/countries/burkina_faso.py (2 hunks)
holidays/countries/burundi.py (2 hunks)
holidays/countries/cambodia.py (1 hunks)
holidays/countries/cameroon.py (2 hunks)
holidays/countries/canada.py (1 hunks)
holidays/countries/chad.py (2 hunks)
holidays/countries/chile.py (1 hunks)
holidays/countries/china.py (1 hunks)
holidays/countries/colombia.py (1 hunks)
holidays/countries/congo.py (1 hunks)
holidays/countries/costa_rica.py (1 hunks)
holidays/countries/croatia.py (1 hunks)
holidays/countries/cuba.py (1 hunks)
holidays/countries/curacao.py (1 hunks)
holidays/countries/cyprus.py (1 hunks)
holidays/countries/czechia.py (1 hunks)
holidays/countries/denmark.py (1 hunks)
holidays/countries/djibouti.py (2 hunks)
holidays/countries/dominica.py (2 hunks)
holidays/countries/dominican_republic.py (1 hunks)
holidays/countries/ecuador.py (1 hunks)
holidays/countries/egypt.py (2 hunks)
holidays/countries/el_salvador.py (1 hunks)
holidays/countries/estonia.py (1 hunks)
holidays/countries/eswatini.py (1 hunks)
holidays/countries/ethiopia.py (2 hunks)
holidays/countries/finland.py (1 hunks)
holidays/countries/france.py (1 hunks)
holidays/countries/gabon.py (2 hunks)
holidays/countries/georgia.py (2 hunks)
holidays/countries/germany.py (2 hunks)
holidays/countries/ghana.py (2 hunks)
holidays/countries/greece.py (1 hunks)
holidays/countries/greenland.py (1 hunks)
holidays/countries/guam.py (1 hunks)
holidays/countries/guatemala.py (1 hunks)
holidays/countries/guernsey.py (2 hunks)
holidays/countries/haiti.py (1 hunks)
holidays/countries/honduras.py (2 hunks)
holidays/countries/hongkong.py (1 hunks)
holidays/countries/hungary.py (2 hunks)
holidays/countries/iceland.py (1 hunks)
holidays/countries/india.py (2 hunks)
holidays/countries/indonesia.py (3 hunks)
holidays/countries/iran.py (2 hunks)
holidays/countries/ireland.py (1 hunks)
holidays/countries/isle_of_man.py (1 hunks)
holidays/countries/israel.py (1 hunks)
holidays/countries/italy.py (1 hunks)
holidays/countries/jamaica.py (1 hunks)
holidays/countries/japan.py (1 hunks)
holidays/countries/jersey.py (2 hunks)
holidays/countries/jordan.py (2 hunks)
holidays/countries/kazakhstan.py (3 hunks)
holidays/countries/kenya.py (3 hunks)
holidays/countries/kuwait.py (2 hunks)
holidays/countries/kyrgyzstan.py (1 hunks)
holidays/countries/laos.py (1 hunks)
holidays/countries/latvia.py (1 hunks)
holidays/countries/lesotho.py (1 hunks)
holidays/countries/liechtenstein.py (1 hunks)
holidays/countries/lithuania.py (1 hunks)
holidays/countries/luxembourg.py (1 hunks)
holidays/countries/macau.py (2 hunks)
holidays/countries/madagascar.py (1 hunks)
holidays/countries/malawi.py (1 hunks)
holidays/countries/malaysia.py (2 hunks)
holidays/countries/maldives.py (1 hunks)
holidays/countries/malta.py (1 hunks)
holidays/countries/marshall_islands.py (1 hunks)
holidays/countries/mauritania.py (1 hunks)
holidays/countries/mexico.py (1 hunks)
holidays/countries/moldova.py (1 hunks)
holidays/countries/monaco.py (1 hunks)
holidays/countries/montenegro.py (2 hunks)
holidays/countries/morocco.py (2 hunks)
holidays/countries/mozambique.py (1 hunks)
holidays/countries/namibia.py (1 hunks)
holidays/countries/netherlands.py (1 hunks)
holidays/countries/new_zealand.py (1 hunks)
holidays/countries/nicaragua.py (1 hunks)
holidays/countries/nigeria.py (2 hunks)
holidays/countries/north_macedonia.py (1 hunks)
holidays/countries/northern_mariana_islands.py (1 hunks)
holidays/countries/norway.py (1 hunks)
holidays/countries/pakistan.py (1 hunks)
holidays/countries/palau.py (2 hunks)
holidays/countries/panama.py (1 hunks)
holidays/countries/papua_new_guinea.py (2 hunks)
holidays/countries/paraguay.py (1 hunks)
holidays/countries/peru.py (1 hunks)
holidays/countries/philippines.py (2 hunks)
holidays/countries/poland.py (1 hunks)
holidays/countries/portugal.py (1 hunks)
holidays/countries/puerto_rico.py (1 hunks)
holidays/countries/romania.py (1 hunks)
holidays/countries/russia.py (1 hunks)
holidays/countries/saint_kitts_and_nevis.py (2 hunks)
holidays/countries/saint_lucia.py (1 hunks)
holidays/countries/samoa.py (1 hunks)
holidays/countries/san_marino.py (1 hunks)
holidays/countries/saudi_arabia.py (2 hunks)
holidays/countries/serbia.py (1 hunks)
holidays/countries/seychelles.py (2 hunks)
holidays/countries/singapore.py (3 hunks)
holidays/countries/slovakia.py (1 hunks)
holidays/countries/slovenia.py (1 hunks)
holidays/countries/south_africa.py (1 hunks)
holidays/countries/south_korea.py (2 hunks)
holidays/countries/spain.py (2 hunks)
holidays/countries/sri_lanka.py (3 hunks)
holidays/countries/sweden.py (1 hunks)
holidays/countries/switzerland.py (1 hunks)
holidays/countries/taiwan.py (2 hunks)
holidays/countries/tanzania.py (2 hunks)
holidays/countries/thailand.py (2 hunks)
holidays/countries/timor_leste.py (2 hunks)
holidays/countries/tonga.py (2 hunks)
holidays/countries/tunisia.py (1 hunks)
holidays/countries/turkey.py (2 hunks)
holidays/countries/tuvalu.py (1 hunks)
holidays/countries/ukraine.py (2 hunks)
holidays/countries/united_arab_emirates.py (3 hunks)
holidays/countries/united_kingdom.py (1 hunks)
holidays/countries/united_states.py (1 hunks)
holidays/countries/united_states_minor_outlying_islands.py (1 hunks)
holidays/countries/united_states_virgin_islands.py (1 hunks)
holidays/countries/uruguay.py (1 hunks)
holidays/countries/uzbekistan.py (2 hunks)
holidays/countries/vanuatu.py (1 hunks)
holidays/countries/vatican_city.py (1 hunks)
holidays/countries/venezuela.py (1 hunks)
holidays/countries/vietnam.py (2 hunks)
holidays/countries/zambia.py (1 hunks)
holidays/countries/zimbabwe.py (1 hunks)
holidays/holiday_base.py (18 hunks)
holidays/mixins.py (1 hunks)
holidays/utils.py (7 hunks)
mkdocs.yml (1 hunks)
pyproject.toml (2 hunks)
requirements/docs.txt (1 hunks)
scripts/docs/gen_changelog.py (1 hunks)
scripts/docs/gen_copyright.py (1 hunks)
scripts/docs/gen_ref_pages.py (1 hunks)
scripts/docs/gen_summary.py (1 hunks)

💤 Files with no reviewable changes (1)

.pre-commit-config.yaml

🧰 Additional context used

🧬 Code Definitions (4)

scripts/docs/gen_copyright.py (3)

scripts/docs/gen_changelog.py (1)

main (20-28)

scripts/docs/gen_ref_pages.py (1)

main (20-33)

scripts/docs/gen_summary.py (1)

main (20-44)

scripts/docs/gen_ref_pages.py (3)

scripts/docs/gen_changelog.py (1)

main (20-28)

scripts/docs/gen_copyright.py (1)

main (20-34)

scripts/docs/gen_summary.py (1)

main (20-44)

holidays/utils.py (1)

holidays/registry.py (3)

EntityLoader (203-297)

get_country_codes (270-276)

get_financial_codes (279-285)

scripts/docs/gen_summary.py (3)

scripts/docs/gen_changelog.py (1)

main (20-28)

scripts/docs/gen_copyright.py (1)

main (20-34)

scripts/docs/gen_ref_pages.py (1)

main (20-33)

🪛 markdownlint-cli2 (0.17.2)

CHANGES.md

19-19: Multiple top-level headings in the same document
null