general site layout

.github/workflows/publish.yaml

@@ -1,7 +1,6 @@
 name: Publish
 on:
   workflow_dispatch:
-  # trigger will use workflow in target (main) so it can have access to secrets
   pull_request:
     branches:
     - main
@@ -12,28 +11,28 @@ jobs:
     env:
       NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
     runs-on: ubuntu-latest
+
     steps:
     - uses: actions/checkout@v4
-    - name: Install Python
-      uses: actions/setup-python@v5
+    - uses: actions/setup-python@v5
       with:
         python-version: '3.11'
     - name: Install Dependencies
       run: |
         pip install -r requirements.txt
         npm install netlify-cli -g
-    - name: Make top level
+    - name: Make top level files
       run: make -C src html
     - name: Assemble site
       run: |
-        cat site.yaml
         python scripts/site.py build
         cp -r src/_build/html/* dist
-    - name: Publish to development on PR
-      if: ${{ github.event_name == 'pull_request_target' }}
-      run: |
-        netlify deploy --dir=dist --site=oneapi-spec
-    - name: Publish to production with manual trigger
-      if: ${{ github.event_name == 'workflow_dispatch' }}
-      run: |
-        netlify deploy --dir=dist --site=oneapi-spec --prod
+    - name: Publish to development
+      # Publish to preview for a PR
+      # Cannot publish from a fork because no access to secrets
+      if: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == false }}
+      run: netlify deploy --dir=dist --site=oneapi-spec
+    - name: Publish to production
+      # Publish to production when manually triggered for main
+      if: ${{ github.event_name == 'workflow_dispatch' || github.ref == 'refs/heads/main' }}
+      run: netlify deploy --dir=dist --site=oneapi-spec --prod

scripts/site.py

@@ -19,30 +19,30 @@ def download_file(url):
     return local_filename
 
 
-def extract_release(releases_dir, url):
+def extract_release(site_dir: str, url: str):
     file = download_file(url)
     with zipfile.ZipFile(file, "r") as zip_ref:
-        zip_ref.extractall(releases_dir)
+        zip_ref.extractall(site_dir)
     os.remove(file)
 
 
-def extract_releases(update, site_dir, config):
-    releases_dir = os.path.join(site_dir, "versions")
-    os.makedirs(releases_dir, exist_ok=update)
-    for release in config["releases"]:
-        if update and os.path.exists(
-            os.path.join(releases_dir, release["name"])
-        ):
-            continue
-        extract_release(releases_dir, release["url"])
-
-    latest = os.path.join(releases_dir, "latest")
-    if update and os.path.exists(latest):
-        os.remove(latest)
-    try:
-        os.symlink(config["latest"], latest)
-    except Exception as e:
-        raise click.ClickException(f"Could not create latest link: {e}")
+def extract_site(update: bool, site_dir: str, tree: dict):
+    for key, value in tree.items():
+        dir = os.path.join(site_dir, key)
+        exists = os.path.exists(dir)
+        try:
+            os.makedirs(dir, exist_ok=update)
+        except Exception as e:
+            raise click.ClickException(
+                f"Could not create directory {dir}: {e}"
+            )
+        if isinstance(value, str):
+            if not exists:
+                extract_release(dir, value)
+        elif isinstance(value, dict):
+            extract_site(update, dir, value)
+        else:
+            raise click.ClickException(f"Invalid value for {key}: {value}")
 
 
 @click.group()
@@ -52,16 +52,26 @@ def cli():
 
 @cli.command()
 @click.option("--update", is_flag=True, help="Update the site.")
-@click.option("--dir", type=click.Path(), default="dist")
-def build(update, dir):
+@click.option(
+    "--dir", type=click.Path(), default="dist", help="Site directory."
+)
+@click.option(
+    "--config",
+    type=click.Path(),
+    default="site.yaml",
+    help="Site configuration.",
+)
+def build(update, dir, config):
     """Build the site."""
 
     # get configuration from site.yaml
     try:
-        with open("site.yaml") as f:
-            config = yaml.load(f, Loader=yaml.FullLoader)
+        with open(config) as f:
+            c = yaml.load(f, Loader=yaml.FullLoader)
     except Exception as e:
-        raise click.ClickException(f"Could not load site configuration: {e}")
+        raise click.ClickException(
+            f"Could not load site configuration from {config}: {e}"
+        )
 
     try:
         os.makedirs(dir, exist_ok=update)
@@ -70,7 +80,7 @@ def build(update, dir):
             f"Site directory {dir} could not be created: {e}"
         )
 
-    extract_releases(update, dir, config)
+    extract_site(update, dir, c["site"])
 
 
 if __name__ == "__main__":

site.yaml

@@ -1,6 +1,6 @@
-latest: 1.0-rev-1
-releases:
-- name: 1.0-rev-1
-  url: https://github.com/uxlfoundation/oneAPI-spec/releases/download/v1.0-rev-1/oneapi-spec-v1.0-rev-1.zip
-- name: 1.3-rev-1
-  url: https://github.com/uxlfoundation/oneAPI-spec/releases/download/oneAPI-v1.3-rev-1/oneapi-spec-v1.3-rev-1.zip
+site:
+  specifications:
+    oneapi:
+      latest: https://github.com/uxlfoundation/oneAPI-spec/releases/download/oneAPI-v1.3-rev-1/oneapi-spec-v1.3-rev-1.zip
+      v1.3-rev-1: https://github.com/uxlfoundation/oneAPI-spec/releases/download/oneAPI-v1.3-rev-1/oneapi-spec-v1.3-rev-1.zip
+      v1.0-rev-1: https://github.com/uxlfoundation/oneAPI-spec/releases/download/v1.0-rev-1/oneapi-spec-v1.0-rev-1.zip

src/index.rst

@@ -30,7 +30,7 @@ Releases are listed below. See GitHub_ for the latest build.
     - View
   * - `1.3 rev 1`_
     - 2023-11-06
-    - `HTML <versions/1.3-rev-1/>`__ `PDF <versions/1.3-rev-1/oneAPI-spec.pdf>`__
+    - `HTML <specifications/oneapi/v1.3-rev-1/>`__ `PDF <specifications/oneapi/v1.3-rev-1/oneAPI-spec.pdf>`__
   * - `1.3 provisional rev 1`_
     - 2023-9-14
     - `HTML <versions/1.3-provisional-rev-1/>`__ `PDF <versions/1.3-provisional-rev-1/oneAPI-spec.pdf>`__
@@ -88,7 +88,7 @@ Releases are listed below. See GitHub_ for the latest build.
     - `HTML <versions/1.0-rev-2/>`__ `PDF <versions/1.0-rev-2/oneAPI-spec.pdf>`__
   * - `1.0 rev 1`_
     - 2020-9-14
-    - `HTML <versions/1.0-rev-1/>`__ `PDF <versions/1.0-rev-1/oneAPI-spec.pdf>`__
+    - `HTML <specifications/oneapi/v1.0-rev-1/>`__ `PDF <specifications/v1.0-rev-1/oneAPI-spec.pdf>`__
 
 Release Notes
 -------------