diff --git a/.Rbuildignore b/.Rbuildignore index 8c8412d..57f59da 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -12,6 +12,7 @@ _freeze/ ^\.github$ ^README\.Rmd$ ^data-raw$ +^cds$ ^\.quarto$ ^AGENTS\.md$ ^CLAUDE\.md$ diff --git a/.claude/commands/lint.md b/.claude/commands/lint.md index 50abda4..a9f7f4e 100644 --- a/.claude/commands/lint.md +++ b/.claude/commands/lint.md @@ -1,10 +1,22 @@ --- description: Lint all R source files and report issues allowed-tools: + - Bash(rm -f cds) - Bash(Rscript -e 'lintr::lint*') --- -Run `Rscript -e 'lintr::lint_dir()'` to check all R source files against `.lintr.R`. +First run `rm -f cds` to remove the repo's self-referential `cds -> .` symlink +(see CLAUDE.md) from the working tree. `lintr::lint_dir()`'s own directory +walk follows symlinks and has no config-level way to skip it (any +`.lintr.R` exclusion naming `cds` collapses onto the real files it aliases +and silently excludes them too --- see `.lintr.R`'s comment), so with the +symlink present every real lint is duplicated dozens of times over. Removing +it first is safe: it only deletes the symlink, never the directory it points +into. + +Then run `Rscript -e 'lintr::lint_dir()'` to check all R source files against `.lintr.R`. +Afterwards, whether or not lint succeeds, restore the symlink with +`git checkout -- cds`, so the deletion is never committed. Report all lint issues grouped by file, including: diff --git a/.claude/commands/new-chapter.md b/.claude/commands/new-chapter.md index d914306..7e81313 100644 --- a/.claude/commands/new-chapter.md +++ b/.claude/commands/new-chapter.md @@ -1,5 +1,5 @@ --- -description: Scaffold a new chapter in the Quarto website +description: Scaffold a new topic page in the Quarto website allowed-tools: - Read - Write @@ -7,7 +7,7 @@ allowed-tools: - Bash(quarto render:*) --- -Create a new chapter from `$ARGUMENTS` (e.g. `/new-chapter intro Introduction`). +Create a new topic page from `$ARGUMENTS` (e.g. `/new-chapter intro Introduction`). First, parse `$ARGUMENTS`: the first whitespace-delimited token is the **slug** (used for the filename, no `.qmd`); everything after the first space is the @@ -15,19 +15,18 @@ First, parse `$ARGUMENTS`: the first whitespace-delimited token is the **slug** Steps: -1. Create `chapters/.qmd` with YAML frontmatter holding just `title:` (set +1. Create `.qmd` at the repo root with YAML frontmatter holding just `title:` (set to the title). Do NOT set `date:` --- `_quarto-website.yml` sets `date: last-modified` globally, and a per-page `date:` would override it and freeze the date. Do NOT add a top-level `#` heading in the body --- Quarto renders the frontmatter `title:` as the page heading, so a `#` heading would duplicate it. -2. Add an entry for the new chapter to the `website.navbar.left` "Chapters" menu - in `_quarto-website.yml` (read the file first to find the menu; there is no - `chapters:` key in `_quarto.yml`). Use `text:` for the menu label and - `href: chapters/.qmd`. - Also add `chapters/.qmd` to the "Chapters" section of `website.sidebar` - in the same position: the sidebar order sets the previous/next page links. -3. Confirm it renders: `quarto render chapters/.qmd`. +2. Add `.qmd` to `website.sidebar.contents` in `_quarto-website.yml`, + in reading order: the sidebar order sets the previous/next page links. + Add the same page, in the same position, to the matching menu under + `website.navbar.left` (create the `left:` list and menu if this is the + first page): the navbar menus mirror the sidebar one-for-one. +3. Confirm it renders: `quarto render .qmd`. Style rules (from CLAUDE.md): diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index c90b813..e18c1a1 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -30,12 +30,12 @@ When describing lists of three or more items, use a bullet list instead of a com **Examples:** -❌ **Don't** use comma-separated lists for three or more items: +**Don't** use comma-separated lists for three or more items: ``` The template includes GitHub Actions workflows for publishing, link checking, and spell checking. ``` -✅ **Do** use bullet lists instead: +**Do** use bullet lists instead: ``` The template includes GitHub Actions workflows for: diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 8b33a49..fa3dda2 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,9 +1,8 @@ # Keep git submodules and pinned GitHub Actions up to date automatically. # -# This template embeds the shared `macros` repo as the `latex-macros` git submodule. Dependabot's +# This repo embeds the shared `macros` repo as the `latex-macros` git submodule. Dependabot's # `gitsubmodule` updater opens a PR whenever a submodule's default branch -# (currently `main`) advances, so neither this template nor the books generated -# from it have to bump the pointer by hand. See the ADR at Morrison-Lab/macros +# (currently `main`) advances, so the pointer never has to be bumped by hand. See the ADR at Morrison-Lab/macros # (docs/adr/0001-macros-submodule-versioning.md) for why we track `main` rather # than a pinned release tag. version: 2 diff --git a/.github/instructions/r-and-config.instructions.md b/.github/instructions/r-and-config.instructions.md index 3dd00e1..36731b5 100644 --- a/.github/instructions/r-and-config.instructions.md +++ b/.github/instructions/r-and-config.instructions.md @@ -16,10 +16,8 @@ description: "Use when editing R source, Quarto configuration, or GitHub workflo - Run `Rscript -e 'spelling::spell_check_package()'` before finishing changes to `.R` or config files. Fix only errors you introduced, and add legitimate technical terms to `inst/WORDLIST` rather than disabling the check. -- This is a template: every dependency added here lands in every downstream - book, so do not add a new R package or Quarto extension without a clear - reason. Align workflow and render changes with the existing CI patterns - instead of inventing parallel setup. +- Align workflow and render changes with the existing CI patterns instead of + inventing parallel setup. - Do not edit generated files (`README.md` is built from `README.Rmd`; `_site/`, `_freeze/`, and `.quarto/` are build outputs). diff --git a/.github/prompts/quarto-review.prompt.md b/.github/prompts/quarto-review.prompt.md index e54a091..c2a119b 100644 --- a/.github/prompts/quarto-review.prompt.md +++ b/.github/prompts/quarto-review.prompt.md @@ -25,12 +25,10 @@ Review checklist: chunk and referenced with inline R. 5. Citations and attribution are present where adapted content or factual claims appear, and only sources in `references.bib` are used. -6. No new R package or Quarto extension is added without a clear reason (this is - a template --- every dependency lands in every downstream book). -7. No generated files are edited (`README.md` from `README.Rmd`; `_site/`, +6. No generated files are edited (`README.md` from `README.Rmd`; `_site/`, `_freeze/`, `.quarto/`), and spell/link-check failures are fixed at the source (wordlist or content), not suppressed. -8. The author ran the required local validation: +7. The author ran the required local validation: - render of the touched page - `lintr` - `spelling::spell_check_package()` diff --git a/.github/rulesets/README.md b/.github/rulesets/README.md index 614d804..eaebe82 100644 --- a/.github/rulesets/README.md +++ b/.github/rulesets/README.md @@ -26,7 +26,7 @@ Applies to the default branch: - **No force-pushes, no branch deletion.** - **Copilot code review** runs on every push and on draft PRs. - **No mandatory approval by default** --- PRs require no approvals to merge - (`required_approving_review_count: 0`); raise this under Settings → Rules → + (`required_approving_review_count: 0`); raise this under Settings -> Rules -> Rulesets if you want a review gate. - **Bypass** in `pull_request` mode for the Maintain role (role id 2) --- Maintainers can merge pull requests even when the ruleset's PR requirements @@ -35,7 +35,7 @@ Applies to the default branch: ## Editing the ruleset Edit `main.json` here, then run `apply-rulesets.sh` to push the change to -the live repo. Or edit in the GitHub UI (Settings → Rules → Rulesets) and +the live repo. Or edit in the GitHub UI (Settings -> Rules -> Rulesets) and re-export with: ```sh diff --git a/.github/workflows/check-bibliography-dois.yml b/.github/workflows/check-bibliography-dois.yml index ec65a2c..761a283 100644 --- a/.github/workflows/check-bibliography-dois.yml +++ b/.github/workflows/check-bibliography-dois.yml @@ -20,4 +20,4 @@ jobs: check-dois: permissions: contents: read - uses: Morrison-Lab/gha/.github/workflows/check-bibliography-dois.yml@v2 + uses: Morrison-Lab/gha/.github/workflows/check-bibliography-dois.yml@v3 diff --git a/.github/workflows/check-links.yml b/.github/workflows/check-links.yml index 9b2e45b..4669c19 100644 --- a/.github/workflows/check-links.yml +++ b/.github/workflows/check-links.yml @@ -4,7 +4,7 @@ name: Check Links # The reusable workflow reproduces the previous standalone behavior: lychee # link check over .qmd/.md/.html, a PR skip-label ("links checked by hand"), # and auto-filing an issue when links break on main. We pass our repo-local -# lychee.toml so the qwt-specific excludes (e.g. quarto.org) still apply. +# lychee.toml so the cds-specific excludes (e.g. quarto.org) still apply. # See https://github.com/Morrison-Lab/gha for inputs and versioning. on: @@ -26,6 +26,6 @@ jobs: contents: read issues: write pull-requests: read - uses: Morrison-Lab/gha/.github/workflows/check-links.yml@v2 + uses: Morrison-Lab/gha/.github/workflows/check-links.yml@v3 with: lychee-config: lychee.toml diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index 6922ac3..227741e 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -5,7 +5,7 @@ # line, and already skips drafts, Dependabot bumps, fork PRs, and PRs that # edit this workflow file itself (the action can't review its own diff -- # see gha's own comments on the App-token validation 401). This caller only -# supplies qwt's Quarto/R-specific review guidance on top. +# supplies cds's Quarto/R-specific review guidance on top. # See https://github.com/Morrison-Lab/gha for inputs and versioning. # # Secrets are passed explicitly rather than via `secrets: inherit`: GitHub @@ -41,15 +41,15 @@ jobs: contents: read pull-requests: write # post review + inline comments issues: write - id-token: write # required by claude-code-action for the App-token exchange - actions: read # lets the reviewer read CI status - uses: Morrison-Lab/gha/.github/workflows/claude-code-review.yml@v2 + actions: read # lets the reviewer read CI status (github_ci MCP server) + checks: read # required by v3 reusable workflow (gha#833) + uses: Morrison-Lab/gha/.github/workflows/claude-code-review.yml@v3 secrets: CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} # Max-plan OAuth; empty when using API key ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} # direct API key; empty when using OAuth SUBMODULES_TOKEN: ${{ secrets.SUBMODULES_TOKEN }} # optional; latex-macros/ is public, so unset is fine with: - pr-number: ${{ inputs.pr_number }} + pr-number: ${{ github.event.pull_request.number || inputs.pr_number }} checkout-submodules: true # latex-macros/ so the reviewer can read it, not report it "not initialized" # `claude` is included because a remote Claude session pushing a # commit directly to a PR fires `synchronize` with `claude` as the @@ -58,9 +58,8 @@ jobs: # "non-human actor". allowed-bots: 'github-actions[bot],claude' prompt-addendum: | - In addition to the standard checks above, this is the qwt Quarto - website template -- small, prose-heavy, and re-used as a template - for downstream books -- so also prioritize: + In addition to the standard checks above, this is a small, + prose-heavy Quarto website, so also prioritize: 1. **Quarto / prose correctness** - `.qmd` syntax: chunk options use `#|` directives, fenced @@ -73,15 +72,13 @@ jobs: 2. **R code** - Conforms to `.lintr.R` settings (snake_case, line length, etc.). - - No new package dependencies without justification -- every - dependency added here lands in every downstream book. 3. **Build hygiene** - No accidental commits of `_site/`, `_freeze/`, or `.quarto/`. - `README.md` is generated; edits should go to `README.Rmd`. - Bibliography entries in `references.bib` are well-formed BibTeX. - 4. **CI / template impact** + 4. **CI impact** - Workflow changes don't break the `copilot-setup-steps.yml` contract or the publish/preview pipelines. - Spell-check / link-check failures are fixed at the source diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index 68fca5a..33318c5 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -8,7 +8,7 @@ # posting Claude's prose reply when no code was committed, dispatching # claude-code-review.yml on an explicit "@claude review" (including one # absorbed late by the polling loop), and the late-comment dedup / rescue -# machinery (`` marker + 🚀 reaction) that was +# machinery (`` marker + rocket reaction) that was # originally ported FROM this repo's own #73/#90/#95 into gha's claude.yml. # See https://github.com/Morrison-Lab/gha for inputs and versioning. # @@ -53,12 +53,12 @@ jobs: issues: write # so Claude can comment on issues id-token: write actions: write # dispatch claude-code-review.yml via `gh workflow run` - uses: Morrison-Lab/gha/.github/workflows/claude.yml@v2 + uses: Morrison-Lab/gha/.github/workflows/claude.yml@v3 secrets: CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} # Max-plan OAuth; empty when using API key ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} # direct API key; empty when using OAuth SUBMODULES_TOKEN: ${{ secrets.SUBMODULES_TOKEN }} # optional; latex-macros/ is public, so unset is fine WORKFLOW_TOKEN: ${{ secrets.WORKFLOW_TOKEN }} # optional; for editing .github/workflows with: - install-quarto: true # qwt is a Quarto site; Claude may need to render .qmd files + install-quarto: true # cds is a Quarto site; Claude may need to render .qmd files checkout-submodules: true # latex-macros/ (public; no SUBMODULES_TOKEN needed) diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml index e61915d..713c3c8 100644 --- a/.github/workflows/copilot-setup-steps.yml +++ b/.github/workflows/copilot-setup-steps.yml @@ -1,4 +1,4 @@ -# GitHub Copilot Setup Steps for qwt +# GitHub Copilot Setup Steps for cds # # This workflow configures the GitHub Copilot coding agent's environment # by preinstalling R, Quarto, TinyTeX, and system dependencies. @@ -54,7 +54,7 @@ jobs: id: check_label # Pass the expression result through env (GitHub-recommended) rather # than interpolating it directly into the shell, to avoid the - # expression-injection anti-pattern in code that downstream books copy. + # expression-injection anti-pattern. env: EVENT_NAME: ${{ github.event_name }} LABELS_CONTAIN_SKIP: ${{ contains(github.event.pull_request.labels.*.name, 'skip-cp-setup') }} diff --git a/.github/workflows/lint-changed-files.yaml b/.github/workflows/lint-changed-files.yaml index d73178b..7f81d90 100644 --- a/.github/workflows/lint-changed-files.yaml +++ b/.github/workflows/lint-changed-files.yaml @@ -25,6 +25,18 @@ jobs: steps: - uses: actions/checkout@v7 + # `cds` is a self-referential symlink (`cds -> .`, see CLAUDE.md). Left + # in place, `all_files` below would also list every real file a second + # time under `cds/...`, and lintr's exclusions field always resolves + # through normalize_path() (see .lintr.R), which follows symlinks: a + # `cds/` entry in `all_files` normalizes onto the exact + # same path as the real changed file, so `setdiff(all_files, + # changed_files)` -- which only strips the real path, never its + # cds-prefixed alias -- ends up excluding the real changed file too. + # Removing the symlink up front avoids both problems. + - name: Remove self-referential cds symlink before linting + run: rm -f cds + - uses: r-lib/actions/setup-r@v2 with: use-public-rspm: true diff --git a/.github/workflows/lint-project.yaml b/.github/workflows/lint-project.yaml index ad476ff..088f0db 100644 --- a/.github/workflows/lint-project.yaml +++ b/.github/workflows/lint-project.yaml @@ -17,6 +17,17 @@ jobs: steps: - uses: actions/checkout@v7 + # `cds` is a self-referential symlink (`cds -> .`, see CLAUDE.md) that + # lets include paths written as `cds/...` resolve when this repo + # renders standalone. lintr's own directory walk follows symlinks and + # has no config-level way to exclude it without also excluding the + # real files it aliases (normalize_path() collapses the two onto the + # same path -- see .lintr.R). Remove it before linting so lintr never + # walks into it; nothing under it is content distinct from what's + # already linted at the repo root, and this job never renders the site. + - name: Remove self-referential cds symlink before linting + run: rm -f cds + - uses: r-lib/actions/setup-r@v2 with: use-public-rspm: true diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index 778cf79..f7f2ae4 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -52,8 +52,8 @@ jobs: changed-chapters-banner: true highlight-changes: ${{ !contains(github.event.pull_request.labels.*.name, 'no-preview-highlights') }} docx-tracked-changes: true - # The home page plus chapters/, and the slide decks that sit beside them - # (gha's default `chapters/*.html` and `chapters/*.docx` would miss index). + # Pages render at the site root, beside their slide decks + # (gha's default `chapters/*.html` and `chapters/*.docx` would miss them). changed-chapters-glob: '**/*.html' docx-tracked-changes-glob: '**/*.docx' diff --git a/.github/workflows/summary.yml b/.github/workflows/summary.yml index e69db79..ac7d3c4 100644 --- a/.github/workflows/summary.yml +++ b/.github/workflows/summary.yml @@ -20,4 +20,4 @@ jobs: issues: write models: read contents: read - uses: Morrison-Lab/gha/.github/workflows/summary.yml@v2 + uses: Morrison-Lab/gha/.github/workflows/summary.yml@v3 diff --git a/.gitignore b/.gitignore index e16132e..c41c9a2 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,6 @@ # Source HTML partials we intentionally track (not build output). !qwt-reveal-toggle.html !theme-picker.html -!page-navigation.html *_files/ site_libs/ @@ -78,3 +77,6 @@ renv/staging/ # Lychee link checker .lycheecache/ lychee-output/ + +# pak lockfile +.github/pkg.lock diff --git a/.lintr.R b/.lintr.R index d81b0b2..ab5ba3f 100644 --- a/.lintr.R +++ b/.lintr.R @@ -27,4 +27,17 @@ exclusions <- list( `data-raw` = list( pipe_consistency_linter = Inf ) + + # NOTE: `cds` (the self-referential `cds -> .` symlink -- see CLAUDE.md) is + # NOT excluded here on purpose. lintr::lint_dir()/lint_package() resolve + # every exclusion path through normalize_path() (lintr:::normalize_exclusions()), + # which follows symlinks. Because `cds` points at the repo root, ANY + # exclusion naming it -- the directory itself, or any file path under it -- + # normalizes to the exact same absolute path as the real file it aliases, + # so it silently excludes the real file too, not just the symlinked + # duplicate. There is no exclusions-list syntax that can single out the + # duplicate without also matching the original. The actual fix lives in + # the CI workflows (lint-project.yaml, lint-changed-files.yaml), which + # remove the `cds` symlink from the checkout before invoking lintr at all, + # so lintr's own directory walk never sees it and no exclusion is needed. ) diff --git a/AGENTS.md b/AGENTS.md index 8a591ef..4b15393 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,4 +9,9 @@ the ai-config plugin), read before starting work, and follow it alongside this file. This file's own instructions add to those rules, and win only where they are more specific. + +Also follow the [UCD-SERG Lab Manual](https://ucd-serg.github.io/lab-manual/) +(source: ) and, for prose, +[*Principles of Scientific Writing*](https://morrison-lab.github.io/psw/) +(source: ). diff --git a/CLAUDE.md b/CLAUDE.md index f67f4a5..0221ac9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ Project guidance for Claude Code (CLI, IDE, and the GitHub Action). The same con ## Project context -`qwt` (Quarto Website Template) is a template repository for [Quarto](https://quarto.org/) websites maintained by the UCD-SERG lab. Downstream repos are created from this template via the GitHub "Use this template" button, so changes here propagate to new books. +`cds` holds the computational complexity that the Morrison-Lab data science courses use, as [Quarto](https://quarto.org/) fragments. It renders on its own as a website, and course sites such as `lds` link to its pages by URL, so a page's path and its `#id` anchors are an interface: renaming either breaks those links. The scaffolding came from the `qwt` template, with the fragment-library setup of [`pds`](https://github.com/Morrison-Lab/pds). Authoritative style guides: @@ -13,18 +13,39 @@ Authoritative style guides: ## Repository layout -- `index.qmd`, `chapters/`, `appendix-*.qmd` --- Quarto source pages +- `index.qmd`, `appendix-*.qmd`, and the top-level topic pages --- Quarto + source pages. The topic pages are listed in reading order in + `_quarto-website.yml`, in a docked sidebar and in matching navbar + dropdowns. The navbar's `left` menus mirror the sidebar's `contents` + one-for-one, so a page added, renamed, or moved must be edited in both. +- `_subfiles/` --- the fragments the topic pages include (created with the first fragment) - `references.qmd` --- standalone reference page; excluded from the default website render (`!references.qmd` in `_quarto-website.yml`), so it isn't part of the normal site build - `_quarto.yml`, `_quarto-website.yml` --- Quarto project + website config -- `_extensions/` --- vendored Quarto extensions (including `code-language-labels`, which labels each code block with its language in HTML and revealjs output; vendored from [`d-morrison/code-language-labels`](https://github.com/d-morrison/code-language-labels)) +- `cds` --- a self-referential symlink (`cds -> .`), so include paths written + as `cds/...` (the paths a host site that keeps a copy of this repo at its root would use) + also resolve when this repo renders standalone. This creates an unbounded + `cds/cds/cds/...` path loop; `_quarto-website.yml`'s `!cds/` render + exclusion keeps Quarto's own render-list glob from walking into it, but the + symlink is not otherwise sandboxed --- avoid recursive/symlink-following + operations (`find -L`, `rsync -a --copy-links`, unscoped `grep -r`) rooted + at the repo root; scope such commands to real subdirectories instead. + **lintr cannot be pointed away from it via `.lintr.R`'s `exclusions` field**: + `lintr::normalize_exclusions()` always resolves exclusion paths with + `normalize_path()`, which follows symlinks, so any exclusion naming `cds` + (the directory, or a file under it) collapses onto the exact same absolute + path as the real file it aliases and silently excludes that real file too + --- there is no exclusions-list syntax that can single out the symlinked + duplicate without also matching the original. `lint-project.yaml` and + `lint-changed-files.yaml` instead `rm -f cds` right after checkout, before + invoking lintr, so its directory walk never sees the symlink at all. +- `_extensions/` --- vendored Quarto extensions - `latex-macros/` --- git submodule for shortcode/macro definitions (see `.gitmodules`) - `R/`, `man/`, `DESCRIPTION`, `NAMESPACE` --- the project is also a small R package - `references.bib` --- BibTeX bibliography -- `offwhite.scss`, `theme-picker.html` --- the website's Light / Off-white / Parchment / Dark theme dropdown (`theme-picker.html` builds it, `offwhite.scss` styles the two tinted palettes); the choice is saved under `mln-theme`, shared with the slides and with the other sites on this origin -- `page-navigation.html` --- HTML include (`format.html.include-after-body`) that adds floating previous/next arrows in the page margins and fixes navbar highlighting now that Home is in the sidebar; vendored from `Morrison-Lab/lbt` (a private repo, so not linked) -- `styles.css` --- website styling; `styles-reveal.scss`, `qwt-reveal-toggle.html` (the same four-theme dropdown for slides), and the `revealjs-*.lua` filters drive the reveal.js slide output +- `offwhite.scss`, `theme-picker.html` --- the website's Light / Off-white / Parchment / Dark theme dropdown (saved under `mln-theme`, shared with the slides and the other sites on this origin) +- `styles.css` --- website styling; `styles-reveal.scss`, `qwt-reveal-toggle.html` (the same dropdown for slides), and the `revealjs-*.lua` filters drive the reveal.js slide output - `assets/`, `images/` --- static image and asset files (site pages, docs, CI/PR screenshots) - `.github/workflows/` --- CI workflow definitions - `.github/scripts/` --- helper scripts used by workflows @@ -39,7 +60,6 @@ Mirrors [`.github/copilot-instructions.md`](.github/copilot-instructions.md). Ke - **Lists of 3+ items**: use bullet lists rather than comma-separated prose. Always leave a blank line before a markdown bullet list (especially in `.qmd` files). - **Code chunks**: HTML output folds code by default: `_quarto-website.yml` sets `code-fold: true` (with `code-tools: true`, so readers can show all code at once), as rme does. Keep the default when the *output* (plot, table) is the point and the code is incidental. Set `#| code-fold: false` on tutorial code, short examples, code that is the main focus, and chunks where the console output is the main content. - **R style**: respect `.lintr.R`. Run `lintr::lint_dir()` before declaring R changes done. -- **Navigation**: `_quarto-website.yml` defines a docked sidebar because `page-navigation: true` builds its previous/next links from the sidebar. Add each new page to both the navbar and the sidebar, in the same order. Keep Home as the first sidebar entry and keep `page-navigation.html` included, which fixes the navbar highlighting that entry would otherwise break (see the README's "Page navigation" section). - **Quarto chunks**: prefer chunk options as YAML-style `#|` directives, not as inline `r, opt = val` arguments. ## Working in this repo @@ -52,18 +72,6 @@ Mirrors [`.github/copilot-instructions.md`](.github/copilot-instructions.md). Ke - **Other CI checks**: workflows also verify bibliography DOIs (`check-bibliography-dois.yml`) and flag non-standard characters (`check-non-standard-chars.yaml`). Fix the flagged source rather than relaxing the check. - **Dependencies**: Dependabot auto-updates the `latex-macros` submodule and GitHub Actions (see `.github/dependabot.yml`); don't bump those by hand unless a PR needs it. -## ai-config plugin - -`.claude/settings.json` declares the `Morrison-Lab` marketplace (source: -[`Morrison-Lab/ai-config`](https://github.com/Morrison-Lab/ai-config)) and enables -its `ai-config@Morrison-Lab` plugin, along with the `posit-dev-skills` and `sembr` -marketplaces this template also carries, matching -[`Morrison-Lab/qbt`](https://github.com/Morrison-Lab/qbt). Declaring is not -installing: a local session still needs `claude plugin install ai-config@Morrison-Lab` -once. Because this is a template repository, this declaration is copied once into -every repo created from it --- an omission here silently ships to every downstream -site. - ## Pull request expectations - Keep PRs scoped --- bug fixes shouldn't smuggle in refactors. @@ -71,9 +79,20 @@ site. - Don't bypass CI failures (spell check, link check, lint, bibliography DOIs, non-standard chars) --- fix the underlying issue. - Don't commit `_site/` or `_freeze/` changes unless that is genuinely the intent of the PR. +## Shared lab rules + +The lab's cross-repository rules live in [`Morrison-Lab/ai-config`](https://github.com/Morrison-Lab/ai-config), +which `.claude/settings.json` enables as the `ai-config@Morrison-Lab` plugin. +Enabling is not installing: a local session needs `claude plugin install ai-config@Morrison-Lab` once. +When the plugin is not loaded (for example, in a session rooted above this checkout), +read the rules from a clone of ai-config before content work, in particular: + +- `shared/writing/` --- definitions, derivation steps, fact-checking, cross-references, plain prose +- `shared/coding/` --- R style, ASCII punctuation in source +- `skills/quarto-authoring/references/divs-and-spans.md` --- no theorem-type div nested inside another + ## Things to avoid -- Adding new top-level dependencies (R packages, Quarto extensions) without a clear reason; this is a template, so every dependency lands in every downstream book. - Reformatting unrelated files. - Inventing URLs or citations --- only use sources actually present in `references.bib` or explicitly provided. @@ -88,4 +107,9 @@ the ai-config plugin), read before starting work, and follow it alongside this file. This file's own instructions add to those rules, and win only where they are more specific. + +Also follow the [UCD-SERG Lab Manual](https://ucd-serg.github.io/lab-manual/) +(source: ) and, for prose, +[*Principles of Scientific Writing*](https://morrison-lab.github.io/psw/) +(source: ). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3566578..3029632 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,10 +10,10 @@ If you're working on content for this book: 1. **Create a new branch** for your work: ```bash - git checkout -b chapter/your-topic + git checkout -b page/your-topic ``` -2. **Edit or create `.qmd` files** for your chapter +2. **Edit or create `.qmd` files** for your topic page 3. **Preview your changes** locally: ```bash @@ -23,12 +23,12 @@ If you're working on content for this book: 4. **Commit your changes**: ```bash git add . - git commit -m "Add chapter on your topic" + git commit -m "Add a page on your topic" ``` 5. **Push and create a pull request**: ```bash - git push origin chapter/your-topic + git push origin page/your-topic ``` ### Content guidelines diff --git a/DESCRIPTION b/DESCRIPTION index 84b6733..b26efca 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,16 +1,16 @@ -Package: qwt -Title: Quarto Website Template +Package: cds +Title: Computational Complexity for Data Science Version: 0.1.0 Authors@R: - person("Your Name", email = "your.email@example.com", role = c("aut", "cre")) -Description: A template for creating websites with Quarto. Includes support for - multiple output formats including HTML, DOCX, RevealJS slides, and PDF handouts. + person("Ezra", "Morrison", email = "d.ezra.morrison@gmail.com", role = c("aut", "cre")) +Description: Computational complexity for data science courses, written as + Quarto fragments that course sites link to. License: MIT + file LICENSE Encoding: UTF-8 Roxygen: list(markdown = TRUE) RoxygenNote: 7.3.3 -URL: https://github.com/UCD-SERG/qwt -BugReports: https://github.com/UCD-SERG/qwt/issues +URL: https://github.com/Morrison-Lab/cds +BugReports: https://github.com/Morrison-Lab/cds/issues Depends: R (>= 4.1.0) Suggests: diff --git a/R/qwt-package.R b/R/cds-package.R similarity index 100% rename from R/qwt-package.R rename to R/cds-package.R diff --git a/README.Rmd b/README.Rmd index 38d41fa..5d80d17 100644 --- a/README.Rmd +++ b/README.Rmd @@ -4,401 +4,40 @@ output: github_document -```{r, include = FALSE} -knitr::opts_chunk$set( - collapse = TRUE, - comment = "#>" -) -``` - -# qwt ([Q]{.underline}uarto [W]{.underline}ebsite [T]{.underline}emplate) +# cds (Computational Complexity for Data Science) -A template repository for creating websites with [Quarto](https://quarto.org/). -This template provides everything you need to quickly start writing your own website. - -## Features - -- 🌐 **Website-ready structure** with sample chapters and references -- 🎨 **Customizable themes** supporting light and dark modes -- 🚀 **Automatic deployment** to GitHub Pages via GitHub Actions -- 🔗 **Automated link checking** to ensure all URLs are reachable -- 📄 **Multiple output formats** including HTML, PDF, RevealJS slides, and DOCX -- 📑 **Bibliography support** with BibTeX integration -- 🔢 **Automatic numbering** of sections and cross-references -- 💅 **Custom CSS** for styling your website -- 🔍 **PR Preview** with change highlighting for pull requests -- ✅ **Automated checks** including spell checking and linting -- 🤖 **GitHub Copilot integration** with custom setup steps -- 📝 **AI-powered issue summaries** for new issues - -## Quick Start - -### Using this template - -1. Click the "Use this template" button at the top of this repository -2. Name your new repository and create it -3. Clone your new repository to your local machine - -```bash -git clone https://github.com/YOUR-USERNAME/YOUR-REPO.git -cd YOUR-REPO -``` - -### Prerequisites - -You need to have [Quarto](https://quarto.org/) installed. Download it from [quarto.org/docs/get-started](https://quarto.org/docs/get-started/). - -To verify Quarto is installed: - -```bash -quarto --version -``` - -**Minimum version:** This template uses Quarto's [`llms-txt`](https://quarto.org/docs/websites/website-llms.html) website option, which requires **Quarto 1.9.36 or newer** (the version this template was verified on). Earlier Quarto versions do not recognize `llms-txt` as a valid `website:` property and will produce a schema error when rendering. - -### Customize your website +`cds` collects the computational complexity that data science courses use, +as [Quarto](https://quarto.org/) fragments. +It renders on its own as a website, +and course sites link to its pages by URL. -1. **Edit `_quarto-website.yml`** to update: +## Using these notes in another site - - Website title and site URL - - Repository URL - - Navigation menu items - - Theme and styling options +Link to the pages by URL. +A host site that keeps a copy of this repository at its root, named `cds`, +can also include fragments with paths that start with `cds/`. -2. **Modify `index.qmd`** to create your website's homepage +Quarto resolves `@id` cross-references only within one rendered page, +so a host site that links to a result here +uses an explicit link to the page and anchor. -3. **Edit or create pages** (`.qmd` files): +## Building the site - - Modify files in the `chapters/` directory as needed - - Create new pages and add them to the navigation menu and the sidebar in `_quarto-website.yml` +This repository uses the `latex-macros` submodule for its LaTeX macros, +so clone it with submodules: -4. **Add references** to `references.bib` in BibTeX format - -5. **Customize styling** in `styles.css` - -## Building the website - -### Local preview - -To preview your website with live reload during development: - -```bash +```sh +git clone --recurse-submodules https://github.com/Morrison-Lab/cds.git +cd cds quarto preview ``` -This will open your website in a web browser and automatically refresh when you make changes. - -### Render the website - -To render the complete website: - -```bash -quarto render -``` - -The output will be generated in the `_site/` directory. - -### Multiple output formats - -This template supports multiple output formats in a single render: - -- **Website pages** (`.html`) -- **RevealJS slides** (`-slides.html`) -- **PDF handouts** (`-handout.pdf`) -- **DOCX documents** (`.docx`) - -## Publishing to GitHub Pages - -This template includes a GitHub Actions workflow (`.github/workflows/publish.yml`) that automatically builds and publishes your website to GitHub Pages when you push to the main branch. - -### Setup steps: - -1. **Enable GitHub Pages** in your repository: - - Go to Settings → Pages - - Under "Build and deployment", set Source to "GitHub Actions" - -2. **Push to main branch**: - ```bash - git add . - git commit -m "Initial website setup" - git push origin main - ``` - -3. **Apply branch rulesets** (requires admin access): - ```bash - .github/scripts/apply-rulesets.sh - ``` - This protects `main` against direct pushes / force-pushes / deletion and - requires a PR to merge. See `.github/rulesets/README.md` for details. - -4. **Wait for the workflow** to complete (check the Actions tab) - -5. **Access your website** at: `https://YOUR-USERNAME.github.io/YOUR-REPO/` - -## GitHub Actions Workflows - -This template includes several automated workflows to enhance your development experience: - -### 🚀 Publish Workflow (`publish.yml`) - -Automatically builds and deploys your website to GitHub Pages when you push to the main branch. It also saves the Quarto freezer (`_freeze`) cache for reuse by preview builds. - -**Triggers:** Push to main branch, manual dispatch - -### 🔍 PR Preview Workflows (`preview.yml`, `preview-deploy.yml`) - -`preview.yml` builds the preview read-only and `preview-deploy.yml` publishes it to `gh-pages` and comments the link. -Both call the shared workflows in [`Morrison-Lab/gha`](https://github.com/Morrison-Lab/gha), and `publish.yml` calls its `quarto-publish.yml`. -Previews start working once `preview-deploy.yml` is on `main`. - -Creates a preview deployment for pull requests with: - -- Change detection and highlighting -- DOCX files with tracked changes -- Visual indicators for modified chapters -- Banner showing what changed in the PR -- Reuse of the Quarto freezer cache with updates saved per PR commit - -**Triggers:** PR opened, reopened, synchronized, closed, labeled, or unlabeled - -A preview renders every format `_quarto.yml` declares (HTML, slides, PDF handouts and Word), so no label is needed for those. - -**Labels:** - -- Add `no-preview-highlights` to disable change highlighting if it's glitchy -- Add `clear freezer` to render without restoring the `_freeze` cache (a label with this exact name, space included, must exist on the repository before it can be applied) - -### ✅ Spell Check Workflow (`check-spelling.yaml`) - -Runs automated spell checking on pushes and pull requests to maintain content quality. - -**Triggers:** Push to main, pull requests - -### 📋 Lint Project Workflow (`lint-project.yaml`) - -Checks R code style and quality using the lintr package. - -**Triggers:** Push to main/master, pull requests - -**Note:** Only runs if your project contains R code. - -### 🤖 Copilot Setup Steps (`copilot-setup-steps.yml`) - -Configures the GitHub Copilot coding agent's environment for: - -- Quarto -- TinyTeX -- Optional GitHub CLI authentication for - `https://github.com/Morrison-Lab/macros` (via the `MACROS_REPO_PAT` - repository or organization Actions secret; includes a write - permission check during setup) - -**Triggers:** Workflow dispatch, changes to the setup file - -### 📝 Issue Summary Workflow (`summary.yml`) - -Automatically generates AI-powered summaries for newly opened issues. - -**Triggers:** New issue opened - -**Permissions required:** The `models: read` permission for AI inference - -### 📚 Check Bibliography DOIs Workflow (`check-bibliography-dois.yml`) - -Validates that all books and articles in bibliography files meet DOI requirements: - -- Every book and article must have a DOI field -- Every DOI must resolve to a valid URL -- Reference information is checked against DOI metadata for consistency - -**Triggers:** Push to main, pull requests, manual dispatch - -**Note:** This helps maintain high-quality bibliographic references and ensures all citations are properly traceable. - -## Project Structure - -``` -. -├── _quarto.yml # Main configuration file -├── _quarto-website.yml # Website-specific configuration -├── index.qmd # Website homepage -├── chapters/ # Chapter files -│ ├── chapter1.qmd # Sample chapter 1 -│ └── chapter2.qmd # Sample chapter 2 -├── references.qmd # References page -├── references.bib # BibTeX bibliography -├── styles.css # Custom CSS styles -├── page-navigation.html # Previous/next margin arrows and navbar highlighting -├── lychee.toml # Link checker configuration -├── .gitignore # Git ignore file -├── LICENSE # CC0 1.0 Universal License -├── README.md # This file -├── latex-macros/ # Git submodule: Morrison-Lab/macros -└── .github/ - ├── rulesets/ # Branch ruleset definitions - │ ├── main.json # Default branch ruleset - │ └── README.md # Ruleset documentation - ├── scripts/ # Scripts for workflows - │ ├── add-page-banners.py # Per-page preview banners (gha#1025) - │ └── apply-rulesets.sh # Apply branch rulesets to a new repo - └── workflows/ # GitHub Actions workflows - ├── publish.yml # Build and deploy to GitHub Pages - ├── preview.yml # PR preview with change highlighting - ├── preview-deploy.yml # Publish the PR preview to gh-pages - ├── check-spelling.yaml # Spell checking - ├── lint-project.yaml # R code linting - ├── copilot-setup-steps.yml # GitHub Copilot setup - ├── summary.yml # AI-powered issue summaries - ├── check-links.yml # URL reachability checker workflow - └── check-bibliography-dois.yml # Bibliography DOI validation -``` - -## Automated Workflows - -This template includes two GitHub Actions workflows: - -### Publishing Workflow (`publish.yml`) -Automatically builds and deploys your website to GitHub Pages when you push to the main branch. - -### Link Checker Workflow (`check-links.yml`) -Automatically checks that all URLs in your website are reachable: - -- **Runs on**: Push to main, pull requests, weekly schedule (Mondays at 9:00 UTC), and manual trigger -- **Checks**: All links in `.qmd`, `.md`, and `.html` files -- **Reports**: Workflow fails if broken links are detected. Check the workflow logs for details on which links are broken. -- **Configuration**: Customize behavior in `lychee.toml` -- **Manual override**: Add the `links checked by hand` label to a PR to skip the automated link check - -To manually trigger the link checker: - -1. Go to the Actions tab in your repository -2. Select "Check Links" workflow -3. Click "Run workflow" - -## Writing Content - -Quarto uses markdown with extensions. Here are some quick tips: - -### Headings - -```markdown -# Chapter Title -## Section -### Subsection -``` - -### Code blocks - -````markdown -```python -print("Hello, World!") -``` -```` - -### Math equations - -```markdown -Inline: $E = mc^2$ - -Display: -$$ -\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} -$$ -``` - -### Citations - -Reference a citation: `@citationkey` - -### Cross-references - -Reference figures, tables, and sections using labels: - -```markdown -See @fig-example for details. -``` - -For more details, see the [Quarto documentation](https://quarto.org/docs/guide/). - -## Customization - -### Changing themes - -Edit the `format.html.theme` section in `_quarto-website.yml`: - -```yaml -format: - html: - theme: - light: cosmo # Try: cosmo, flatly, litera, minty, etc. - dark: darkly # Try: darkly, cyborg, slate, superhero, etc. -``` - -### Adding pages - -1. Create a new `.qmd` file (e.g., `chapters/chapter3.qmd`) -2. Add it to the navigation menu and to the sidebar in `_quarto-website.yml`: - -```yaml -website: - navbar: - left: - - text: "Chapters" - menu: - - text: "Chapter 1: Introduction" - href: chapters/chapter1.qmd - - text: "Chapter 2: Advanced Topics" - href: chapters/chapter2.qmd - - text: "Chapter 3: Your New Chapter" - href: chapters/chapter3.qmd - sidebar: - contents: - - section: "Chapters" - contents: - - chapters/chapter1.qmd - - chapters/chapter2.qmd - - chapters/chapter3.qmd -``` - -### Page navigation - -`website.page-navigation: true` adds previous and next links at the foot of each page. -Quarto builds those links from the sidebar, not the navbar -([Quarto docs](https://quarto.org/docs/websites/website-navigation.html#page-navigation)), -so the template defines a docked sidebar in the same order as the navbar. -Keep the two in sync: the sidebar order is the reading order. - -The sidebar starts with Home, so the previous/next chain starts at the home page. -Quarto highlights the first navbar link whose target appears anywhere in the sidebar, -so a Home entry in the sidebar would highlight "Home" in the navbar on every page. - -`page-navigation.html`, included under `format.html` with `include-after-body`, -corrects the highlighting: -it highlights the navbar link (or dropdown) for the current page. -It also adds floating previous/next arrows in the page margins. -The arrows sit in the space beside the page text and are hidden on narrow screens and in print. - -### Custom CSS - -Add your custom styles to `styles.css`. These will override the default theme styles. - -## License - -This template is released under the [CC0 1.0 Universal License](LICENSE), which means you can freely use, modify, and distribute it without any restrictions. - -## Acknowledgments - -This template is based on the structure of the [UCD-SERG Lab Manual](https://github.com/UCD-SERG/lab-manual), which was adapted from the [Benjamin-Chung Lab Manual](https://jadebc.github.io/lab-manual/index.html). - -## Support - -- [Quarto Documentation](https://quarto.org/docs/guide/) -- [Quarto Community](https://github.com/quarto-dev/quarto-cli/discussions) -- [GitHub Pages Documentation](https://docs.github.com/en/pages) - -## Contributing +## Provenance -Feel free to open issues or submit pull requests to improve this template! +The site scaffolding comes from the +[qwt](https://github.com/Morrison-Lab/qwt) Quarto website template, +with the fragment-library setup of +[pds](https://github.com/Morrison-Lab/pds). diff --git a/README.md b/README.md index 26962de..22de2d4 100644 --- a/README.md +++ b/README.md @@ -1,443 +1,39 @@ - -# qwt (Quarto Website Template) +# cds (Computational Complexity for Data Science) -A template repository for creating websites with -[Quarto](https://quarto.org/). This template provides everything you -need to quickly start writing your own website. - -## Features - -- 🌐 **Website-ready structure** with sample chapters and references -- 🎨 **Customizable themes** supporting light and dark modes -- 🚀 **Automatic deployment** to GitHub Pages via GitHub Actions -- 🔗 **Automated link checking** to ensure all URLs are reachable -- 📄 **Multiple output formats** including HTML, PDF, RevealJS slides, - and DOCX -- 📑 **Bibliography support** with BibTeX integration -- 🔢 **Automatic numbering** of sections and cross-references -- 💅 **Custom CSS** for styling your website -- 🔍 **PR Preview** with change highlighting for pull requests -- ✅ **Automated checks** including spell checking and linting -- 🤖 **GitHub Copilot integration** with custom setup steps -- 📝 **AI-powered issue summaries** for new issues - -## Quick Start - -### Using this template - -1. Click the "Use this template" button at the top of this repository -2. Name your new repository and create it -3. Clone your new repository to your local machine - -``` bash -git clone https://github.com/YOUR-USERNAME/YOUR-REPO.git -cd YOUR-REPO -``` - -### Prerequisites - -You need to have [Quarto](https://quarto.org/) installed. Download it -from -[quarto.org/docs/get-started](https://quarto.org/docs/get-started/). - -To verify Quarto is installed: - -``` bash -quarto --version -``` - -**Minimum version:** This template uses Quarto's -[`llms-txt`](https://quarto.org/docs/websites/website-llms.html) website -option, which requires **Quarto 1.9.36 or newer** (the version this -template was verified on). Earlier Quarto versions do not recognize -`llms-txt` as a valid `website:` property and will produce a schema -error when rendering. - -### Customize your website - -1. **Edit `_quarto-website.yml`** to update: +`cds` collects the computational complexity that data science courses use, +as [Quarto](https://quarto.org/) fragments. +It renders on its own as a website, +and course sites link to its pages by URL. - - Website title and site URL - - Repository URL - - Navigation menu items - - Theme and styling options +## Using these notes in another site -2. **Modify `index.qmd`** to create your website's homepage +Link to the pages by URL. +A host site that keeps a copy of this repository at its root, named `cds`, +can also include fragments with paths that start with `cds/`. -3. **Edit or create pages** (`.qmd` files): +Quarto resolves `@id` cross-references only within one rendered page, +so a host site that links to a result here +uses an explicit link to the page and anchor. - - Modify files in the `chapters/` directory as needed - - Create new pages and add them to the navigation menu and the - sidebar in `_quarto-website.yml` +## Building the site -4. **Add references** to `references.bib` in BibTeX format +This repository uses the `latex-macros` submodule for its LaTeX macros, +so clone it with submodules: -5. **Customize styling** in `styles.css` - -## Building the website - -### Local preview - -To preview your website with live reload during development: - -``` bash +```sh +git clone --recurse-submodules https://github.com/Morrison-Lab/cds.git +cd cds quarto preview ``` -This will open your website in a web browser and automatically refresh -when you make changes. - -### Render the website - -To render the complete website: - -``` bash -quarto render -``` - -The output will be generated in the `_site/` directory. - -### Multiple output formats - -This template supports multiple output formats in a single render: - -- **Website pages** (`.html`) -- **RevealJS slides** (`-slides.html`) -- **PDF handouts** (`-handout.pdf`) -- **DOCX documents** (`.docx`) - -## Publishing to GitHub Pages - -This template includes a GitHub Actions workflow -(`.github/workflows/publish.yml`) that automatically builds and -publishes your website to GitHub Pages when you push to the main branch. - -### Setup steps: - -1. **Enable GitHub Pages** in your repository: - - - Go to Settings → Pages - - Under "Build and deployment", set Source to "GitHub Actions" - -2. **Push to main branch**: - - ``` bash - git add . - git commit -m "Initial website setup" - git push origin main - ``` - -3. **Apply branch rulesets** (requires admin access): - - ``` bash - .github/scripts/apply-rulesets.sh - ``` - - This protects `main` against direct pushes / force-pushes / deletion - and requires a PR to merge. See `.github/rulesets/README.md` for - details. - -4. **Wait for the workflow** to complete (check the Actions tab) - -5. **Access your website** at: - `https://YOUR-USERNAME.github.io/YOUR-REPO/` - -## GitHub Actions Workflows - -This template includes several automated workflows to enhance your -development experience: - -### 🚀 Publish Workflow (`publish.yml`) - -Automatically builds and deploys your website to GitHub Pages when you -push to the main branch. It also saves the Quarto freezer (`_freeze`) -cache for reuse by preview builds. - -**Triggers:** Push to main branch, manual dispatch - -### 🔍 PR Preview Workflows (`preview.yml`, `preview-deploy.yml`) - -`preview.yml` builds the preview read-only and `preview-deploy.yml` -publishes it to `gh-pages` and comments the link. -Both call the shared workflows in -[`Morrison-Lab/gha`](https://github.com/Morrison-Lab/gha), and -`publish.yml` calls its `quarto-publish.yml`. -Previews start working once `preview-deploy.yml` is on `main`. - -Creates a preview deployment for pull requests with: - -- Change detection and highlighting -- DOCX files with tracked changes -- Visual indicators for modified chapters -- Banner showing what changed in the PR -- Reuse of the Quarto freezer cache with updates saved per PR commit - -**Triggers:** PR opened, reopened, synchronized, closed, labeled, or -unlabeled - -A preview renders every format `_quarto.yml` declares (HTML, slides, -PDF handouts and Word), so no label is needed for those. - -**Labels:** - -- Add `no-preview-highlights` to disable change highlighting if it's - glitchy -- Add `clear freezer` to render without restoring the `_freeze` cache (a - label with this exact name, space included, must exist on the - repository before it can be applied) - -### ✅ Spell Check Workflow (`check-spelling.yaml`) - -Runs automated spell checking on pushes and pull requests to maintain -content quality. - -**Triggers:** Push to main, pull requests - -### 📋 Lint Project Workflow (`lint-project.yaml`) - -Checks R code style and quality using the lintr package. - -**Triggers:** Push to main/master, pull requests - -**Note:** Only runs if your project contains R code. - -### 🤖 Copilot Setup Steps (`copilot-setup-steps.yml`) - -Configures the GitHub Copilot coding agent's environment for: - -- Quarto -- TinyTeX -- Optional GitHub CLI authentication for - `https://github.com/Morrison-Lab/macros` (via the `MACROS_REPO_PAT` - repository or organization Actions secret; includes a write permission - check during setup) - -**Triggers:** Workflow dispatch, changes to the setup file - -### 📝 Issue Summary Workflow (`summary.yml`) - -Automatically generates AI-powered summaries for newly opened issues. - -**Triggers:** New issue opened - -**Permissions required:** The `models: read` permission for AI inference - -### 📚 Check Bibliography DOIs Workflow (`check-bibliography-dois.yml`) - -Validates that all books and articles in bibliography files meet DOI -requirements: - -- Every book and article must have a DOI field -- Every DOI must resolve to a valid URL -- Reference information is checked against DOI metadata for consistency - -**Triggers:** Push to main, pull requests, manual dispatch - -**Note:** This helps maintain high-quality bibliographic references and -ensures all citations are properly traceable. - -## Project Structure - - . - ├── _quarto.yml # Main configuration file - ├── _quarto-website.yml # Website-specific configuration - ├── index.qmd # Website homepage - ├── chapters/ # Chapter files - │ ├── chapter1.qmd # Sample chapter 1 - │ └── chapter2.qmd # Sample chapter 2 - ├── references.qmd # References page - ├── references.bib # BibTeX bibliography - ├── styles.css # Custom CSS styles - ├── page-navigation.html # Previous/next margin arrows and navbar highlighting - ├── lychee.toml # Link checker configuration - ├── .gitignore # Git ignore file - ├── LICENSE # CC0 1.0 Universal License - ├── README.md # This file - ├── latex-macros/ # Git submodule: Morrison-Lab/macros - └── .github/ - ├── rulesets/ # Branch ruleset definitions - │ ├── main.json # Default branch ruleset - │ └── README.md # Ruleset documentation - ├── scripts/ # Scripts for workflows - │ ├── add-page-banners.py # Per-page preview banners (gha#1025) - │ └── apply-rulesets.sh # Apply branch rulesets to a new repo - └── workflows/ # GitHub Actions workflows - ├── publish.yml # Build and deploy to GitHub Pages - ├── preview.yml # PR preview with change highlighting - ├── preview-deploy.yml # Publish the PR preview to gh-pages - ├── check-spelling.yaml # Spell checking - ├── lint-project.yaml # R code linting - ├── copilot-setup-steps.yml # GitHub Copilot setup - ├── summary.yml # AI-powered issue summaries - ├── check-links.yml # URL reachability checker workflow - └── check-bibliography-dois.yml # Bibliography DOI validation - -## Automated Workflows - -This template includes two GitHub Actions workflows: - -### Publishing Workflow (`publish.yml`) - -Automatically builds and deploys your website to GitHub Pages when you -push to the main branch. - -### Link Checker Workflow (`check-links.yml`) - -Automatically checks that all URLs in your website are reachable: - -- **Runs on**: Push to main, pull requests, weekly schedule (Mondays at - 9:00 UTC), and manual trigger -- **Checks**: All links in `.qmd`, `.md`, and `.html` files -- **Reports**: Workflow fails if broken links are detected. Check the - workflow logs for details on which links are broken. -- **Configuration**: Customize behavior in `lychee.toml` -- **Manual override**: Add the `links checked by hand` label to a PR to - skip the automated link check - -To manually trigger the link checker: - -1. Go to the Actions tab in your repository -2. Select "Check Links" workflow -3. Click "Run workflow" - -## Writing Content - -Quarto uses markdown with extensions. Here are some quick tips: - -### Headings - -``` markdown -# Chapter Title -## Section -### Subsection -``` - -### Code blocks - -```` markdown -```python -print("Hello, World!") -``` -```` - -### Math equations - -``` markdown -Inline: $E = mc^2$ - -Display: -$$ -\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} -$$ -``` - -### Citations - -Reference a citation: `@citationkey` - -### Cross-references - -Reference figures, tables, and sections using labels: - -``` markdown -See @fig-example for details. -``` - -For more details, see the [Quarto -documentation](https://quarto.org/docs/guide/). - -## Customization - -### Changing themes - -Edit the `format.html.theme` section in `_quarto-website.yml`: - -``` yaml -format: - html: - theme: - light: cosmo # Try: cosmo, flatly, litera, minty, etc. - dark: darkly # Try: darkly, cyborg, slate, superhero, etc. -``` - -### Adding pages - -1. Create a new `.qmd` file (e.g., `chapters/chapter3.qmd`) -2. Add it to the navigation menu and to the sidebar in - `_quarto-website.yml`: - -``` yaml -website: - navbar: - left: - - text: "Chapters" - menu: - - text: "Chapter 1: Introduction" - href: chapters/chapter1.qmd - - text: "Chapter 2: Advanced Topics" - href: chapters/chapter2.qmd - - text: "Chapter 3: Your New Chapter" - href: chapters/chapter3.qmd - sidebar: - contents: - - section: "Chapters" - contents: - - chapters/chapter1.qmd - - chapters/chapter2.qmd - - chapters/chapter3.qmd -``` - -### Page navigation - -`website.page-navigation: true` adds previous and next links at the foot -of each page. Quarto builds those links from the sidebar, not the navbar -([Quarto -docs](https://quarto.org/docs/websites/website-navigation.html#page-navigation)), -so the template defines a docked sidebar in the same order as the -navbar. Keep the two in sync: the sidebar order is the reading order. - -The sidebar starts with Home, so the previous/next chain starts at the -home page. Quarto highlights the first navbar link whose target appears -anywhere in the sidebar, so a Home entry in the sidebar would highlight -"Home" in the navbar on every page. - -`page-navigation.html`, included under `format.html` with -`include-after-body`, corrects the highlighting: it highlights the -navbar link (or dropdown) for the current page. It also adds floating -previous/next arrows in the page margins. The arrows sit in the space -beside the page text and are hidden on narrow screens and in print. - -### Custom CSS - -Add your custom styles to `styles.css`. These will override the default -theme styles. - -## License - -This template is released under the [CC0 1.0 Universal -License](LICENSE), which means you can freely use, modify, and -distribute it without any restrictions. - -## Acknowledgments - -This template is based on the structure of the [UCD-SERG Lab -Manual](https://github.com/UCD-SERG/lab-manual), which was adapted from -the [Benjamin-Chung Lab -Manual](https://jadebc.github.io/lab-manual/index.html). - -## Support - -- [Quarto Documentation](https://quarto.org/docs/guide/) -- [Quarto - Community](https://github.com/quarto-dev/quarto-cli/discussions) -- [GitHub Pages Documentation](https://docs.github.com/en/pages) - -## Contributing +## Provenance -Feel free to open issues or submit pull requests to improve this -template! +The site scaffolding comes from the +[qwt](https://github.com/Morrison-Lab/qwt) Quarto website template, +with the fragment-library setup of +[pds](https://github.com/Morrison-Lab/pds). diff --git a/_quarto-website.yml b/_quarto-website.yml index d7c7efa..5d42b6b 100644 --- a/_quarto-website.yml +++ b/_quarto-website.yml @@ -3,7 +3,6 @@ project: output-dir: _site render: - "*.qmd" - - "chapters/*.qmd" - "!README.md" - "!appendix-document-metadata.qmd" - "!references.qmd" @@ -12,58 +11,38 @@ project: # directly: macros-table.qmd uses DT::datatable() (an HTML widget) that # errors when the project also renders to PDF. - "!latex-macros/" + - "!cds/" website: - title: "Quarto Website Template" - site-url: https://ucd-serg.github.io/qwt/ - description: "A template for creating websites with Quarto" + title: "Computational Complexity for Data Science" + site-url: https://morrison-lab.github.io/cds/ + description: "Computational complexity for data science courses" # https://quarto.org/docs/websites/website-llms.html --- use `llms-txt:`, not `llms:` (schema error) llms-txt: true page-footer: center: "Built with [Quarto](https://quarto.org/)" back-to-top-navigation: true - # Previous/next links at the foot of each page follow the sidebar's order, - # so page-navigation does nothing without the sidebar below. - # https://quarto.org/docs/websites/website-navigation.html#page-navigation page-navigation: true reader-mode: true - repo-url: https://github.com/UCD-SERG/qwt + repo-url: https://github.com/Morrison-Lab/cds repo-actions: [edit, issue, source] navbar: - left: - - text: "Home" - href: index.qmd - - text: "Chapters" - menu: - - text: "Chapter 1: Introduction" - href: chapters/chapter1.qmd - - text: "Chapter 2: Advanced Topics" - href: chapters/chapter2.qmd - - text: "Theorem Examples" - href: chapters/theorem-examples.qmd + # Add a `left:` list of menus here that mirrors the sidebar's `contents` + # one-for-one (same groups, same names, same order, same pages), as pds + # does, once the first topic pages exist. The site title (which links + # home), search, and the GitHub link round out the navbar. + search: true right: - icon: github - href: https://github.com/UCD-SERG/qwt + href: https://github.com/Morrison-Lab/cds aria-label: GitHub - - # The sidebar sets the previous/next page links, so keep it in the same - # order as the navbar and add each new page to both. - # Home is the first entry, so the chain starts at the home page. - # Quarto highlights the first navbar link whose target appears anywhere in - # the sidebar, which would be "Home" on every page; - # page-navigation.html (see `include-after-body` under `format.html`) - # corrects that. sidebar: + # Topic pages in reading order, grouped into sections, each group + # depending only on earlier ones; the navbar's `left` menus mirror it. + # There is no Home entry: the navbar title already links to the home page. style: docked - search: false # the navbar already has search - contents: - - text: "Home" - href: index.qmd - - section: "Chapters" - contents: - - chapters/chapter1.qmd - - chapters/chapter2.qmd - - chapters/theorem-examples.qmd + search: false + contents: [] callouty-theorem: thm: @@ -166,10 +145,6 @@ format: dark: darkly # Replaces Quarto's two-way toggle with a Light / Off-white / Parchment / Dark dropdown. include-in-header: theme-picker.html - # Floating previous/next arrows in the page margins, and navbar - # highlighting for the current page (needed because Home is in the - # sidebar). - include-after-body: page-navigation.html css: styles.css toc: true anchor-sections: true @@ -178,7 +153,7 @@ format: code-fold: true code-tools: true code-link: true - code-summary: "Show R code" + code-summary: "Show code" highlight-style: arrow lightbox: true link-external-icon: true @@ -218,7 +193,7 @@ format: margin: 0.0 code-fold: true code-link: true - code-summary: "[R code]" + code-summary: "[Code]" auto-stretch: true fig-height: 5 fig-width: 7 diff --git a/appendix-document-metadata.qmd b/appendix-document-metadata.qmd index a746254..4088adc 100644 --- a/appendix-document-metadata.qmd +++ b/appendix-document-metadata.qmd @@ -1,6 +1,6 @@ ::: {.content-visible when-format="docx"} -# Document Generation Metadata {.unnumbered} +## Document Generation Metadata {.unnumbered} This document was generated from the following git commit: diff --git a/assets/pr-screenshots/theorem-examples.png b/assets/pr-screenshots/theorem-examples.png deleted file mode 100644 index a3f5587..0000000 Binary files a/assets/pr-screenshots/theorem-examples.png and /dev/null differ diff --git a/cds b/cds new file mode 120000 index 0000000..945c9b4 --- /dev/null +++ b/cds @@ -0,0 +1 @@ +. \ No newline at end of file diff --git a/chapters/chapter1.qmd b/chapters/chapter1.qmd deleted file mode 100644 index f94b11a..0000000 --- a/chapters/chapter1.qmd +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "Chapter 1: Introduction" -format: - html: default - revealjs: - output-file: chapter1-slides.html - pdf: - output-file: chapter1-handout.pdf - docx: - output-file: chapter1.docx ---- - -This is the first chapter of your website. Replace this content with your own. - -# Section 1.1 {#sec-1.1} - -Add your content here. - -## Subsection 1.1.1 - -You can include: - -- **Lists** like this one -- *Italic* and **bold** text -- `Code snippets` -- Links: [Quarto Documentation](https://quarto.org/) - -# Section 1.2 - -You can also include code blocks: - -```python -# Example Python code -def hello_world(): - print("Hello, World!") - -hello_world() -``` - -Or R code: - -```r -# Example R code -library(ggplot2) - -ggplot(mtcars, aes(x = wt, y = mpg)) + - geom_point() + - theme_minimal() -``` - -# Section 1.3 - -Include citations using `@citationkey` format, which references entries in your `references.bib` file. - -You can also add theorem-style divs: - -::: {#thm-sample .thm} -This is a sample theorem block with an ID. -::: - -I'm adding some new content here: - -```{r} -1 + 1 -``` - - -# References {.unnumbered} - -::: {#refs} -::: diff --git a/chapters/chapter2.qmd b/chapters/chapter2.qmd deleted file mode 100644 index 9749b54..0000000 --- a/chapters/chapter2.qmd +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "Chapter 2: Advanced Topics" -format: - html: default - revealjs: - output-file: chapter2-slides.html - pdf: - output-file: chapter2-handout.pdf - docx: - output-file: chapter2.docx ---- - -This is the second chapter. Continue building your website with more chapters. - -# Mathematical Equations - -You can include mathematical equations using LaTeX syntax: - -Inline equation: $E = mc^2$ - -Display equation: - -$$ -\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi} -$$ {#eq-gaussian-integral} - -Direct link to the equation anchor: -See @eq-gaussian-integral. - -# Tables - -| Column 1 | Column 2 | Column 3 | -|----------|----------|----------| -| Data 1 | Data 2 | Data 3 | -| Data 4 | Data 5 | Data 6 | - -: Example table caption {#tbl-example} - -# Figures - -You can include images by placing them in the `images/` directory: - -```markdown -![Example image caption](images/your-image.png){#fig-example} -``` - -Then reference the figure in text using `@fig-example`. - -# Callouts - -::: {.callout-note} -This is a note callout. Use it to highlight important information. -::: - -::: {.callout-tip} -This is a tip callout. Share helpful suggestions with your readers. -::: - -::: {.callout-warning} -This is a warning callout. Alert readers to potential issues. -::: - -::: {.callout-important} -This is an important callout. Emphasize critical information. -::: - -# Theorem-like Divs - -::: {#lem-sample .lem} -This is a sample lemma-style div using the standard class name `lem`. -::: - -::: {#exm-sample .exm} -This is a sample example-style div using the standard class name `exm`. -::: - -# References {.unnumbered} - -::: {#refs} -::: diff --git a/chapters/theorem-examples.qmd b/chapters/theorem-examples.qmd deleted file mode 100644 index 9802b37..0000000 --- a/chapters/theorem-examples.qmd +++ /dev/null @@ -1,160 +0,0 @@ ---- -title: "Theorem Examples" ---- - -This chapter demonstrates all the theorem-like environments available through the `callouty-theorem` and `custom-callout` extensions. - -# Theorems - -:::{#thm-pythagorean} -## Pythagorean Theorem -In a right triangle with legs of length $a$ and $b$ and hypotenuse of length $c$, we have: -$$a^2 + b^2 = c^2$$ -::: - -See @thm-pythagorean for the famous Pythagorean theorem. - -# Lemmas - -:::{#lem-fundamental} -## Fundamental Lemma -Every non-empty subset of $\mathbb{N}$ has a smallest element. -::: - -The result in @lem-fundamental is used to prove many theorems in number theory. - -# Corollaries - -:::{#cor-rational-root} -## Rational Root Test Corollary -If $p/q$ is a rational root of the polynomial $a_n x^n + \cdots + a_1 x + a_0$ with integer coefficients, then $p$ divides $a_0$ and $q$ divides $a_n$. -::: - -@cor-rational-root follows directly from the Rational Root Theorem. - -# Propositions - -:::{#prp-triangle-inequality} -## Triangle Inequality -For any real numbers $x$ and $y$: -$$|x + y| \leq |x| + |y|$$ -::: - -The triangle inequality (@prp-triangle-inequality) is fundamental in analysis. - -# Conjectures - -:::{#cnj-goldbach} -## Goldbach's Conjecture -Every even integer greater than 2 can be expressed as the sum of two prime numbers. -::: - -@cnj-goldbach remains one of the oldest unsolved problems in number theory. - -# Definitions - -:::{#def-derivative} -## Derivative -The derivative of a function $f$ at a point $x$ is defined as: -$$f'(x) = \lim_{h \to 0} \frac{f(x+h) - f(x)}{h}$$ -provided this limit exists. -::: - -See @def-derivative for the formal definition of a derivative. - -# Examples - -:::{#exm-quadratic} -## Solving a Quadratic Equation -Solve $x^2 - 5x + 6 = 0$. - -We can factor this as $(x-2)(x-3) = 0$, so the solutions are $x = 2$ and $x = 3$. -::: - -@exm-quadratic shows how to solve a simple quadratic equation. - -# Exercises - -:::{#exr-integration} -## Integration Practice -Compute the following integral: -$$\int_0^1 x^2 \, dx$$ -::: - -Try @exr-integration to practice basic integration. - -# Proofs - -:::{.proof} -## Proof of the Pythagorean Theorem - -Consider a square with side length $a+b$. We can divide this square into four right triangles and a central square with side length $c$. - -The area equations show: -$$a^2 + b^2 = c^2$$ -::: - -:::{.proof} -## Proof that the derivative of a constant is zero - -Let $f(x) = c$ for some constant $c$. Then $f'(x) = 0$. -::: - -# Solutions - -:::{#sol-integration .solution} -## Solution to Exercise on Integration - -We use the power rule for integration: -$$\int_0^1 x^2 \, dx = \left[\frac{x^3}{3}\right]_0^1 = \frac{1}{3}$$ -::: - -:::{.solution} -## Alternative Solution to Quadratic Equation - -For the quadratic equation, we can use the quadratic formula: -$$x = \frac{5 \pm 1}{2}$$ - -This gives us $x = 3$ or $x = 2$. -::: - -# Remarks - -:::{#rem-convergence .remark} -## Convergence Note -The limit in @def-derivative may not exist for all functions at all points. For example, the absolute value function $|x|$ is not differentiable at $x=0$. -::: - -@rem-convergence highlights an important limitation of the derivative definition. - -# Mixed Example with Theorem and Solution - -Here's an example that combines multiple theorem types: - -:::{#thm-mean-value} -## Mean Value Theorem -If $f$ is continuous on $[a,b]$ and differentiable on $(a,b)$, then there exists a point $c \in (a,b)$ such that: -$$f'(c) = \frac{f(b) - f(a)}{b - a}$$ -::: - -:::{#exr-mvt-application} -## Applying the Mean Value Theorem -Let $f(x) = x^2$ on $[0, 2]$. Find the value of $c$ guaranteed by the Mean Value Theorem (@thm-mean-value). -::: - -:::{#sol-mvt-application .solution} -## Solution to Mean Value Theorem Exercise - -We have $f(x) = x^2$, so $f'(x) = 2x$. - -By the Mean Value Theorem: -$$f'(c) = \frac{f(2) - f(0)}{2 - 0} = \frac{4 - 0}{2} = 2$$ - -Since $f'(c) = 2c$, we need: -$$2c = 2$$ -$$c = 1$$ - -Therefore, $c = 1$ is the value guaranteed by the Mean Value Theorem. -::: - -# References {.unnumbered} diff --git a/images/README.md b/images/README.md index a449f18..db9104f 100644 --- a/images/README.md +++ b/images/README.md @@ -5,7 +5,7 @@ Place your images and figures in this directory. ## Naming conventions Use descriptive names for your images: -- `chapter1-workflow-diagram.png` +- `entropy-diagram.png` - `results-plot-2024.png` - `methodology-flowchart.svg` diff --git a/index.qmd b/index.qmd index 85db33d..23c6eea 100644 --- a/index.qmd +++ b/index.qmd @@ -1,5 +1,5 @@ --- -title: "Quarto Website Template" +title: "Computational Complexity for Data Science" format: html: default revealjs: @@ -10,69 +10,60 @@ format: output-file: index.docx --- -# Welcome {.unnumbered} - -This is a Quarto website template that you can use to create your own website. - -The notes are available in multiple formats: - -- **HTML Website**: Navigate using the navbar for easy access to all pages -- **RevealJS Slides**: Each chapter can generate a presentation format with `-slides.html` suffix -- **PDF Handouts**: Each chapter can generate a PDF handout with `-handout.pdf` suffix -- **DOCX Documents**: Each chapter can generate a Microsoft Word document with `.docx` extension - -## About this website - -This website is built with [Quarto](https://quarto.org/), an open-source scientific and technical publishing system. You can use Quarto to create books, websites, blogs, presentations, and more from markdown files. - -## Getting Started - -To use this template: - -1. **Update the configuration**: Edit `_quarto-website.yml` to change the website title, site URL, and navigation menu. - -2. **Add your content**: Create new `.qmd` files for each page and add them to the navigation menu and the sidebar in `_quarto-website.yml` (the sidebar order sets the previous/next page links). - -3. **Customize the style**: Modify `styles.css` to change the appearance of your website. - -4. **Add references**: Update `references.bib` with your citations. - -## Building the website - -To render the website locally: - -```bash -quarto render -``` - -To preview the website with live reload: - -```bash -quarto preview -``` - -The rendered output will be in the `_site/` directory, which can be published to GitHub Pages. - -## Publishing to GitHub Pages - -This template includes a GitHub Actions workflow that automatically builds and publishes your website to GitHub Pages when you push to the main branch. - -To enable GitHub Pages: - -1. Go to your repository settings -2. Navigate to "Pages" in the left sidebar -3. Under "Build and deployment", set Source to "GitHub Actions" -4. Push your changes to the main branch -5. The workflow will automatically build and deploy your website - -Your website will be available at `https://YOUR-USERNAME.github.io/YOUR-REPO/` - -## License - -Add your license information here. - -## References {.unnumbered} - -::: {#refs} -::: - +## Welcome {.unnumbered} + +Computational complexity asks how much time, memory or randomness +a problem needs, whatever algorithm solves it. +Data science meets it whenever fitting a model exactly turns out to be +computationally hard, +which is one reason practical methods use greedy search or a convex surrogate loss. + +These notes collect the computational complexity that data science courses use. +They are new, and the topic pages are still to be written. +The planned topics are: + +- models of computation: Turing machines and computability +- time and space complexity, and the classes P and NP +- reductions and NP-completeness +- randomized computation +- communication and information complexity + +Information theory has its own library, +[*Information Theory for Data Science*](https://morrison-lab.github.io/ids/). +Results that connect the two live in the library that holds +their main statement, and the other links to them. + +## Starting materials {.unnumbered} + +These notes are written fresh, but they draw on the following books and Stanford course pages. + +- Sanjeev Arora and Boaz Barak, *Computational Complexity: A Modern Approach*, + the main starting point for complexity theory. +- [CS154: Introduction to the Theory of Computation](https://theory.stanford.edu/~liyang/teaching/computability.html) + (Omer Reingold and Li-Yang Tan), which covers automata, computability and complexity, + using Michael Sipser's *Introduction to the Theory of Computation*, + with lecture slides and videos. +- [CS154: Introduction to Automata and Complexity Theory](https://theory.stanford.edu/~rajeev/cs154.html) + (Spring 2009, with Rajeev Motwani among the course staff), + with handouts, homework and a reading list. +- [*Introduction to Automata Theory, Languages, and Computation*](http://infolab.stanford.edu/~ullman/ialc.html), + Jeff Ullman's home page for the book, which is the textbook the 2009 CS154 page links. + It has solutions to starred exercises, errata, slides, and past CS154 course materials. +- [CS254: Computational Complexity](https://theory.stanford.edu/~liyang/teaching/complexity.html) + (Li-Yang Tan), which covers space complexity, the polynomial hierarchy, randomized and non-uniform computation, + and interactive proofs. + It uses Arora and Barak and Avi Wigderson's *Mathematics and Computation*, + and links a reading for each lecture. + +## Using these notes in another site {.unnumbered} + +Course sites link to these pages by URL; +they do not include this repository as a git submodule. +A host site that keeps a copy of this repository at its root, named `cds`, +can still include fragments with paths that start with `cds/`. +This site includes its own fragments the same way, +through a `cds` symlink that points at the repository root. + +Quarto resolves `@id` cross-references only within one rendered page, +so a host site that links to a result here +uses an explicit link to the page and anchor. diff --git a/inst/WORDLIST b/inst/WORDLIST index 9aa519b..0112791 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -1,14 +1,34 @@ +Arora +Automata +Avi +Barak +Boaz CLI DOCX +Motwani +Omer +Rajeev +Reingold RevealJS SERG +Sanjeev +Sipser's TinyTeX UCD +Ullman's +Wigderson's +automata +computability dropdown ebsite emplate glitchy lintr navbar +pds +qwt rulesets +submodule +submodules +symlink uarto diff --git a/latex-macros b/latex-macros index 5232f88..5791ba5 160000 --- a/latex-macros +++ b/latex-macros @@ -1 +1 @@ -Subproject commit 5232f88b31a1bf77fe497633dc785a152e5550a6 +Subproject commit 5791ba5dea1321d1cb407079dcc1f7d09824a2cb diff --git a/lychee.toml b/lychee.toml index c7c7506..0bd0189 100644 --- a/lychee.toml +++ b/lychee.toml @@ -27,4 +27,14 @@ exclude = [ "https://127.0.0.1.*", # quarto.org is a trusted site but may be unreachable from CI runners "https://quarto.org/.*", + # StackExchange and etymonline sites answer automated clients such as CI + # link checkers with 403 Forbidden; the links work in a browser. + "https://math.stackexchange.com/.*", + "https://stats.stackexchange.com/.*", + "https://www.etymonline.com/.*", ] + +# `cds` is a symlink to the repository root, so include paths read +# `cds/...` both here and in a host site that keeps a copy at its root. +# Without this exclusion lychee follows it recursively (cds/cds/cds/...). +exclude_path = ["^(\\./)?cds/"] diff --git a/man/cds-package.Rd b/man/cds-package.Rd new file mode 100644 index 0000000..115d649 --- /dev/null +++ b/man/cds-package.Rd @@ -0,0 +1,28 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/cds-package.R +\docType{package} +\name{cds-package} +\alias{cds} +\alias{cds-package} +\title{cds: Computational Complexity for Data Science} +\description{ +Computational complexity for data science courses, written as Quarto fragments that course sites link to. +} +\seealso{ +Useful links: +\itemize{ + \item \url{https://github.com/Morrison-Lab/cds} + \item Report bugs at \url{https://github.com/Morrison-Lab/cds/issues} +} + +} +\author{ +\strong{Maintainer}: Ezra Morrison \email{d.ezra.morrison@gmail.com} + +Authors: +\itemize{ + \item Ezra Morrison \email{d.ezra.morrison@gmail.com} +} + +} +\keyword{internal} diff --git a/man/qwt-package.Rd b/man/qwt-package.Rd deleted file mode 100644 index 36e9e3e..0000000 --- a/man/qwt-package.Rd +++ /dev/null @@ -1,23 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/qwt-package.R -\docType{package} -\name{qwt-package} -\alias{qwt} -\alias{qwt-package} -\title{qwt: Quarto Website Template} -\description{ -A template for creating websites with Quarto. Includes support for multiple output formats including HTML, DOCX, RevealJS slides, and PDF handouts. -} -\seealso{ -Useful links: -\itemize{ - \item \url{https://github.com/UCD-SERG/qwt} - \item Report bugs at \url{https://github.com/UCD-SERG/qwt/issues} -} - -} -\author{ -\strong{Maintainer}: Your Name \email{your.email@example.com} - -} -\keyword{internal} diff --git a/page-navigation.html b/page-navigation.html deleted file mode 100644 index 2f7adf7..0000000 --- a/page-navigation.html +++ /dev/null @@ -1,149 +0,0 @@ - - - diff --git a/references.bib b/references.bib index 764e5b4..e69de29 100644 --- a/references.bib +++ b/references.bib @@ -1,19 +0,0 @@ -@book{example2024, - title={Example Book Title}, - author={Author, Example}, - year={2024}, - publisher={Example Publisher}, - doi={10.1007/978-3-319-24277-4} -} - -@article{example-article2024, - title={Example Article Title}, - author={Author, Example and Coauthor, Another}, - journal={Example Journal}, - volume={10}, - number={1}, - pages={1--10}, - year={2024}, - publisher={Example Publisher}, - doi={10.1038/nature12373} -} diff --git a/references.qmd b/references.qmd index 46868aa..bac6d97 100644 --- a/references.qmd +++ b/references.qmd @@ -10,8 +10,6 @@ format: output-file: references.docx --- -# References {.unnumbered} - ::: {#refs} ::: diff --git a/revealjs-level1-slide-breaks.lua b/revealjs-level1-slide-breaks.lua index 0ae902a..f02a99d 100644 --- a/revealjs-level1-slide-breaks.lua +++ b/revealjs-level1-slide-breaks.lua @@ -8,7 +8,7 @@ function Pandoc(doc) for i, block in ipairs(doc.blocks) do table.insert(updated_blocks, block) - if block.t == "Header" and block.level <= 2 then + if block.t == "Header" and block.level <= 1 then local next_block = doc.blocks[i + 1] if next_block and next_block.t ~= "HorizontalRule" then diff --git a/styles-reveal.scss b/styles-reveal.scss index eba0572..daaff4e 100644 --- a/styles-reveal.scss +++ b/styles-reveal.scss @@ -105,7 +105,7 @@ body.qwt-dark .reveal { code span.in { color: #d4d0ab; } } -// The code-fold summary ("[R code]") is the text colour softened toward the page, +// The code-fold summary ("[Code]") is the text colour softened toward the page, // which stays above AA on every palette. .reveal details > summary, .reveal details > summary p {