fix: pydata theme colors

Issue-ref: see eclipse-score#7 * Uses pyData Sphinx theme * Changes default theme colors * Add How to get involved page * Small fix for the github CI docs build
useblocks · Dec 6, 2024 · 539ff7d · 539ff7d
1 parent d05cb3e
commit 539ff7d
Show file tree

Hide file tree

Showing 9 changed files with 345 additions and 13 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -38,7 +38,7 @@ jobs:
           retention-days: 1
           if-no-files-found: error
       - name: Comment artifact URL
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false
         run: |
           gh pr comment ${{ github.event.pull_request.number }} \
             --body "Documentation artifact: ${{ steps.upload-artifact-pr.outputs.artifact-url }}"

diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,12 @@ MODULE.bazel.lock
 
 # Ruff
 .ruff_cache
+
+# Python
+.venv/
+
+# Environments
+.envrc
+
+# Sphinx builds
+_build/
diff --git a/docs/BUILD b/docs/BUILD
@@ -11,7 +11,7 @@
 # SPDX-License-Identifier: Apache-2.0
 # *******************************************************************************
 
-load("@pip_sphinx//:requirements.bzl", "requirement")
+load("@pip_sphinx//:requirements.bzl", "all_requirements", "requirement")
 load("@rules_pkg//pkg:mappings.bzl", "pkg_files")
 load("@rules_pkg//pkg:tar.bzl", "pkg_tar")
 load("@rules_python//python:defs.bzl", "py_library")
@@ -25,6 +25,7 @@ sphinx_docs(
         "**/*.svg",
         "**/*.rst",
         "**/*.html",
+        "**/*.css",
     ]),
     config = ":conf.py",
     extra_opts = [
@@ -42,9 +43,7 @@ sphinx_docs(
 
 sphinx_build_binary(
     name = "sphinx_build",
-    deps = [
-        requirement("sphinx"),
-    ],
+    deps = all_requirements,
 )
 
 compile_pip_requirements(

diff --git a/docs/_assets/css/score.css b/docs/_assets/css/score.css
@@ -0,0 +1,156 @@
+html {
+    --pst-font-size-base: 17px;
+}
+
+.underline {
+    text-decoration: underline;
+}
+
+/*  SCORE specfic colors 
+    A list of available colro variable names for pyData Sphinx Theme can be found at
+    https://pydata-sphinx-theme.readthedocs.io/en/stable/_downloads/565fbb3ecf2b3048f5fb3953890ba176/_color.scss 
+    
+    The base color is TEAL */
+
+
+html[data-theme="light"] {
+    --pst-color-primary: #547980;
+    --pst-color-secondary: #45ADA8;
+    --pst-color-accent: #9DE0AD;
+    --pst-color-target: #E5FCC2;
+    --pst-color-on-surface: #594F4F;
+    --pst-color-on-background: var(--pst-color-secondary);
+    --pst-color-text-muted: #FFFFFF;
+}
+
+html[data-theme="dark"] {
+    --pst-color-primary: #45ADA8;
+    --pst-color-secondary: #547980;
+    --pst-color-accent: #9DE0AD;
+    --pst-color-target: #E5FCC2;
+    --pst-color-on-surface: #594F4F;
+    --pst-color-on-background: var(--pst-color-secondary);
+    --pst-color-text-muted: #FFFFFF;
+}
+
+.search-button-field {
+    color: var(--pst-color-primary);
+}
+html .pst-navbar-icon:hover {
+    border-bottom: max(3px,.1875rem,.12em) solid var(--pst-color-primary) !important;
+    color: var(--pst-color-primary) !important;
+  }
+
+.bd-header ul.navbar-nav > li.nav-item.current > .nav-link {
+    color: var(--pst-color-text-muted) !important;
+    font-weight: 900 !important;
+}
+
+.bd-header ul.navbar-nav > li.nav-item > .nav-link:hover {
+    color: var(--pst-color-primary);
+  }
+
+.bd-search input.form-control::placeholder,
+.bd-search input.form-control {
+    color: var(--pst-color-primary) !important;
+}
+
+/* Right sidebar */
+.toc-entry a.nav-link {
+    color: var(--pst-color-text-base);
+}
+/* Left, top SCORE brand  */
+.navbar-brand p
+{
+    color: var(--pst-color-text-muted);
+    font-weight: 900;
+}
+.navbar-brand:hover, .navbar-brand:visited:hover {
+    text-decoration: none;
+}
+
+/* GitHub logo for shorten URL  */
+a.github::before {
+    content: var(--pst-icon-github);
+    color: var(--pst-color-text-base);
+}
+a.github {
+    text-decoration: none !important;
+}
+
+/* SCORE Background video
+   Source: https://www.imi21.com/background-video-full-screen.php */
+
+div.score_banner {
+    background-color: var(--pst-color-on-surface);
+}
+#videowrapper{  
+    position: relative;
+    overflow: hidden;
+} 
+
+#fullScreenDiv{
+    height: 300px;
+    width: 100%;
+    padding:0;
+    margin: 0;
+    /* background-color: gray;
+    position: relative; */
+    container-type: inline-size;
+}
+
+#video{    
+    width: 100%; 
+    /* height: auto;
+    margin: auto;
+    display: block; */
+}
+@media (min-aspect-ratio: 16/9) {
+  #video{
+    width: 100%; 
+    height:auto;
+  }
+}
+
+#score-title {
+    width: 100%; 
+    height: 100%;
+    position: absolute; 
+    top: 0; 
+    left: 0;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    flex-direction: column;
+    color: var(--pst-color-text-base);
+    /* font-size: 4.5em; */
+    font-size: 8.0cqw;
+    font-weight: 900;
+
+    /* Is somehow cool with image/video title background */
+    /*animation: fadeIn 3s;  */
+}
+
+/* As long as no image or video is shown in
+   the title, this is not needed, but kept 
+   for future needs */
+/* html[data-theme="light"] #score-title {
+    background-color: rgba(0,0,0,0.3);
+}
+html[data-theme="dark"] #score-title {
+    background-color: rgba(0,0,0,0.5);
+} */
+
+#score-subtitle {
+    font-size: 0.4em;
+}
+
+#score-phrase {
+    font-size: 0.3em;
+    font-weight: 400;
+}
+
+@keyframes fadeIn {
+    0% { opacity: 0; }
+    100% { opacity: 1; }
+  }
diff --git a/docs/conf.py b/docs/conf.py
@@ -34,5 +34,45 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "alabaster"
-html_theme_options = {"page_width": "auto", "body_max_width": "1500"}
+html_theme = "pydata_sphinx_theme"  #  "alabaster"
+# html_theme_options = {"page_width": "auto", "body_max_width": "1500"}
+
+html_static_path = ["_assets"]
+html_css_files = [
+    "css/score.css",
+]
+
+html_theme_options = {
+    "external_links": [
+        {"name": "Docs", "url": "https://eclipse-score.github.io/score/"},
+        {
+            "name": "Eclipse",
+            "url": "https://projects.eclipse.org/projects/automotive.score",
+        },
+    ],
+    "icon_links": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/eclipse-score",
+            "icon": "fa-brands fa-github",
+            "type": "fontawesome",
+        }
+    ],
+    "use_edit_page_button": True,  # https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/source-buttons.html#add-an-edit-button
+    "collapse_navigation": True,
+    "logo": {
+        "text": "Eclipse SCORE",
+    },
+}
+
+html_context = {
+    # "github_url": "https://github.com", # or your GitHub Enterprise site
+    "github_user": "eclipse-score",
+    "github_repo": "eclipse-score.github.io",
+    "github_version": "main",
+    "doc_path": "docs",
+}
+
+# Shows no left sidebar for single files
+# Woraround for bug: https://github.com/pydata/pydata-sphinx-theme/issues/1662#issuecomment-1913672649
+html_sidebars = {"get_involved": []}
diff --git a/docs/get_involved.rst b/docs/get_involved.rst
@@ -0,0 +1,73 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2024 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+.. role:: underline
+    :class: underline
+
+Get involved
+============
+
+How to get in contact with SCORE
+--------------------------------
+
+If you want to get into contact with SCORE, these are your primary entry points: 
+
+:Project Mailing List: [email protected]
+
+:Architectural Discussion: `#score-project-open-channel <https://sdvworkinggroup.slack.com/archives/C083Z4VL90B>`__
+
+| **General Information / Alignment regarding SCORE as a basis for distributions & products:** 
+| Contact one of the project leads of SCORE https://projects.eclipse.org/projects/automotive.score/who
+
+The technical HOWTO regarding involvement into SCORE is described here: 
+https://github.com/eclipse-score/score/blob/main/CONTRIBUTION.md
+
+How to get involved into SCORE
+------------------------------
+
+The :underline:`only` way to influence SCORE is TO CONTRIBUTE. Everybody can contribute – SCORE is open.
+
+Active Contributions to the SCORE project are the basis for getting involved. The SCORE Project works according to 
+the Eclipse Project Handbook and has named and elected project leads and committers (see https://projects.eclipse.org/projects/automotive.score/who). 
+Direction of the SCORE project is discussed and decided in the project lead circle, technical direction is created and prediscussed in the tech 
+lead circle. Meeting notes are transparent via the SCORE github organization. (see https://github.com/orgs/eclipse-score/discussions)
+
+We aim to build a safety ready full stack architecture, where components fit to each other in 
+automotive grade Software Quality and performance. To achieve this, we follow a strict feature roadmap and architecture
+and a rigid software development process (publicly available in the SCORE Project Handbook starting end of 2024). 
+
+Contributions to the SCORE project must therefore follow the technical direction of the project and the SCORE 
+architecture. All work in SCORE will therefore follow a "Contribution Request" Process. Features on the roadmap of 
+SCORE are defined, Contribution Requests create the basis for individual contributions from within the SCORE 
+project and also from the outside.
+
+You can make proposals for new features or architectural building blocks besides the active contribution requests. 
+Those will not by default be part of the next release of SCORE, because the SCORE release roadmap will strictly 
+comply with the contribution request structure. 
+We plan to have the initial contribution request structure available in the SCORE GitHub until Q1 / 2025.
+
+We plan to incorporate a staging area for such contributions, but
+in the initial phase of the SCORE project (until end of 2025) the focus will be primarily on building a valid 1.0 
+release. Feel free to reach out via the communication channels above.
+
+If you think about your contribution to SCORE, the Contribution Request overview
+is the best place to start (available on https://github.com/eclipse-score/score/issues starting Q1 / 2025)
+
+Based on successful code contributions to the SCORE roadmap, further steps in involvement (like becoming a committer) 
+will be handled according to the rules of the Eclipse Foundation Project Handbook. We value real code based 
+collaboration and will judge new potential contributors and committers mainly on the validity of their work. Active 
+and sustaining contributions are the basis for the ability to shape SCORE.
+
+Making active code contributions via the contribution request process described in the Project Handbook. The 
+project handbook will be available on the SCORE website until end of 2024.
diff --git a/docs/index.rst b/docs/index.rst
@@ -12,9 +12,35 @@
    # SPDX-License-Identifier: Apache-2.0
    # *******************************************************************************
 
+.. raw:: html
+
+   <div style="visibility: hidden;height:0px;">
+
 SCORE (Eclipse Safe Open Vehicle Core)
 ######################################
 
+.. raw:: html
+
+   </div>
+
+.. toctree::
+   :hidden:
+
+   get_involved
+
+.. raw:: html
+
+   <div id="videowrapper">
+      <div id="fullScreenDiv">
+         <div id="score-title"> 
+               Eclipse SCORE
+               <span id="score-subtitle">Eclipse Safe Open Vehicle Core</span>
+               <span id="score-phrase">BUILD THE BEST AUTOMOTIVE RUNTIME SOLUTION ONLY ONCE</span>
+         </div>   
+      </div>
+   </div>
+
+
 Background
 **********
 
@@ -118,9 +144,9 @@ Roadmap
 
 Here you can find the preliminary roadmap of the project:
 
-  .. image:: _assets/score_roadmap.svg
-     :alt: project roadmap
-     :align: center
+.. image:: _assets/score_roadmap.svg
+   :alt: project roadmap
+   :align: center
 
 
 Please be aware, that this roadmap will be also transfered to the `GitHub project <https://github.com/orgs/eclipse-score/projects/1>`_.

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -2,3 +2,4 @@
 
 Sphinx==8.1.3
 sphinx-needs==4.1.0
+pydata-sphinx-theme==0.16.0
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2,3 +2,4 @@

		Sphinx==8.1.3
		sphinx-needs==4.1.0
		pydata-sphinx-theme==0.16.0