Add mkdocs publishing of OSEP site

Signed-off-by: Paul Albertella <[email protected]>
elisa-tech · Oct 28, 2024 · 397bd6d · 397bd6d
1 parent 2f31160
commit 397bd6d
Show file tree

Hide file tree

Showing 14 changed files with 419 additions and 30 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -2,43 +2,38 @@ name: CI
 
 # Controls when the workflow will run
 on:
-  # Triggers the workflow on push or pull request events but only for the main branch
+  # Triggers the workflow on push events for the main branch
   push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
+    branches: [ mkdocs ]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
+# Needs write permission to update the gh-pages branch that is used for GitHub Pages
+permissions:
+  contents: write
+
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
   # This workflow contains a single job called "build"
-  build:
-    # The type of runner that the job will run on
+  # Copied from https://squidfunk.github.io/mkdocs-material/publishing-your-site/
+  deploy:
     runs-on: ubuntu-latest
-
-    env:
-      STPATOOLS_VERSION: "42e07abc5510f5864aa102aa7ae1e8349911a620"
-      STPATOOLS_REPO: "https://gitlab.com/CodethinkLabs/stpatools.git"
-
-    # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-      - uses: actions/checkout@v2
-
-      # Check that YAML files are well-formed
-      - name: YAML lint
-        run: yamllint -d relaxed .
-
-      # Install specific version of ruamel.yaml required by STPAtools
-      - name: Install ruamel.yaml
-        run: pip3 install ruamel.yaml==0.16.7
-
-      # Install specific version of STPA tools from repo
-      - name: Install STPA tools
-        run: pip3 install "git+${{env.STPATOOLS_REPO}}@${{env.STPATOOLS_VERSION}}"
-
-      # Validate STPA files
-      - name: Validate STPA files (STPA_DynMA)
-        run: stpa-validate STPA_DynMA/*.yml
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material mkdocs-material-extensions pymdown-extensions
+      - run: mkdocs gh-deploy --force
diff --git a/docs/CNAME b/docs/CNAME
@@ -0,0 +1 @@
+osep.elisa.tech
diff --git a/docs/images/elisa-horizontal-color.svg b/docs/images/elisa-horizontal-color.svg
diff --git a/docs/images/elisa-logo.svg b/docs/images/elisa-logo.svg
diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,18 @@
+![ELISA - Enabling Linux in Safety Applications](images/elisa-horizontal-color.svg){: .elisa-title-image }
+
+# Welcome to OSEP
+
+This is the home of the **Open Source Engineering Process (OSEP)** working
+group, part of the Linux Foundation's [ELISA](https://elisa.tech/) project
+
+This working group examines how software engineering processes can be used to
+facilitate the certification of safety-related systems incorporating Linux and
+other FOSS. We consider the roles that a Linux-based OS might have in such
+systems; how FOSS developers, system integrators and product creators can
+specify these roles; and the evidence they might need to provide to support
+associated safety arguments.
+
+Use the menu on the left to navigate within the site, and the _Table of
+contents_ on the right to browse within a page. Alternatively, type what you
+are looking for in the _Search_ box above.
+
diff --git a/docs/stylesheets/elisa.css b/docs/stylesheets/elisa.css
@@ -0,0 +1,47 @@
+  :root {
+
+    --elisa-green: #77c046;
+
+    --md-default-fg-color: slategrey;
+    --md-default-bg-color: white;
+
+    --md-primary-fg-color: black;
+    --md-primary-bg-color: var(--elisa-green);
+
+    --md-typeset-a-color: darkgreen;
+    --md-accent-fg-color: var(--elisa-green);
+
+  }
+
+.md-typeset__table {
+  min-width: 100%;
+}
+
+.md-typeset table:not([class]) {
+  display: table;
+  border: none;
+}
+
+td {
+  background-color: #f0f0f0;
+  margin: 2px;
+}
+
+th {
+  background-color: darkgreen;
+  color: var(--elisa-green);
+}
+
+th:first-child {
+  border-top-left-radius: 10px;
+}
+
+th:last-child {
+  border-top-right-radius: 10px;
+}
+
+.elisa-title-image {
+  width: 50%;
+  float: right;
+  padding-left: 10px;
+}
diff --git a/docs/workshops/2021-11-Virtual/Certification-using-the-New-Approach-to-Safety.pdf b/docs/workshops/2021-11-Virtual/Certification-using-the-New-Approach-to-Safety.pdf
diff --git a/docs/workshops/2023-06-Berlin/Safety-Analysis-Approach.pdf b/docs/workshops/2023-06-Berlin/Safety-Analysis-Approach.pdf
diff --git a/...s/2023-10-Munich/A-Systematic-Approach-to-Using-the-Linux-Kernel-in-a-Safety-Scenario.pdf b/...s/2023-10-Munich/A-Systematic-Approach-to-Using-the-Linux-Kernel-in-a-Safety-Scenario.pdf
diff --git a/...0-Munich/Update-on-Planned-Processes-for-Safety-Analysis-and-Documentation-of-Results.pdf b/...0-Munich/Update-on-Planned-Processes-for-Safety-Analysis-and-Documentation-of-Results.pdf
diff --git a/...hops/2024-06-Lund/Overall-engineering-approach-to-safety-with-systems-involving-Linux.pdf b/...hops/2024-06-Lund/Overall-engineering-approach-to-safety-with-systems-involving-Linux.pdf
diff --git a/docs/workshops/index.md b/docs/workshops/index.md
@@ -0,0 +1,27 @@
+# Workshop presentation archive
+
+## June 2024 (Lund)
+
+| Title | Presenter(s) |
+| ----- | ------------ |
+| [Overall engineering approach to safety with systems involving Linux](2024-06-Lund/Overall-engineering-approach-to-safety-with-systems-involving-Linux.pdf) | Paul Albertella, Igor Stoppa |
+
+## October 2023 (Munich)
+
+| Title | Presenter(s) |
+| ----- | ------------ |
+| [A Systematic Approach to Using the Linux Kernel in a Safety Scenario](2023-10-Munich/A-Systematic-Approach-to-Using-the-Linux-Kernel-in-a-Safety-Scenario.pdf) | Igor Stoppa |
+| [Update on Planned Processes for Safety Analysis and Documentation of Results](2023-10-Munich/Update-on-Planned-Processes-for-Safety-Analysis-and-Documentation-of-Results.pdf) | Paul Albertella |
+
+## June 2023 (Berlin)
+
+| Title | Presenter(s) |
+| ----- | ------------ |
+| [Safety Analysis Approach](2023-06-Berlin/Safety-Analysis-Approach.pdf) | Paul Albertella |
+
+## November 2021 (Virtual)
+
+| Title | Presenter(s) |
+| ----- | ------------ |
+| [Certification using the New Approach to Safety](2021-11-Virtual/Certification-using-the-New-Approach-to-Safety.pdf) | Paul Albertella |
+
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,39 @@
+site_name: ELISA - Open Source Engineering Process
+repo_url: https://github.com/elisa-tech/wg-osep
+site_url: https://osep.elisa.tech/
+site_dir: public
+
+theme:
+  name: material
+  logo: images/elisa-logo.svg
+  favicon: images/favicon.ico
+  icon:
+    repo: fontawesome/brands/gitlab
+  font:
+    text: Open Sans
+    code: Fira Code
+  features:
+    - content.code.copy
+    - content.code.annotate
+    - navigation.footer
+    - navigation.top
+
+extra_css:
+  - stylesheets/elisa.css
+
+use_directory_urls: false
+
+plugins:
+  - search
+
+markdown_extensions:
+  - attr_list
+  - pymdownx.pathconverter:
+      absolute: true
+
+nav:
+  - ELISA: https://elisa.tech/
+  - OSEP: index.md
+  - Workshops: 'workshops/index.md'
+
+