From 9e87730f07ce91352bfc583870dbe118141c7c4f Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 29 Jul 2024 12:34:47 -0500 Subject: [PATCH 01/23] Add Makefile with commands for local development of schema browser --- Makefile | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..9ea82203 --- /dev/null +++ b/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 + +# 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 From 1d3cc75edc185389ba84c022cc2cccfa0ba8969b Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 29 Jul 2024 12:35:15 -0500 Subject: [PATCH 02/23] Add symlink to data directory --- browser/yml | 1 + 1 file changed, 1 insertion(+) create mode 120000 browser/yml diff --git a/browser/yml b/browser/yml new file mode 120000 index 00000000..114cd3f0 --- /dev/null +++ b/browser/yml @@ -0,0 +1 @@ +../yml/ \ No newline at end of file From 37960da427856657e02d6f95cf88ec3a1eafdf18 Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 29 Jul 2024 12:36:35 -0500 Subject: [PATCH 03/23] Add schema list partial Add a partial that will include a bulleted list of schemas with their names and (optionally) descriptions. The include_description parameter can be set to true if the schema's description field from the YAML file should be included; set this to false to include only the schema title. --- browser/_includes/_schema_list.html | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 browser/_includes/_schema_list.html diff --git a/browser/_includes/_schema_list.html b/browser/_includes/_schema_list.html new file mode 100644 index 00000000..7aece1e5 --- /dev/null +++ b/browser/_includes/_schema_list.html @@ -0,0 +1,13 @@ +
    + {%- assign schemas = site.pages | where: 'dir', '/' %} + {%- for schema in schemas %} + {%- if schema.name != 'index.md' %} +
  • + {{ schema.title }} + {%- if include.include_description %} + {{ schema.content }} + {%- endif %} +
    • + {%- endif %} + {%- endfor %} +
From 6b125bbc8354238a7e2b9edeecd59c32b60b6cd1 Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 29 Jul 2024 12:54:44 -0500 Subject: [PATCH 04/23] Add site footer partial --- browser/_includes/_site_footer.html | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 browser/_includes/_site_footer.html diff --git a/browser/_includes/_site_footer.html b/browser/_includes/_site_footer.html new file mode 100644 index 00000000..6942f977 --- /dev/null +++ b/browser/_includes/_site_footer.html @@ -0,0 +1,5 @@ +
+ + {{ site.repository_name }} is maintained by + {{ site.owner_name }}. + From 45030f0125492d040a930c1956416ed99f3258d4 Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 29 Jul 2024 12:55:06 -0500 Subject: [PATCH 05/23] Update browser to use new partials and fix links --- browser/_layouts/schema.html | 13 +++++-------- browser/_layouts/schema_index.html | 25 +++++++------------------ browser/index.md | 9 +-------- 3 files changed, 13 insertions(+), 34 deletions(-) diff --git a/browser/_layouts/schema.html b/browser/_layouts/schema.html index 8796443d..684215f5 100644 --- a/browser/_layouts/schema.html +++ b/browser/_layouts/schema.html @@ -6,12 +6,12 @@ {% seo %} - +
+ +

{{ page.title }}

{{ content }} @@ -53,10 +53,7 @@

{{ table.name }}

{%- endfor %} - + {% include _site_footer.html %}
diff --git a/browser/_layouts/schema_index.html b/browser/_layouts/schema_index.html index b0d3e623..98ca69e7 100644 --- a/browser/_layouts/schema_index.html +++ b/browser/_layouts/schema_index.html @@ -2,36 +2,25 @@ - -{% seo %} + {% seo %} - +
+ +

{{ page.title }}

{{ content }} - + {% include _site_footer.html %}
diff --git a/browser/index.md b/browser/index.md index 661e5e38..bdb22251 100644 --- a/browser/index.md +++ b/browser/index.md @@ -9,11 +9,4 @@ github repository. Schemas available here for browsing include: -
    - {%- assign schemas = site.pages | where: 'dir','/browser/' | sort: 'sort-index' %} - {%- for schema in schemas %} - {%- if schema.name != 'index.md' %} -
  • {{ schema.title }} {{ schema.content }}
    • - {%- endif %} - {%- endfor %} -
+{% include _schema_list.html include_description=true %} From 28f432b72854796f34d45e4c65e645ab299744ae Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 29 Jul 2024 12:53:18 -0500 Subject: [PATCH 06/23] Update site config to use with LTD --- _config.yml | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/_config.yml b/_config.yml index 356873bc..3dd7c00d 100644 --- a/_config.yml +++ b/_config.yml @@ -1,11 +1,27 @@ theme: jekyll-theme-cayman + 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://github.com/lsst" +owner_name: "LSST" + exclude: - Gemfile - /datalink - /tap-schema - /ups - /yml + - Makefile + - README.md + - requirements.txt + - yml/archive + readme_index: remove_originals: true + +safe: false From 20a39e4c1aac6b07b3cfe31f12424be517085291 Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 29 Jul 2024 13:04:22 -0500 Subject: [PATCH 07/23] Rename footer partial to _footer.html --- browser/_includes/{_site_footer.html => _footer.html} | 0 browser/_layouts/schema.html | 9 ++------- browser/_layouts/schema_index.html | 8 ++------ 3 files changed, 4 insertions(+), 13 deletions(-) rename browser/_includes/{_site_footer.html => _footer.html} (100%) diff --git a/browser/_includes/_site_footer.html b/browser/_includes/_footer.html similarity index 100% rename from browser/_includes/_site_footer.html rename to browser/_includes/_footer.html diff --git a/browser/_layouts/schema.html b/browser/_layouts/schema.html index 684215f5..9c98deb2 100644 --- a/browser/_layouts/schema.html +++ b/browser/_layouts/schema.html @@ -1,12 +1,7 @@ - - -{% seo %} - - - + {% include _site_header.html %}
@@ -53,7 +48,7 @@

{{ table.name }}

{%- endfor %} - {% include _site_footer.html %} + {% include _footer.html %}
diff --git a/browser/_layouts/schema_index.html b/browser/_layouts/schema_index.html index 98ca69e7..952186f9 100644 --- a/browser/_layouts/schema_index.html +++ b/browser/_layouts/schema_index.html @@ -1,11 +1,7 @@ - - {% seo %} - - - + {% include _site_header.html %}
@@ -20,7 +16,7 @@

{{ page.title }}

{{ content }} - {% include _site_footer.html %} + {% include _footer.html %}
From ee2e5ca898040b93c2f10830f15c7a1ea83b50cf Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 29 Jul 2024 13:06:17 -0500 Subject: [PATCH 08/23] Add site header partial --- browser/_includes/_header.html | 5 +++++ browser/_layouts/schema.html | 2 +- browser/_layouts/schema_index.html | 2 +- 3 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 browser/_includes/_header.html diff --git a/browser/_includes/_header.html b/browser/_includes/_header.html new file mode 100644 index 00000000..c32d92e4 --- /dev/null +++ b/browser/_includes/_header.html @@ -0,0 +1,5 @@ + +{% seo %} + + + \ No newline at end of file diff --git a/browser/_layouts/schema.html b/browser/_layouts/schema.html index 9c98deb2..991c3d3d 100644 --- a/browser/_layouts/schema.html +++ b/browser/_layouts/schema.html @@ -1,7 +1,7 @@ - {% include _site_header.html %} + {% include _header.html %}
diff --git a/browser/_layouts/schema_index.html b/browser/_layouts/schema_index.html index 952186f9..c6f616d0 100644 --- a/browser/_layouts/schema_index.html +++ b/browser/_layouts/schema_index.html @@ -1,7 +1,7 @@ - {% include _site_header.html %} + {% include _header.html %}
From 98b959ddecfdbaf7df1a9b2da92bbc918016a787 Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 29 Jul 2024 14:28:26 -0500 Subject: [PATCH 09/23] Capitalize GitHub properly in index text --- browser/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browser/index.md b/browser/index.md index bdb22251..4aa32f40 100644 --- a/browser/index.md +++ b/browser/index.md @@ -5,7 +5,7 @@ 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: From 34f4ceda8a865e04f5150b6dbfee26220d3b6312 Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 29 Jul 2024 14:44:44 -0500 Subject: [PATCH 10/23] Add GitHub workflow to build and upload schema browser to LTD --- .github/workflows/docs.yaml | 55 +++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 .github/workflows/docs.yaml diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..a176b576 --- /dev/null +++ b/.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 + + - 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/')) From 01d480436edd8eadc36c307efb73c23e2dc2cf10 Mon Sep 17 00:00:00 2001 From: Jeremy McCormick Date: Mon, 29 Jul 2024 16:08:31 -0500 Subject: [PATCH 11/23] Fix icon link --- browser/_layouts/schema.html | 2 +- browser/_layouts/schema_index.html | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/browser/_layouts/schema.html b/browser/_layouts/schema.html index 991c3d3d..f74994b7 100644 --- a/browser/_layouts/schema.html +++ b/browser/_layouts/schema.html @@ -6,7 +6,7 @@