fix: pydata theme for documentation

* Adds pydata theme, same config as for the landing page * Restructured folders, to have shorter names * Modifies Sphinx-Needs layout and representation * Minor layout fixes Issue-ref: resolves eclipse-score#42
useblocks · Dec 9, 2024 · 5dbbe7e · 5dbbe7e
1 parent 3670d55
commit 5dbbe7e
Show file tree

Hide file tree

Showing 17 changed files with 432 additions and 20 deletions.
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,16 +43,13 @@ sphinx_docs(
 
 sphinx_build_binary(
     name = "sphinx_build",
-    deps = [
-        ":extensions",
-        requirement("sphinx"),
-        requirement("sphinx-needs"),
-    ],
+    deps = [":extensions"] + all_requirements,
 )
 
 py_library(
     name = "extensions",
     srcs = [
+        "_extensions/layouts.py",
         "_extensions/metamodel.py",
     ],
     imports = ["."],

diff --git a/docs/_assets/css/score.css b/docs/_assets/css/score.css
@@ -0,0 +1,188 @@
+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;
+    --pst-color-table-row-zebra-high-bg: #e6e7e8;
+    --pst-color-table-row-hover-bg: var(--pst-color-secondary); /*#d7d6d6;*/
+}
+
+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;
+    --pst-color-table-row-zebra-high-bg: #20242b;
+    --pst-color-table-row-hover-bg: var(--pst-color-secondary); /*#30353e;*/
+}
+
+.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);
+}
+
+ul.navbar-nav li a {
+    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;
+}
+
+/* Left sidebar links */
+nav.bd-links li > a {
+    color: var(--pst-color-text-base);
+}
+
+/* Breadcrumbs, above page content: Link color */
+ul.bd-breadcrumbs li.breadcrumb-item a {
+    color: var(--pst-color-text-base);
+    text-decoration: none;
+}
+
+/* Breadcrumbs, above page content: Arrow color */
+ul.bd-breadcrumbs li.breadcrumb-item:not(.breadcrumb-home)::before {
+    color: var(--pst-color-text-base);
+}
+
+blockquote {
+    color: var(--pst-color-text-base);
+}
+
+.admonition, div.admonition {
+    background-color: rgba(0,0,0,0.1);
+
+/* 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/_assets/css/score_needs.css b/docs/_assets/css/score_needs.css
@@ -0,0 +1,72 @@
+/* ######################### */
+/* NEED TYPE specific config */
+/* ######################### */
+
+/* Stakeholder requirement */
+table.needs_type_stkh_req > tbody > tr.head > td {
+    border-bottom: 3px solid rgb(124, 0, 0) !important;
+}
+
+/* Tool requirement */
+table.needs_type_tool_req > tbody > tr.head > td {
+    border-bottom: 3px solid rgb(6, 70, 139) !important;
+}
+
+/* ######################### */
+/* Common NEED configs       */
+/* ######################### */
+
+/* All need table cells */
+table.need.need.need > tbody > tr > td {
+    padding: 0.7em 1.25em;
+}
+
+td.head_left,
+td.footer_left {
+    vertical-align: middle;
+    width: 70%;
+}
+
+td.head_center,
+td.footer {
+    width: 25%;
+    line-height: 100%;
+    vertical-align: middle;
+}
+
+td.head_right,
+td.footer_right {
+    width: 5%;
+    line-height: 100%;
+    vertical-align: middle;
+}
+
+/* left head -> title area */
+.needs_head_left {
+    font-size: 1.2em;
+    font-weight: 900;
+}
+
+/* center head -> status, security area */
+.needs_head {
+    font-size: 0.8em;
+}
+
+/* Common fixes for Need tables in pydata theme */
+/* .table tbody tr:nth-child(2n),
+.table tbody tr:nth-child(2n+1) {
+    background-color: var(--pst-color-table-row-zebra-low-bg);
+} */
+
+html[data-theme="dark"] {
+    --sn-color-need-bg-head: #20242b;
+}
+
+/* No hover effect (same color) for need objects */
+.table.need tbody tr:nth-child(2n+1):hover {
+    background-color: var(--pst-color-table-row-zebra-low-bg);
+}
+.table.need tbody tr:nth-child(2n):hover {
+    background-color: var(--pst-color-table-row-zebra-high-bg);
+}
+
diff --git a/docs/_extensions/layouts.py b/docs/_extensions/layouts.py
@@ -0,0 +1,41 @@
+# *******************************************************************************
+# 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
+# *******************************************************************************
+
+needs_layouts = {
+    "score": {
+        "grid": "complex",
+        "layout": {
+            "head_left": [
+                '<<meta("title")>>',
+            ],
+            "head": [
+                'status: **<<meta("status")>>**',
+                'security: **<<meta("security")>>**',
+                'safety: **<<meta("safety")>>**',
+            ],
+            "head_right": [
+                '<<collapse_button("meta",collapsed="icon:arrow-down-circle", visible="icon:arrow-right-circle", initial=False)>> '
+            ],
+            "meta_left": [
+                '<<meta_all(no_links=True, exclude=["layout","style"])>>',
+                "<<meta_links_all()>>",
+            ],
+            "meta_right": [],
+            "footer_left": ["<<meta_id()>>"],
+            "footer": ['<<meta("type_name")>>'],
+            "footer_right": [],
+        },
+    },
+}
+
+needs_global_options = {"layout": "score"}