diff --git a/docs/BUILD b/docs/BUILD index d793fee..426c075 100644 --- 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 new file mode 100644 index 0000000..fd8e562 --- /dev/null +++ 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 new file mode 100644 index 0000000..8ab71c0 --- /dev/null +++ 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 new file mode 100644 index 0000000..7c58c4f --- /dev/null +++ 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": [ + '<>', + ], + "head": [ + 'status: **<>**', + 'security: **<>**', + 'safety: **<>**', + ], + "head_right": [ + '<> ' + ], + "meta_left": [ + '<>', + "<>", + ], + "meta_right": [], + "footer_left": ["<>"], + "footer": ['<>'], + "footer_right": [], + }, + }, +} + +needs_global_options = {"layout": "score"} diff --git a/docs/conf.py b/docs/conf.py index f61fd63..15dfdd6 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,7 +17,8 @@ # https://www.sphinx-doc.org/en/master/usage/configuration.html # from process.process_model_configuration import * -from _extensions import metamodel +from _extensions import metamodel, layouts + # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -44,7 +45,44 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = "alabaster" +html_theme = "pydata_sphinx_theme" # "alabaster" +html_static_path = ["_assets"] +html_css_files = [ + "css/score.css", + "css/score_needs.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 Docs", + }, +} + +html_context = { + # "github_url": "https://github.com", # or your GitHub Enterprise site + "github_user": "eclipse-score", + "github_repo": "score", + "github_version": "main", + "doc_path": "docs", +} + # -- sphinx-needs configuration -------------------------------------------- @@ -52,6 +90,12 @@ needs_extra_options = metamodel.needs_extra_options needs_extra_links = metamodel.needs_extra_links +# Setting the needs layouts +needs_layouts = layouts.needs_layouts +needs_global_options = {"collapse": True} +needs_global_options = needs_global_options | layouts.needs_global_options + + # sphinx_needs configuration needs_id_required = True needs_id_regex = "^[A-Za-z0-9_-]{6,}" diff --git a/docs/features/index.rst b/docs/features/index.rst index 058c2fc..d93cf7d 100644 --- a/docs/features/index.rst +++ b/docs/features/index.rst @@ -12,8 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* -Feature documentation -===================== +Features +======== .. toctree:: :maxdepth: 1 diff --git a/docs/index.rst b/docs/index.rst index 027268d..bb9c038 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,14 +12,33 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* +.. raw:: html + + + Documentation ============= +.. raw:: html + + + +.. raw:: html + + + + + Eclipse SCORE + Eclipse Safe Open Vehicle Core + Software Documentation + + + + .. toctree:: - :maxdepth: 1 + :maxdepth: 2 :glob: - stakeholder_requirements/index.rst - tool_requirements/index.rst - process_description/index.rst - features/index.rst + requirements/index + features/index + process/index diff --git a/docs/process_description/guidelines/branch/index.rst b/docs/process/guidelines/branch/index.rst similarity index 100% rename from docs/process_description/guidelines/branch/index.rst rename to docs/process/guidelines/branch/index.rst diff --git a/docs/process_description/guidelines/git/index.rst b/docs/process/guidelines/git/index.rst similarity index 100% rename from docs/process_description/guidelines/git/index.rst rename to docs/process/guidelines/git/index.rst diff --git a/docs/process_description/guidelines/index.rst b/docs/process/guidelines/index.rst similarity index 100% rename from docs/process_description/guidelines/index.rst rename to docs/process/guidelines/index.rst diff --git a/docs/process_description/index.rst b/docs/process/index.rst similarity index 97% rename from docs/process_description/index.rst rename to docs/process/index.rst index 5608c2a..a92958c 100644 --- a/docs/process_description/index.rst +++ b/docs/process/index.rst @@ -14,8 +14,8 @@ .. _Process_description: -Process description -=================== +Process +======= Processes are the basis to describe the way of working within the SCORE project. diff --git a/docs/process_description/templates/index.rst b/docs/process/templates/index.rst similarity index 100% rename from docs/process_description/templates/index.rst rename to docs/process/templates/index.rst diff --git a/docs/requirements.txt b/docs/requirements.txt index 91fbf5d..3e5cf07 100644 --- 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 diff --git a/docs/requirements/index.rst b/docs/requirements/index.rst new file mode 100644 index 0000000..fe06ad6 --- /dev/null +++ b/docs/requirements/index.rst @@ -0,0 +1,21 @@ +.. + # ******************************************************************************* + # 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 + # ******************************************************************************* + +Requirements +============ + +.. toctree:: + + stakeholder/index + tool/index \ No newline at end of file diff --git a/docs/stakeholder_requirements/index.rst b/docs/requirements/stakeholder/index.rst similarity index 100% rename from docs/stakeholder_requirements/index.rst rename to docs/requirements/stakeholder/index.rst diff --git a/docs/tool_requirements/index.rst b/docs/requirements/tool/index.rst similarity index 100% rename from docs/tool_requirements/index.rst rename to docs/requirements/tool/index.rst diff --git a/docs/requirements_lock.txt b/docs/requirements_lock.txt index 7d8cb87..8493462 100644 --- a/docs/requirements_lock.txt +++ b/docs/requirements_lock.txt @@ -6,6 +6,10 @@ # --extra-index-url https://pypi.org/simple/ +accessible-pygments==0.0.5 \ + --hash=sha256:40918d3e6a2b619ad424cb91e556bd3bd8865443d9f22f1dcdf79e33c8046872 \ + --hash=sha256:88ae3211e68a1d0b011504b2ffc1691feafce124b845bd072ab6f9f66f34d4b7 + # via pydata-sphinx-theme alabaster==0.7.16 \ --hash=sha256:75a8b99c28a5dad50dd7f8ccdd447a121ddb3892da9e53d1ca5cca3106d58d65 \ --hash=sha256:b46733c07dce03ae4e150330b975c75737fa60f0a7c591b6c8bf4928a28e2c92 @@ -19,7 +23,13 @@ attrs==24.2.0 \ babel==2.15.0 \ --hash=sha256:08706bdad8d0a3413266ab61bd6c34d0c28d6e1e7badf40a2cebe67644e2e1fb \ --hash=sha256:8daf0e265d05768bc6c7a314cf1321e9a123afc328cc635c18622a2f30a04413 - # via sphinx + # via + # pydata-sphinx-theme + # sphinx +beautifulsoup4==4.12.3 \ + --hash=sha256:74e3d1928edc070d21748185c46e3fb33490f22f52a3addee9aee0f4f7781051 \ + --hash=sha256:b80878c9f40111313e55da8ba20bdba06d8fa3969fc68304167741bbf9e082ed + # via pydata-sphinx-theme certifi==2024.7.4 \ --hash=sha256:5a1e7645bc0ec61a09e26c36f6106dd4cf40c6db3a1fb6352b0244e7fb057c7b \ --hash=sha256:c198e21b1289c2ab85ee4e67bb4b4ef3ead0892059901a8d5b622f24a1101e90 @@ -119,7 +129,9 @@ charset-normalizer==3.3.2 \ docutils==0.20.1 \ --hash=sha256:96f387a2c5562db4476f09f13bbab2192e764cac08ebbf3a34a95d9b1e4a59d6 \ --hash=sha256:f08a4e276c3a1583a86dce3e34aba3fe04d02bba2dd51ed16106244e8a923e3b - # via sphinx + # via + # pydata-sphinx-theme + # sphinx idna==3.7 \ --hash=sha256:028ff3aadf0609c1fd278d8ea3089299412a7a8b9bd005dd08b9f8285bcb5cfc \ --hash=sha256:82fee1fc78add43492d3a1898bfa6d8a904cc97d8427f683ed8e798d07761aa0 @@ -206,10 +218,17 @@ packaging==24.1 \ --hash=sha256:026ed72c8ed3fcce5bf8950572258698927fd1dbda10a5e981cdf0ac37f4f002 \ --hash=sha256:5b8f2217dbdbd2f7f384c41c628544e6d52f2d0f53c6d0c3ea61aa5d1d7ff124 # via sphinx +pydata-sphinx-theme==0.16.0 \ + --hash=sha256:18c810ee4e67e05281e371e156c1fb5bb0fa1f2747240461b225272f7d8d57d8 \ + --hash=sha256:721dd26e05fa8b992d66ef545536e6cbe0110afb9865820a08894af1ad6f7707 + # via -r docs/requirements.txt pygments==2.18.0 \ --hash=sha256:786ff802f32e91311bff3889f6e9a86e81505fe99f2735bb6d60ae0c5004f199 \ --hash=sha256:b8e6aca0523f3ab76fee51799c488e38782ac06eafcf95e7ba832985c8e7b13a - # via sphinx + # via + # accessible-pygments + # pydata-sphinx-theme + # sphinx referencing==0.35.1 \ --hash=sha256:25b42124a6c8b632a425174f24087783efb348a6f1e0008e63cd4466fedf703c \ --hash=sha256:eda6d3234d62814d1c64e305c1331c9a3a6132da475ab6382eaa997b21ee75de @@ -325,11 +344,16 @@ snowballstemmer==2.2.0 \ --hash=sha256:09b16deb8547d3412ad7b590689584cd0fe25ec8db3be37788be3810cbf19cb1 \ --hash=sha256:c8e1716e83cc398ae16824e5572ae04e0d9fc2c6b985fb0f900f5f0c96ecba1a # via sphinx +soupsieve==2.6 \ + --hash=sha256:e2e68417777af359ec65daac1057404a3c8a5455bb8abc36f1a9866ab1a51abb \ + --hash=sha256:e72c4ff06e4fb6e4b5a9f0f55fe6e81514581fca1515028625d0f299c602ccc9 + # via beautifulsoup4 sphinx==8.1.3 \ --hash=sha256:09719015511837b76bf6e03e42eb7595ac8c2e41eeb9c29c5b755c6b677992a2 \ --hash=sha256:43c1911eecb0d3e161ad78611bc905d1ad0e523e4ddc202a58a821773dc4c927 # via # -r docs/requirements.txt + # pydata-sphinx-theme # sphinx-data-viewer # sphinx-needs # sphinxcontrib-jquery @@ -369,6 +393,10 @@ sphinxcontrib-serializinghtml==1.1.10 \ --hash=sha256:326369b8df80a7d2d8d7f99aa5ac577f51ea51556ed974e7716cfd4fca3f6cb7 \ --hash=sha256:93f3f5dc458b91b192fe10c397e324f262cf163d79f3282c158e8436a2c4511f # via sphinx +typing-extensions==4.12.2 \ + --hash=sha256:04e5ca0351e0f3f85c6853954072df659d0d13fac324d0072316b67d7794700d \ + --hash=sha256:1a7ead55c7e559dd4dee8856e3a88b41225abfe1ce8df57b7c13915fe121ffb8 + # via pydata-sphinx-theme urllib3==2.2.2 \ --hash=sha256:a448b2f64d686155468037e1ace9f2d2199776e17f0a46610480d311f73e3472 \ --hash=sha256:dd505485549a7a552833da5e6063639d0d177c04f23bc3864e41e5dc5f612168