Add mkdocs publish support

Signed-off-by: Paul Albertella <[email protected]>

.github/workflows/main.yml

@@ -1,44 +1,39 @@
-name: CI
+name: main
 
 # 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 ]
 
   # 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
+  # This workflow contains a single job called "deploy"
+  # 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

.github/workflows/preview.yml

@@ -0,0 +1,38 @@
+name: preview
+
+on:
+  # Triggers on pull request branch when it is marked ready for review
+  pull_request:
+    type: [ready_for_review]
+
+  # 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 "preview"
+  # This deploys PR content to a preview sub-directory
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - 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 -v -d preview/ --force

docs/CNAME

@@ -0,0 +1 @@
+osep.elisa.tech

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.
+

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;
+}

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:
+    - Home: index.md
+
+