scikit-learn · ogrisel · Feb 22, 2024 · Feb 1, 2024 · Feb 1, 2024 · Feb 1, 2024
diff --git a/doc/conf.py b/doc/conf.py
@@ -64,7 +64,6 @@
     "sphinx_remove_toctrees",
     "sphinx_design",
     # See sphinxext/
-    "add_toctree_functions",
     "allow_nan_estimators",
     "doi_role",
     "move_gallery_links",
@@ -315,9 +314,7 @@
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
-# TODO: change to html_additional_pages = {"index": "index.html"} so that our landing
-# page template can override the one generated from index.rst
-html_additional_pages = {}
+html_additional_pages = {"index": "index.html"}
 
 # Additional JS files
 html_js_files = ["scripts/details-permalink.js"]
@@ -340,7 +337,9 @@ def add_js_css_files(app, pagename, templatename, context, doctree):
     should be used for the ones that are used by multiple pages. All page-specific
     JS and CSS files should be added here instead.
     """
-    if pagename == "install":
+    if pagename == "index":
+        app.add_css_file("styles/index.css")
+    elif pagename == "install":
         app.add_css_file("styles/install.css")
 
 
@@ -740,7 +739,7 @@ def filter_search_index(app, exception):
         f.write(searchindex_text)
 
 
-def generate_min_dependency_table(app):
+def generate_min_dependency_table():
     """Generate min dependency table for docs."""
     from sklearn._min_dependencies import dependent_packages
 
@@ -786,11 +785,11 @@ def generate_min_dependency_table(app):
     output.write("\n")
     output = output.getvalue()
 
-    with (Path(".") / "min_dependency_table.rst").open("w") as f:
+    with (Path(".") / "min_dependency_table.rst").open("w", encoding="utf-8") as f:
         f.write(output)
 
 
-def generate_min_dependency_substitutions(app):
+def generate_min_dependency_substitutions():
     """Generate min dependency substitutions for docs."""
     from sklearn._min_dependencies import dependent_packages
 
@@ -803,7 +802,55 @@ def generate_min_dependency_substitutions(app):
 
     output = output.getvalue()
 
-    with (Path(".") / "min_dependency_substitutions.rst").open("w") as f:
+    with (Path(".") / "min_dependency_substitutions.rst").open(
+        "w", encoding="utf-8"
+    ) as f:
+        f.write(output)
+
+
+def generate_index_rst():
+    """Generate index.rst.
+
+    The reason for generating this file at build time is to allow specifying the
+    development link as a variable.
+    https://github.com/scikit-learn/scikit-learn/pull/22550
+    """
+    development_link = (
+        "developers/index"
+        if parsed_version.is_devrelease
+        else "https://scikit-learn.org/dev/developers/index.html"
+    )
+
+    output = f"""
+.. title:: Index
+
+.. Define the overall structure, that affects the prev-next buttons and the order
+   of the sections in the top navbar.
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   Install <install>
+   user_guide
+   API <modules/classes>
+   auto_examples/index
+   Community <https://blog.scikit-learn.org/>
+   getting_started
+   Tutorials <tutorial/index>
+   whats_new
+   Glossary <glossary>
+   Development <{development_link}>
+   FAQ <faq>
+   support
+   related_projects
+   roadmap
+   Governance <governance>
+   about
+   Other Versions and Download <https://scikit-learn.org/dev/versions.html>
+"""
+
+    with (Path(".") / "index.rst").open("w", encoding="utf-8") as f:
         f.write(output)
 
 
@@ -822,8 +869,6 @@ def setup(app):
     # do not run the examples when using linkcheck by using a small priority
     # (default priority is 500 and sphinx-gallery using builder-inited event too)
     app.connect("builder-inited", disable_plot_gallery_for_linkcheck, priority=50)
-    app.connect("builder-inited", generate_min_dependency_table)
-    app.connect("builder-inited", generate_min_dependency_substitutions)
 
     # triggered just before the HTML for an individual page is created
     app.connect("html-page-context", add_js_css_files)
@@ -954,3 +999,8 @@ def setup(app):
     linkcheck_request_headers = {
         "https://github.com/": {"Authorization": f"token {github_token}"},
     }
+
+# Write the pages prior to any sphinx event
+generate_index_rst()
+generate_min_dependency_table()
+generate_min_dependency_substitutions()
diff --git a/doc/index.rst b/doc/index.rst
diff --git a/doc/scss/colors.scss b/doc/scss/colors.scss
@@ -1,6 +1,9 @@
 /**
  * This is the style sheet for customized colors of scikit-learn.
  * Tints and shades are generated by https://colorkit.co/color-shades-generator/
+ *
+ * This file is compiled into styles/colors.css by sphinxcontrib.sass, see:
+ * https://sass-lang.com/guide/
  */
 
 :root {

diff --git a/doc/scss/custom.scss b/doc/scss/custom.scss
@@ -1,6 +1,9 @@
 /**
  * This is a general styling sheet.
  * It should be used for customizations that affect multiple pages.
+ *
+ * This file is compiled into styles/custom.css by sphinxcontrib.sass, see:
+ * https://sass-lang.com/guide/
  */
 
 /* Global */

diff --git a/doc/scss/index.scss b/doc/scss/index.scss
@@ -0,0 +1,175 @@
+/**
+ * Styling sheet for the scikit-learn landing page. This should be loaded only for the
+ * landing page.
+ *
+ * This file is compiled into styles/index.css by sphinxcontrib.sass, see:
+ * https://sass-lang.com/guide/
+ */
+
+/* Theme-aware colors for the landing page */
+
+html {
+  &[data-theme="light"] {
+    --sk-landing-bg-1: var(--sk-cyan-shades-3);
+    --sk-landing-bg-2: var(--sk-cyan);
+    --sk-landing-bg-3: var(--sk-orange-tint-8);
+    --sk-landing-bg-4: var(--sk-orange-tint-3);
+  }
+
+  &[data-theme="dark"] {
+    --sk-landing-bg-1: var(--sk-cyan-shades-5);
+    --sk-landing-bg-2: var(--sk-cyan-shades-2);
+    --sk-landing-bg-3: var(--sk-orange-tint-4);
+    --sk-landing-bg-4: var(--sk-orange-tint-1);
+  }
+}
+
+/* General */
+
+div.sk-landing-container {
+  max-width: 1400px;
+}
+
+/* Top bar */
+
+div.sk-landing-top-bar {
+  background-image: linear-gradient(
+    160deg,
+    var(--sk-landing-bg-1) 0%,
+    var(--sk-landing-bg-2) 17%,
+    var(--sk-landing-bg-3) 59%,
+    var(--sk-landing-bg-4) 100%
+  );
+
+  .sk-landing-header,
+  .sk-landing-subheader {
+    color: white;
+    text-shadow: 0px 0px 8px var(--sk-landing-bg-1);
+  }
+
+  .sk-landing-header {
+    font-size: 3.2rem;
+    margin-bottom: 0.5rem;
+  }
+
+  .sk-landing-subheader {
+    letter-spacing: 0.17rem;
+    margin-top: 0;
+    font-weight: 500;
+  }
+
+  a.sk-btn-orange {
+    font-size: 1.1rem;
+    font-weight: 500;
+  }
+
+  ul.sk-landing-header-body {
+    margin-top: auto;
+    margin-bottom: auto;
+    font-size: 1.2rem;
+    font-weight: 500;
+    color: black;
+  }
+}
+
+/* Body */
+
+div.sk-landing-body {
+  div.card {
+    background-color: var(--pst-color-background);
+    border-color: var(--pst-color-border);
+  }
+
+  .sk-px-xl-4 {
+    @media screen and (min-width: 1200px) {
+      padding-left: 1.3rem !important;
+      padding-right: 1.3rem !important;
+    }
+  }
+
+  .card-body {
+    p {
+      margin-bottom: 0.8rem;
+    }
+
+    .sk-card-title {
+      font-weight: 700;
+      margin: 0 0 1rem 0;
+    }
+  }
+
+  .sk-card-img-container {
+    display: flex;
+    justify-content: center;
+    align-items: end;
+    margin-bottom: 1rem;
+
+    img {
+      max-width: unset;
+      height: 15rem;
+    }
+  }
+}
+
+/* More info */
+
+div.sk-landing-more-info {
+  font-size: 0.96rem;
+  background-color: var(--pst-color-surface);
+
+  .sk-landing-call-header {
+    font-weight: 700;
+    margin-top: 0;
+
+    html[data-theme="light"] & {
+      color: var(--sk-orange-shades-1);
+    }
+
+    html[data-theme="dark"] & {
+      color: var(--sk-orange);
+    }
+  }
+
+  ul.sk-landing-call-list > li {
+    margin-bottom: 0.25rem;
+  }
+
+  .sk-who-uses-carousel {
+    min-height: 200px;
+
+    .carousel-item img {
+      max-height: 100px;
+      max-width: 50%;
+      margin: 0.5rem;
+    }
+  }
+
+  .sk-more-testimonials {
+    text-align: right !important;
+  }
+}
+
+/* Footer */
+
+div.sk-landing-footer {
+  a.sk-footer-funding-link {
+    text-decoration: none;
+
+    p.sk-footer-funding-text {
+      color: var(--pst-color-link);
+
+      &:hover {
+        color: var(--pst-color-secondary);
+      }
+    }
+
+    div.sk-footer-funding-logos > img {
+      max-height: 40px;
+      max-width: 85px;
+      margin: 0 8px 8px 8px;
+      padding: 5px;
+      border-radius: 3px;
+      background-color: white;
+    }
+  }
+}
diff --git a/doc/scss/install.scss b/doc/scss/install.scss
@@ -1,6 +1,9 @@
 /**
  * Styling for the installation page, including overriding some default styling of
  * sphinx-design. This style sheet should be included only for the install page.
+ *
+ * This file is compiled into styles/install.css by sphinxcontrib.sass, see:
+ * https://sass-lang.com/guide/
  */
 
 .install-instructions .sd-tab-set {