Merge pull request #15 from Arcadia-Science/ek/empty-repo

Merge full codebase review

Author: ekiefl

.github/workflows/build.yml

@@ -0,0 +1,80 @@
+on:
+  # Run the workflow when new tags are created.
+  push:
+    tags:
+      - v*
+  # Allow the workflow to be triggered manually.
+  workflow_dispatch:
+
+name: Build
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      PUBLISH_BRANCH: publish
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+
+      - name: Create a name for the build branch
+        run: |
+          git checkout main
+          echo "BUILD_BRANCH=build-$(git rev-parse --short HEAD)" >> $GITHUB_ENV
+
+      # Reset the `publish` branch to point to `main`, because we use the `publish` branch
+      # only to store the build artifacts, not for version control.
+      - name: Reset the publish branch
+        run: |
+          git checkout -b $PUBLISH_BRANCH || true
+          git checkout $PUBLISH_BRANCH
+          git reset --hard origin/main
+          git push --force origin $PUBLISH_BRANCH
+          git checkout main
+
+      # Delete the build branch if it already exists,
+      # as the `peter-evans/create-pull-request` action used below will update the branch
+      # if it exists, which we don't want.
+      # Note: deleting the build branch will also close the corresponding PR, if it exists.
+      - name: Delete the build branch
+        run: |
+          git branch -D $BUILD_BRANCH || true
+          git push --force --delete origin $BUILD_BRANCH || true
+
+      - name: Build the publication
+        run: |
+          git checkout main
+          uv run --no-project _build.py
+
+      # Open a PR to merge the build artifacts into the `publish` branch.
+      # Note: this action automatically creates the build branch and commits all unstaged changes to it.
+      - name: Open PR
+        uses: peter-evans/create-pull-request@v7
+        env:
+          PR_BODY: |
+            This PR creates a new version of the public Quarto publication. It was automatically created by the `build.yml` workflow.
+
+            To preview this version of the publication, check out this PR branch locally and run `quarto preview`.
+
+            To publish this version of the publication, merge this PR into the `publish` branch.
+        with:
+          # `base` is the target branch for the PR.
+          base: ${{ env.PUBLISH_BRANCH }}
+          # `branch` is the source branch for the PR.
+          branch: ${{ env.BUILD_BRANCH }}
+          commit-message: "Update the public Quarto publication"
+          title: "[Publication] Update the public Quarto publication"
+          body: ${{ env.PR_BODY }}

.github/workflows/publish.yml

@@ -1,3 +1,6 @@
+# This workflow is derived from an example workflow in the Quarto docs here:
+# https://quarto.org/docs/publishing/github-pages.html#github-action.
+
 on:
   workflow_dispatch:
   push:
@@ -6,13 +9,35 @@ on:
 name: Quarto Publish
 
 jobs:
-  build-deploy:
+  publish:
     runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
       - name: Check out repository
         uses: actions/checkout@v4
+        with:
+          # Ensure that the `publish` branch is checked out.
+          ref: publish
+
+      # This is needed to create the `gh-pages` branch.
+      - name: Set up Git user
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      # The `quarto-actions/publish` action does not create the `gh-pages` branch,
+      # so we need to create it manually here (if it does not exist).
+      - name: Create the `gh-pages` branch if it does not exist
+        run: |
+          git fetch origin
+          if ! git show-ref --verify --quiet refs/remotes/origin/gh-pages; then
+            git checkout --orphan gh-pages
+            git rm -rf --quiet .
+            git commit --allow-empty -m "Initializing gh-pages branch"
+            git push origin gh-pages
+            git checkout publish
+          fi
 
       - name: Set up Quarto
         uses: quarto-dev/quarto-actions/setup@v2

.gitignore

@@ -1,3 +1,6 @@
+# Claude Code
+CLAUDE.md
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

Makefile

@@ -29,7 +29,3 @@ execute:
 .PHONY: preview
 preview:
 	quarto preview
-
-.PHONY: bump-version
-bump-version:
-	python _bump_version.py

README.md

@@ -1,142 +1,34 @@
-# Notebook pub template
+# Notebook Publication Template
 
-This repo is a template for notebook publications. The publication rendered and hosted by this repository serves as a demo that can be viewed at [this URL](https://arcadia-science.github.io/notebook-pub-template/).
+This repo is a template for Jupyter notebook publications. The template produces a publication rendered and hosted by Quarto, which can be viewed at [this demo URL](https://arcadia-science.github.io/notebook-pub-template/).
 
-## How to use this template
+## Template Documentation
 
-1. Create a repo from this template
+All the learning resources for this template can be found in `developer-docs/`.
 
-    In the top-right of this GitHub repo, select the green button that says "*Use this template*".
+- [Quickstart Guide](developer-docs/QUICKSTART.md) - **The most efficient way to get started** is to follow this guide (the rest can wait)
+- [Environment Setup Guide](developer-docs/ENVIRONMENT_SETUP.md) - How to set up your development environment
+- [Publishing Guide](developer-docs/PUBLISHING_GUIDE.md) - How to publish your notebook publication
+- [Template Architecture](developer-docs/TEMPLATE_ARCHITECTURE.md) - Understanding the template's structure
 
-    **IMPORTANT**: When creating your repo from this template, you need to **check the box** that says, "*Include all branches*". This is because the hosted pub is managed on a separate branch.
+---
 
-1. Config edits
+**NOTE: When ready to publish, fill in the information below, then delete this line and everything above it.**
 
-    * Replace the variables in `_variables.yml`
-        - For `google_analytics`, provide the publishing team your repo name and they'll provide you a Google Analytics tracking ID.
-    * Replace the variables in `authors.yml`.
-        - This can always be updated, but for now at least add yourself.
+# [PUB-TITLE]
 
-1. Install Quarto
+This code repository contains or points to all materials required for creating and hosting the publication entitled, *"[PUB-TITLE]"*.
 
-    The publication is rendered with [Quarto](https://quarto.org/). If you don’t have it installed (check with quarto --version), you can install it [here](https://quarto.org/docs/get-started/).
+The publication is hosted at [this URL]([PUB-URL]).
 
-1. Setup the code environment
+## Data Description
 
-    This repository uses conda to manage the computational and build environment. If you don’t have it installed (check with `conda --version`), you can find operating system-specific instructions for installing miniconda [here](https://docs.anaconda.com/miniconda/).
+[DESCRIPTION OF THE DATA]
 
-    When you're ready, run the following commands to create and activate the environment. Replace `[REPO-NAME]` with your repository name.
+## Reproduce
 
-    ```bash
-    conda env create -n [REPO-NAME] --file env.yml
-    conda activate [REPO-NAME]
-    ```
+Please see [SETUP.qmd](SETUP.qmd).
 
-    (As you introduce dependencies to your publication, or if you already have your full set of dependencies, add them to `env.yml` with the version pinned.)
+## Contribute
 
-    Now, install any internal packages in the repository:
-
-    ```bash
-    pip install -e .
-    ```
-
-    And finally, install the [pre-commit](https://pre-commit.com/) hooks:
-
-    ```bash
-    pre-commit install
-    ```
-
-    Test your installation with `make preview`. Your pub will open up in your browser.
-
-    Afterwards, create a branch to work on (don't commit to `main` directly).
-
-1. Register your publication with the Pub Team
-
-    If you intend to publish your analysis, fill out the "*Kick off a new pub*" form on the AirTable [Publishing toolkit](https://www.notion.so/arcadiascience/Publishing-2-0-f0c51bf29d1d4356a86e6cf8a72ae88b?pvs=4#e1de83e8dd2a4081904064347779ed25).
-
-1. Create your pub
-
-    Edit `index.ipynb` to create your pub. As you work, render it in a live preview with `make preview`.
-
-
-## How to publish
-
-1. Enable read/write permissions for GitHub Actions
-
-    In your repo, go to *Settings* -> *Actions* -> *General* -> *Workflow permissions*, and check the box, "*Read and write permissions*"
-
-1. Populate the `README_TEMPLATE.md`
-
-    Populate `README_TEMPLATE.md` and then rename it to `README.md`.
-
-    **NOTE**: The content you're reading now is the current `README.md`, which is to be replaced with `README_TEMPLATE.md`.
-
-1. Remove placeholder package
-
-    If you did not populate `src/analysis` with your own content, remove it (`rm -rf src/analysis`).
-
-1. Remove reference to the syntax demo from `_quarto.yml`
-
-    Feel free to keep `demo.ipynb` in your repo, but remove the following lines in `_quarto.yml`:
-
-    ```
-    - text: 'Demo'
-      href: demo.ipynb
-    ```
-
-    This will remove *Demo* from the navigation bar.
-
-1. Make the repository public
-
-    In order for this pub to be open and reproducible, make the [repo public](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility).
-
-1. Enable comments
-
-    Comments are handled with [Giscus](https://giscus.app/), which Quarto has an integration for. Once enabled, a widget is placed at the bottom of the publication that provides an interface to read, write, react, and respond to [GitHub Discussions](https://docs.github.com/en/discussions) comments. Comments made through the interface are automatically added as comments to a GitHub Discussions thread of your repository.
-
-    First, [enable GitHub Discussions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/enabling-or-disabling-github-discussions-for-a-repository) for your repo.
-
-    Second, [install the Giscus App](https://github.com/apps/giscus) for your repository. Click *Configure*, select *Arcadia-Science*, then select your repository from the dropdown. Click *Update access*.
-
-    **IMPORTANT**: Do not deselect any of the other Arcadia-Science repositories that already have the Giscus app installed, *e.g.* `Arcadia-Science/notebook-pub-template`.
-
-    Now, edit the comments section in `_quarto.yml` with your repo name:
-
-    ```yaml
-    comments:
-      giscus:
-        repo: Arcadia-Science/notebook-pub-template
-        input-position: top
-    ```
-
-    You may have to wait a few minutes for `make preview` to properly render the Giscus widget.
-
-1. Get approval from the Pub Team
-
-    Like all other pubs, follow the [AirTable toolkit guide](https://airtable.com/appN7KQ55bT6HHfog/pagm69ti1kZK1GhBx) through to the final step, "*Submit your pub for release*".
-
-1. Final run-through
-
-    Begin with a clean branch (no uncommitted changes). Then run the notebook from the command line:
-
-    ```bash
-    make execute
-    ```
-
-    This command will update `index.ipynb` with the latest execution results. Importantly, it may generate runtime artifacts in the `_freeze/` directory.
-
-    Then run `make preview` to see how the publication is rendering. Verify that your changes appear how you intend them to appear. If not, make the necessary changes and re-run `make execute`.
-
-    Once happy, commit `index.ipynb` and all files in the `_freeze/` directory.
-
-    Now, create a pull request to merge your branch into `main`. Once your PR is approved, merge into `main`.
-
-1. Host the publication
-
-    Publishing is automated through a GitHub Action that triggers when a pull request is merged into the `publish` branch. Thus, all that's required for your publication to go live is to merge into `publish`. By convention, we only merge changes from the `main` branch into `publish`. This ensures collaborators can merge their completed work into `main`, where others can see and build upon it, while keeping those changes private until they are deliberately hosted by merging `main` into `publish`.
-
-    When all your changes have been merged into `main` and you're ready for your publication to go live, open a pull request to merge `main` into `publish`. Once approved and merged, your publication will be live within minutes.
-
-## Publishing revisions
-
-See [CONTRIBUTING.qmd](CONTRIBUTING.qmd).
+Please see [CONTRIBUTING.qmd](CONTRIBUTING.qmd).