Merge pull request #242 from lsst/tickets/DM-41310

DM-41310: Update the schema browser to use LTD

.github/workflows/docs.yaml

@@ -0,0 +1,55 @@
+name: Build and Deploy the Schema Browser
+
+"on":
+  merge_group: {}
+  pull_request: {}
+  push:
+    branches-ignore:
+      # These should always correspond to pull requests, so ignore them for
+      # the push trigger and let them be triggered by the pull_request
+      # trigger, avoiding running the workflow twice.  This is a minor
+      # optimization so there's no need to ensure this is comprehensive.
+      - "dependabot/**"
+      - "gh-readonly-queue/**"
+      - "renovate/**"
+      - "tickets/**"
+      - "u/**"
+  release:
+    types: [published]
+
+jobs:
+
+  docs:
+
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history for setuptools_scm
+
+      - name: Install Ruby and other prerequisites
+        run: sudo apt-get install -y ruby-full build-essential zlib1g-dev
+
+      - name: Install required Ruby gems
+        run: sudo gem install bundler jekyll jekyll-theme-cayman jekyll-last-modified-at
+
+      - name: Build the schema browser site
+        run: jekyll build
+
+      # Only attempt documentation uploads for tagged releases and pull
+      # requests from ticket branches in the same repository.  This avoids
+      # version clutter in the docs and failures when a PR doesn't have access
+      # to secrets.
+      - name: Upload to LSST the Docs
+        uses: lsst-sqre/ltd-upload@v1
+        with:
+          project: "sdm-schemas"
+          dir: "_site"
+          username: ${{ secrets.LTD_USERNAME }}
+          password: ${{ secrets.LTD_PASSWORD }}
+        if: >
+          github.event_name != 'merge_group'
+          && (github.event_name != 'pull_request'
+              || startsWith(github.head_ref, 'tickets/'))

Makefile

@@ -0,0 +1,31 @@
+# Makefile for building the SDM Schemas browser site
+.PHONY: help init run build clean
+
+# Print help
+help:
+	@echo "Available targets for sdm_schemas:"
+	@echo "  init  - Install the required Ruby gems"
+	@echo "  build - Build the schema browser site"
+	@echo "  run   - Serve the schema browser site"
+	@echo "  clean - Clean the schema browser site"
+
+# Install required Ruby gems (Ruby must be installed externally.)
+init:
+	@command -v gem >/dev/null 2>&1 || { \
+		echo >&2 "gem command not found. Please install Ruby using your package manager."; \
+		echo >&2 "For more information, visit: https://jekyllrb.com/docs/installation"; \
+		exit 1; \
+	}
+	gem install -q --silent --no-verbose jekyll bundler jekyll-theme-cayman jekyll-last-modified-at
+
+# Run the web server and watch for changes
+run:
+	jekyll serve --watch
+
+# Build the site
+build:
+	jekyll build
+
+# Cleanup local config and remove the generated site
+clean:
+	jekyll clean && rm -rf _site &> /dev/null

_config.yml

@@ -1,11 +1,35 @@
 theme: jekyll-theme-cayman
+plugins:
+  - jekyll-last-modified-at
+last-modified-at:
+  date-format: '%B %d, %Y'
+
 data_dir: ./yml
-layouts_dir: ./browser/_layouts
+layouts_dir: _layouts
+source: ./browser
+baseurl: ""
+
+repository_url: "https://github.com/lsst/sdm_schemas"
+repository_name: "SDM Schemas"
+owner_url: "https://rubinobservatory.org/"
+owner_name: "Rubin Observatory"
+
 exclude:
   - Gemfile
   - /datalink
   - /tap-schema
   - /ups
   - /yml
+  - Makefile
+  - README.md
+  - requirements.txt
+  - yml/archive
+
 readme_index:
   remove_originals: true
+
+safe: false
+
+sass:
+  sass_dir: _sass
+  #  style: compressed

browser/_includes/_footer.html

@@ -0,0 +1,7 @@
+<hr/>
+<!--<span class="site-footer-owner">-->
+<p>
+    <a href="{{ site.repository_url }}">{{ site.repository_name }}</a> is maintained by
+    <a href="{{ site.owner_url }}">{{ site.owner_name }}</a>.
+</p>
+

browser/_includes/_header.html

@@ -0,0 +1,7 @@
+<meta charset="UTF-8">
+{% seo %}
+<link rel="shortcut icon" href="https://www.lsst.org/sites/default/files/Rubin%20favicon%2032px.png" type="image/png">
+<link rel="shortcut icon" href="./favicon.ico" type="image/x-icon">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="theme-color" content="#157878">
+<link rel="stylesheet" href="./assets/css/main.css">

browser/_includes/_logo.html

@@ -0,0 +1,3 @@
+<a href="https://rubinobservatory.org/" target="_blank">
+  <img id="logo" src="./assets/images/rubinobs.png" alt="Rubin Observatory Logo"/>
+</a>

browser/_includes/_schema_list.html

@@ -0,0 +1,13 @@
+<ul>
+  {%- assign schemas = site.pages | where: 'dir', '/' | sort: 'sort-index' %}
+  {%- for schema in schemas %}
+    {%- if schema.name != 'index.md' %}
+    <li>
+        <a href=".{{ schema.url }}">{{ schema.title }}</a>
+        {%- if include.include_description %}
+        {{ schema.content }}
+        {%- endif %}
+    </li>
+    {%- endif %}
+  {%- endfor %}
+</ul>

browser/_layouts/schema.html

@@ -1,17 +1,15 @@
 <!DOCTYPE html>
 <html lang="{{ site.lang | default: "en-US" }}">
   <head>
-    <meta charset="UTF-8">
-
-{% seo %}
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <meta name="theme-color" content="#157878">
-    <link rel="stylesheet" href="{{ '/assets/css/style2.css?v=' | append: site.github.build_revision | relative_url }}">
+    {% include _header.html %}
   </head>
   <body>
     <div id="container">
       <nav id="sidebar">
-        <img id="logo" src="{{ '/browser/assets/images/rubinobs.png' | relative_url }}"/>
+        {% include _logo.html %}
+        <ul>
+            <li><b>Updated:</b> {% last_modified_at %}</li>
+        </ul>
         <ul>
           <li><a href=".">Schema Browser</a></li>
           <ul>
@@ -23,8 +21,11 @@
             </ul>
           </ul>
         </ul>
-      </nav><!--
-   --><div id="content">
+        <ul>
+          <li><a href="/v">Change version</a></li>
+        </ul>
+      </nav>
+      <div id="content">
         <main class="main-content">
           <h1>{{ page.title }}</h1>
           {{ content }}
@@ -41,7 +42,9 @@ <h2>{{ table.name }}</h2>
               </tr>
               {%- for col in table.columns %}
               <tr id="{{ col['@id'] | remove:'#' }}">
-                <td class="column-name">{{ col.name }}</td>
+                <td class="column-name">
+                    <a href="#{{ col['@id'] | remove:'#' }}">{{ col.name }}</a>
+                </td>
                 <td>{{ col.datatype }}</td>
                 <td>{{ col['ivoa:unit'] | default: col['fits:tunit'] }}</td>
                 <td>
@@ -53,10 +56,7 @@ <h2>{{ table.name }}</h2>
             </table>
           </section>
           {%- endfor %}
-          <footer class="site-footer">
-            <span class="site-footer-owner"><a href="{{ site.github.repository_url }}">{{ site.github.repository_name }}</a> is maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a>.</span>
-            <span class="site-footer-credits">This page was generated by <a href="https://pages.github.com">GitHub Pages</a>.</span>
-          </footer>
+          {% include _footer.html %}
         </main>
       </div>
     </div>

browser/_layouts/schema_index.html

@@ -1,37 +1,28 @@
 <!DOCTYPE html>
 <html lang="{{ site.lang | default: "en-US" }}">
   <head>
-    <meta charset="UTF-8">
-
-{% seo %}
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <meta name="theme-color" content="#157878">
-    <link rel="stylesheet" href="{{ '/assets/css/style2.css?v=' | append: site.github.build_revision | relative_url }}">
+    {% include _header.html %}
   </head>
   <body>
     <div id="container">
       <nav id="sidebar">
-        <img id="logo" src="{{ '/browser/assets/images/rubinobs.png' | relative_url }}"/>
+        {% include _logo.html %}
+        <ul>
+            <li><b>Updated:</b> {% last_modified_at %}</li>
+        </ul>
         <ul>
           <li><a href=".">Schema Browser</a></li>
-          <ul>
-            {%- assign schemas = site.pages | where: 'dir','/browser/' | sort: 'sort-index' %}
-            {%- for schema in schemas %}
-            {%- if schema.name != 'index.md' %}
-            <li><a href="{{ schema.url | relative_url }}">{{ schema.title }}</a></li>
-            {%- endif %}
-            {%- endfor %}
-          </ul>
+          {% include _schema_list.html include_description=false %}
+        </ul>
+        <ul>
+        <li><a href="/v">Change version</a></li>
         </ul>
-      </nav><!--
-   --><div id="content">
+      </nav>
+      <div id="content">
         <main class="main-content">
           <h1>{{ page.title }}</h1>
           {{ content }}
-          <footer class="site-footer">
-            <span class="site-footer-owner"><a href="{{ site.github.repository_url }}">{{ site.github.repository_name }}</a> is maintained by <a href="{{ site.github.owner_url }}">{{ site.github.owner_name }}</a>.</span>
-            <span class="site-footer-credits">This page was generated by <a href="https://pages.github.com">GitHub Pages</a>.</span>
-          </footer>
+          {% include _footer.html %}
         </main>
       </div>
     </div>

browser/assets/css/style2.scss → browser/_sass/style2.scss

@@ -1,7 +1,3 @@
----
-permalink: /assets/css/style2.css
----
-
 @import 'jekyll-theme-cayman';
 
 html {
@@ -18,6 +14,7 @@ a {
 }
 
 #container {
+	display: flex;
 	height: 100%;
 }
 
@@ -40,7 +37,7 @@ a {
 #sidebar ul {
 	list-style-type: none;
 	margin-left: 1rem;
-	padding: 0;  
+	padding: 0;
 }
 
 #sidebar ul ul ul {
@@ -74,5 +71,5 @@ a {
 }
 
 .main-content .schema-table .column-name {
-	font-family: monospace;	
+	font-family: monospace;
 }

browser/apdb.md

@@ -1,6 +1,6 @@
 ---
 layout: schema
-title: Alert Production Database schema
+title: Alert Production Database
 schema: apdb
 sort-index: 15
 ---

browser/assets/css/main.scss

@@ -0,0 +1,3 @@
+---
+---
+@import "style2";

browser/dp01.md

@@ -1,6 +1,6 @@
 ---
 layout: schema
-title: Data Preview 0.1 Schema
+title: Data Preview 0.1
 schema: dp01_dc2
 sort-index: 10
 ---

browser/dp02.md

@@ -1,6 +1,6 @@
 ---
 layout: schema
-title: Data Preview 0.2 Schema
+title: Data Preview 0.2
 schema: dp02_dc2
 sort-index: 9
 ---

browser/hsc.md

@@ -1,8 +1,10 @@
 ---
 layout: schema
-title: HSC Schema
+title: HyperSuprimeCam
 schema: hsc
 sort-index: 20
 ---
-The HSC Schema describes the outputs of the latest data release production pipelines for HyperSuprimeCam. This schema is used by [ci_hsc](https://github.com/lsst/ci_hsc), which
-verifies the schema of the pipeline output files.
+The HyperSuprimeCam (HSC) Schema describes the outputs of the latest data release production pipelines for
+HyperSuprimeCam.
+This schema is used by [ci_hsc](https://github.com/lsst/ci_hsc), which verifies the schema of the pipeline
+output files.

browser/imsim.md

@@ -1,6 +1,6 @@
 ---
 layout: schema
-title: LSSTCam-imSim Schema
+title: LSSTCam ImSim
 schema: imsim
 sort-index: 30
 ---

browser/index.md

@@ -5,15 +5,8 @@ title: Science Data Model Schemas
 This schema browser provides a view on a curated subset of the Rubin Observatory's database schemas for
 user-facing data products (the Science Data Model, or SDM).  These pages are rendered directly from the latest
 revisions of schema definition YAML files maintained in the [sdm_schemas](https://github.com/lsst/sdm_schemas)
-github repository.
+GitHub repository.
 
 Schemas available here for browsing include:
 
-<ul>
-    {%- assign schemas = site.pages | where: 'dir','/browser/' | sort: 'sort-index' %}
-    {%- for schema in schemas %}
-    {%- if schema.name != 'index.md' %}
-    <li><a href="{{ schema.url | relative_url }}">{{ schema.title }}</a> {{ schema.content }}</li>
-    {%- endif %}
-    {%- endfor %}
-</ul>
+{% include _schema_list.html include_description=true %}

browser/yml

@@ -0,0 +1 @@
+../yml/