From f8b8053b0f9ae6b67837e50dcba601eb3dc5016b Mon Sep 17 00:00:00 2001 From: novica Date: Sat, 4 Jul 2026 15:35:36 +0200 Subject: [PATCH 1/2] feat: unify docs into a single Quarto website MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit quartify's rtoqmd_dir() has no way to include README/architecture/ADR pages, and the previous docs-build call used a nonexistent `render` argument (real name render_html) that silently no-opped, so the generated reference was never actually part of a real site. Demote quartify to a flat .qmd emitter (create_book = FALSE, render_html = FALSE), relocate its output into docs/reference/, and hand-author docs/_quarto.yml as the website project that ties together the README (via {{< include >}} as the home page), architecture/ADR markdown (rendered natively), and the generated reference into one navigable site. Also fixes ~20 repo-relative README links that would 404 once transcluded into docs/index.qmd, plus several unrelated stale/broken links and content found along the way (wrong test dir path, uv.lock vs rv.lock, wrong clone URL, hello.py vs hello.r, stale Common Tasks table). Also bumps jarl-pre-commit 0.4.0 -> 0.5.0: 0.4.0 fails to parse a bare .qmd file with no frontmatter/R chunks (like docs/index.qmd's {{< include >}}-only content) with "Failed to parse ... due to syntax errors" — fixed upstream in 0.5.0, confirmed locally. Verified locally: `quarto render docs/` renders all 10 pages (README, architecture/ADRs, reference stubs) cleanly with working absolute links. quartify itself couldn't be exercised locally due to a pre-existing R 4.6.1/rv-pinned-4.5 mismatch on this machine (unrelated to this change, CI pins R 4.5 via setup-r so unaffected); the create_book/render_html argument behavior was confirmed by reading quartify's installed source directly. Documented as ADR-004 (Accepted — no tagged release exists yet, so this is a clean initial decision, not a reversal of anything shipped). Assisted-by: Claude Sonnet 5 --- .github/workflows/generate-docs.yml | 12 ++- .gitignore | 2 + .pre-commit-config.yaml | 2 +- CLAUDE.md | 17 ++-- README.md | 87 ++++++++++--------- docs/.gitignore | 2 + docs/_quarto.yml | 41 +++++++++ ...4-unify-docs-into-single-quarto-website.md | 75 ++++++++++++++++ docs/architecture/adr/index.md | 1 + docs/index.qmd | 1 + justfile | 7 +- 11 files changed, 195 insertions(+), 52 deletions(-) create mode 100644 docs/.gitignore create mode 100644 docs/_quarto.yml create mode 100644 docs/architecture/adr/004-unify-docs-into-single-quarto-website.md create mode 100644 docs/index.qmd diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml index 3299c73..eed5e7e 100644 --- a/.github/workflows/generate-docs.yml +++ b/.github/workflows/generate-docs.yml @@ -5,6 +5,7 @@ on: branches: [main] paths: - "docs/**" + - "README.md" # feeds the site's home page - ".github/workflows/generate-docs.yml" - "src/package_name/**" # rebuild if API docs change @@ -38,8 +39,15 @@ jobs: - name: Sync project run: rv sync - - name: Run Quartrify - run: Rscript -e "quartify::rtoqmd_dir('src/package_name/', render = TRUE, output_html_dir = '../../docs/html', exclude_pattern='__tests__')" + - name: Generate API reference (Quartify) + run: | + Rscript -e "quartify::rtoqmd_dir('src/package_name/', create_book = FALSE, render_html = FALSE, exclude_pattern = '__tests__')" + rm -rf docs/reference && mkdir -p docs/reference + for f in src/package_name/*.qmd; do mv "$f" "docs/reference/$(basename "$f" | sed 's/^_*//')"; done + + - name: Render docs site (Quarto) + run: quarto render docs/ + - name: Upload artifact uses: actions/upload-pages-artifact@v5 with: diff --git a/.gitignore b/.gitignore index 2f387ee..ad851e5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,4 @@ **/.quarto/ **/*.quarto_ipynb +docs/reference/ +docs/html/ diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1548718..fe21867 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -9,7 +9,7 @@ repos: # --- Jarl linter --- - repo: https://github.com/etiennebacher/jarl-pre-commit - rev: 0.4.0 + rev: 0.5.0 hooks: - id: jarl-check diff --git a/CLAUDE.md b/CLAUDE.md index 0b23063..b140a62 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ just update # rv upgrade — bump deps to latest allowed versions just lint # jarl check . just format # r-air format --check . (drop --check to auto-fix: r-air format .) just test # Rscript -e "testthat::test_dir('src/package_name/__tests__')" -just docs-build # quartify::rtoqmd_dir(...) — regenerates docs/*.qmd + docs/html from R source +just docs-build # quartify generates docs/reference/*.qmd, then `quarto render docs/` builds docs/html just pre-commit-install # one-time: installs pre-commit + pre-push + commit-msg hooks via prek just pre-commit # prek run --all-files --hook-stage pre-push ``` @@ -43,17 +43,22 @@ There is no `library()`/`require()` for internal code — everything is `box::us for the tests — add an equivalent `box::use()` line here when testing a new sibling module. - New test files follow the `test-.R` naming convention testthat expects. -**Docs are generated, not hand-written.** `docs/` (the `.qmd` files and `docs/html/`) is produced from the R -source + roxygen comments by `quartify::rtoqmd_dir()` (`just docs-build`), excluding `__tests__`. Don't hand-edit -generated `.qmd`/`docs/html` content — edit the roxygen comments in the source `.r` files instead and regenerate. -`docs/html` is what's deployed to GitHub Pages (`generate-docs.yml`). +**`docs/` is a single hand-authored Quarto website** (`docs/_quarto.yml`, see ADR-004) that combines the root +README (`docs/index.qmd` includes it via `{{< include ../README.md >}}`), the architecture/ADR markdown +(`docs/architecture/**`, rendered natively, edit directly), and a generated API reference. Only +`docs/reference/*.qmd` and `docs/html/` are generated/gitignored: `quartify::rtoqmd_dir()` converts roxygen +comments from `src/package_name/*.r` into `.qmd` (excluding `__tests__`), which `just docs-build` relocates +into `docs/reference/` before running `quarto render docs/` to produce `docs/html` (deployed to GitHub Pages +via `generate-docs.yml`). Don't hand-edit `docs/reference/*.qmd`/`docs/html` — edit the roxygen comments and +regenerate instead. Adding or removing a source module needs a matching entry added/removed in +`docs/_quarto.yml`'s sidebar (quartify's output isn't auto-discovered there). **Architectural Decision Records live in `docs/architecture/adr/`** (see ADR-001). Any architecturally significant change (new tool, new convention, reversing a prior decision) should get a new ADR — copy `template.md`, number sequentially (`NNN-verb-object.md`), status `🟡 Proposed`. Check existing ADRs before proposing changes that touch already-decided territory (e.g. `box` vs packages, `rv` vs `renv`/`packrat`). Note: ADR-002 covers running Git hooks via `prek`, a dependency-free Rust binary — R dependency management is -a separate decision, `rv` not `renv`/`packrat` (see ADR-003). +a separate decision, `rv` not `renv`/`packrat` (see ADR-003). ADR-004 covers the `docs/` site structure. **Only one package manager is in play**: `rv` (via `rproject.toml` / `rv.lock`) manages R dependencies. rv has no concept of dev-only dependencies, so tooling deps (`languageserver`, `testthat`, `roxygen2`, `quartify`) are diff --git a/README.md b/README.md index cdf2b01..8fb683e 100644 --- a/README.md +++ b/README.md @@ -27,37 +27,37 @@ way of doing things in the R world, and there is a question mark if they get ado 1. Clone your new repo locally 1. 🏡 Customise the repository 1. Rename your package directory `cd src; mv package_name my_package` - 1. Update [rproject.toml](rproject.toml) with your package name, author, and description, and preferred repository. + 1. Update [rproject.toml](https://github.com/novica/r-project-template/blob/main/rproject.toml) with your package name, author, and description, and preferred repository. 1. Update all references to package_name in: - - [package_name/tests/](package_name/tests/) - - [docs/](docs/) - - [release-please-config.json](release-please-config.json) - - [GitHub Actions workflow](.github/workflows/ci.yml) + - [src/package_name/\_\_tests\_\_/](https://github.com/novica/r-project-template/tree/main/src/package_name/__tests__) + - [docs/](https://github.com/novica/r-project-template/tree/main/docs) + - [release-please-config.json](https://github.com/novica/r-project-template/blob/main/release-please-config.json) + - [GitHub Actions workflow](https://github.com/novica/r-project-template/blob/main/.github/workflows/ci.yml) - This README (including badge links) - 1. Update the `"package-name"` field in [release-please-config.json](release-please-config.json) with your package name for automatically bumping the version number in [uv.lock](uv.lock) (see [release-please issue #2561](https://github.com/googleapis/release-please/issues/2561)). + 1. Update the `"package-name"` field in [release-please-config.json](https://github.com/novica/r-project-template/blob/main/release-please-config.json) with your package name for automatically bumping the version number in [rv.lock](https://github.com/novica/r-project-template/blob/main/rv.lock) (see [release-please issue #2561](https://github.com/googleapis/release-please/issues/2561)). 1. Customise this README with a description of your project and planned features. 1. Clear the CHANGELOG. - 1. Enable automated releases by permitting GitHub Actions to open PRs (Settings -> Actions -> Workflow permissions) and add an initial commit hash to bootstrap the release-please in [.release-please-manifest.json](.release-please-manifest.json). + 1. Enable automated releases by permitting GitHub Actions to open PRs (Settings -> Actions -> Workflow permissions) and add an initial commit hash to bootstrap the release-please in [.release-please-manifest.json](https://github.com/novica/r-project-template/blob/main/.release-please-manifest.json). 1. Enable publishing to GitHub Pages (Settings -> Pages). ## 🚀 Features - Modular project directory structure using [box](https://klmr.me/box/articles/box.html). - README template with badges. -- Packaging and dependency management via [rv](https://a2-ai.github.io/rv-docs/): [rproject.toml](rproject.toml). +- Packaging and dependency management via [rv](https://a2-ai.github.io/rv-docs/): [rproject.toml](https://github.com/novica/r-project-template/blob/main/rproject.toml). - Linting via [Jarl](https://jarl.etiennebacher.com/). - Formatting via [Air](https://posit-dev.github.io/air/). - Testing framework using [testthat](https://testthat.r-lib.org/). -- [Pre-commit hooks](.pre-commit-config.yaml) (linting and formatting). -- CI using [GitHub Actions](https://docs.github.com/en/actions): [.github/workflows/ci.yml](.github/workflows/ci.yml). -- Docs generated with [Quartrify](https://github.com/ddotta/quartify) and deployed to `gh-pages` branch via GitHub action: [.github/workflows/generate-docs.yml](.github/workflows/generate-docs.yml). -- Templates for GitHub issues: bug report ([01-bug.yml](.github/ISSUE_TEMPLATE/01-bug.yml)) and feature request ([02-feature.yml](.github/ISSUE_TEMPLATE/01-feature.yml)). -- Template for GitHub pull request: [.github/pull_request_template.md](.github/pull_request_template.md). -- Template for [documenting architectural decisions](https://adr.github.io/): [docs/architecture/adr/template.md](docs/architecture/adr/template.md). - - ADR to explain the rationale for using ADRs: [docs/architecture/adr/001-use-architectural-decision-records.md](docs/architecture/adr/001-use-architectural-decision-records.md). -- Release automation via GitHub action from [release-please](https://github.com/googleapis/release-please): [.github/release-please-config.json](.github/release-please-config.json). -- Citation metadata, automatically updated for each new release: [CITATION.cff](CITATION.cff). -- [EditorConfig](https://editorconfig.org/) configuration for consistent coding style across editors: [.editorconfig](.editorconfig). +- [Git hooks](https://github.com/novica/r-project-template/blob/main/.pre-commit-config.yaml) via [prek](https://prek.j178.dev/) (linting and formatting). +- CI using [GitHub Actions](https://docs.github.com/en/actions): [.github/workflows/ci.yml](https://github.com/novica/r-project-template/blob/main/.github/workflows/ci.yml). +- Docs generated with [quartify](https://github.com/ddotta/quartify) and rendered as a single [Quarto](https://quarto.org/) website, deployed to GitHub Pages via GitHub action: [.github/workflows/generate-docs.yml](https://github.com/novica/r-project-template/blob/main/.github/workflows/generate-docs.yml). +- Templates for GitHub issues: bug report ([01-bug.yml](https://github.com/novica/r-project-template/blob/main/.github/ISSUE_TEMPLATE/01-bug.yml)) and feature request ([02-feature.yml](https://github.com/novica/r-project-template/blob/main/.github/ISSUE_TEMPLATE/02-feature.yml)). +- Template for GitHub pull request: [.github/pull_request_template.md](https://github.com/novica/r-project-template/blob/main/.github/pull_request_template.md). +- Template for [documenting architectural decisions](https://adr.github.io/): [docs/architecture/adr/template.md](https://github.com/novica/r-project-template/blob/main/docs/architecture/adr/template.md). + - ADR to explain the rationale for using ADRs: [docs/architecture/adr/001-use-architectural-decision-records.md](https://github.com/novica/r-project-template/blob/main/docs/architecture/adr/001-use-architectural-decision-records.md). +- Release automation via GitHub action from [release-please](https://github.com/googleapis/release-please): [release-please-config.json](https://github.com/novica/r-project-template/blob/main/release-please-config.json). +- Citation metadata, automatically updated for each new release: [CITATION.cff](https://github.com/novica/r-project-template/blob/main/CITATION.cff). +- [EditorConfig](https://editorconfig.org/) configuration for consistent coding style across editors: [.editorconfig](https://github.com/novica/r-project-template/blob/main/.editorconfig). ## ‼️ Limitations @@ -69,7 +69,7 @@ way of doing things in the R world, and there is a question mark if they get ado ### Working in a development container -A [Dockerfile](./.devcontainer/Dockerfile) and [configuration](./.devcontainer/devcontainer.json) in [./.devcontainer](./.devcontainer) can be used in VSCode or GitHub Codespaces to work in a pre-configured development environment. It uses a Python 3.14 base image and installs prek, just and all Python dependencies. +A [Dockerfile](https://github.com/novica/r-project-template/blob/main/.devcontainer/Dockerfile) and [configuration](https://github.com/novica/r-project-template/blob/main/.devcontainer/devcontainer.json) in [.devcontainer](https://github.com/novica/r-project-template/tree/main/.devcontainer) can be used in VSCode or GitHub Codespaces to work in a pre-configured development environment. It uses an R base image and installs Quarto, rv, air, jarl, prek, and just. To open the project in the container VSCode, you will need to add the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and download [Docker](https://docs.docker.com/get-started/get-docker/) (or [Podman](https://podman.io/docs/installation) -- and [configure VSCode to use podman instead of Docker](https://code.visualstudio.com/remote/advancedcontainers/docker-options#_podman)) -- see the [VSCode tutorial on devcontainers](https://code.visualstudio.com/docs/devcontainers/tutorial) for more details on using devcontainers. Then run: @@ -82,39 +82,41 @@ Dev Containers: Reopen in Container 1. [Install rv](https://2-ai.github.io/rv-docs/intro/installation/) 1. optional, if you want to use shortcut commands, [install just](https://just.systems/) 1. optional, if you want to use pre-commit hooks, [install prek](https://prek.j178.dev/) +1. optional, if you want to build the docs site locally, [install Quarto](https://quarto.org/docs/get-started/) 1. Clone and install the project using rv: ```bash -git clone https://github.com/gemmadanks/r-project-template +git clone https://github.com/novica/r-project-template cd r-project-template rv sync ``` -1. [Install just](https://just.systems/man/en/packages.html). -1. Install pre-commit hooks (only needs to be done once) +1. Install pre-commit hooks (only needs to be done once): `just pre-commit-install` ## 🧪 Common Tasks -Several common tasks have been added as recipes to a [justfile](justfile) in the root of the repository: +Several common tasks have been added as recipes to a [justfile](https://github.com/novica/r-project-template/blob/main/justfile) in the root of the repository: ```bash - default # Default recipe (shown when running plain `just`) - docs-build # Build docs (Quartrify) - format # Format (Air format) - install # Install dependencies (create/update virtualenv) - lint # Lint (Jarl check) - test # Run testthat - update # Upgrade packages to the latest versions available + default # Default recipe (shown when running plain `just`) + install # Install dependencies (rv sync) + update # Upgrade packages to the latest versions available (rv upgrade) + lint # Lint (Jarl check) + format # Format (Air format) + test # Run testthat + docs-build # Build docs (Quartify generates reference qmd, Quarto renders the site) + pre-commit-install # Install git hooks (via prek) + pre-commit # Run all git hooks (via prek) ``` ## 📚 Documentation -- Generated with [Quartrify](https:://github.com/ddotta/quartify). Probably a lot can be improved here. +- Generated with [quartify](https://github.com/ddotta/quartify) and rendered as a single [Quarto](https://quarto.org/) website (`just docs-build`), combining this README, the architecture/ADR docs, and the generated API reference. See [ADR-004](https://github.com/novica/r-project-template/blob/main/docs/architecture/adr/004-unify-docs-into-single-quarto-website.md). ## 🔄 Releases Managed by release-please: ([conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) drive [semantic versioning](https://semver.org/) and an autogenerated CHANGELOG). - - Configuration: [.github/release-please-config.json](.github/release-please-config.json) + - Configuration: [release-please-config.json](https://github.com/novica/r-project-template/blob/main/release-please-config.json) - Version source: rproject.toml ## 📂 Project Structure @@ -124,17 +126,20 @@ Managed by release-please: ([conventional commits](https://www.conventionalcommi ├── src/ │ └── package_name/ # Source package │ ├── __init__.r -│ └── hello.py # Example module (replace with real code) +│ └── hello.r # Example module (replace with real code) | └── __tests__/ # Test suite for the example module | ├── __init__.r | ├── helper-module.r | └── test_hello.R ├── data-raw/ # Raw data used in the project (if applicable) -├── docs/ # Generated quarto documentation -│ ├── __init__.qmd -│ ├── index.qmd -│ ├── hello.qmd -│ └── html/* # Generated HTML docs (deployed to GitHub Pages) +├── docs/ # Documentation site (Quarto website, see ADR-004) +│ ├── _quarto.yml # Hand-authored Quarto website project +│ ├── index.qmd # Home page ({{< include ../README.md >}}) +│ ├── architecture/ # Hand-written: architecture overview + ADRs +│ │ ├── index.md +│ │ └── adr/ +│ ├── reference/ # Generated by quartify (gitignored, rebuilt by `just docs-build`) +│ └── html/ # Rendered site output (gitignored; deployed to GitHub Pages) ├── notebooks/ # Quarto notebooks │ └── demo.qmd ├── .github/ @@ -152,7 +157,7 @@ Managed by release-please: ([conventional commits](https://www.conventionalcommi ├── CITATION.cff # Citation metadata ├── LICENSE # License ├── NEWS.md # Generated by release-please (post-release) -├── .pre-commit-config.yaml # Pre-commit hooks configuration (uv) +├── .pre-commit-config.yaml # Git hooks configuration (run via prek) ├── .release-please-manifest.json # Release-please state ├── release-please-config.json # Release-please configuration ├── justfile # justfile containing recipes for common tasks @@ -180,10 +185,10 @@ Suggestions and improvements to this template are very welcome — feel free to ## 📖 Citation -If used in research, cite via [CITATION.cff](CITATION.cff). +If used in research, cite via [CITATION.cff](https://github.com/novica/r-project-template/blob/main/CITATION.cff). ## 🛡 License -BSD-3-Clause – see [LICENSE](LICENSE). +BSD-3-Clause – see [LICENSE](https://github.com/novica/r-project-template/blob/main/LICENSE). Happy coding! 🚀 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..ad29309 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +/.quarto/ +**/*.quarto_ipynb diff --git a/docs/_quarto.yml b/docs/_quarto.yml new file mode 100644 index 0000000..7d7a9cf --- /dev/null +++ b/docs/_quarto.yml @@ -0,0 +1,41 @@ +project: + type: website + output-dir: html + +website: + title: "package_name" + navbar: + left: + - href: index.qmd + text: Home + - href: architecture/index.md + text: Architecture + - href: reference/init.qmd + text: Reference + right: + - icon: github + href: "https://github.com/novica/r-project-template" + sidebar: + style: docked + contents: + - index.qmd + - section: "Architecture" + contents: + - architecture/index.md + - architecture/adr/index.md + - section: "API Reference" + contents: + # Generated by quartify (see justfile's `docs-build`), one file per src/package_name/*.r + # module — this list isn't auto-discovered and needs a manual entry when a module is + # added or removed. Filenames have leading underscores stripped on relocation (e.g. + # __init__.qmd -> init.qmd) since Quarto excludes underscore-prefixed files from the + # project by default. + - text: "Package overview" + href: reference/init.qmd + - text: "hello" + href: reference/hello.qmd + +format: + html: + theme: cosmo + toc: true diff --git a/docs/architecture/adr/004-unify-docs-into-single-quarto-website.md b/docs/architecture/adr/004-unify-docs-into-single-quarto-website.md new file mode 100644 index 0000000..6a68e0d --- /dev/null +++ b/docs/architecture/adr/004-unify-docs-into-single-quarto-website.md @@ -0,0 +1,75 @@ +--- +tags: + - docs +--- + +# ADR-004: Unify docs into a single Quarto website +| | | +| ---| ---| +| **Status** | 🟢 Accepted | +| **Created** | 2026-07-04 | +| **Last Updated** | 2026-07-04 | +| **Deciders** | Novica Nakov | + +--- + +## Context + +`quartify::rtoqmd_dir()` converts roxygen comments in `src/package_name/*.r` into `.qmd` reference pages, but +it has no concept of pages outside the R source tree it's converting — it can't include a README, an +architecture overview, or ADRs. Left on its own, that leaves this project with two disconnected things: a +generated API reference, and a pile of hand-written markdown (`README.md`, `docs/architecture/index.md`, +`docs/architecture/adr/*.md`) with no shared navigation tying them into one site. + +## Problem Statement + +How should this project combine hand-written docs (README, architecture, ADRs) and the quartify-generated API +reference into one navigable, deployable documentation site? + +## Options Considered + +| Option | Description | Coherent nav | Low maintenance | No new tooling | Keeps generated content out of `src/` | Overall score | Notes | +|----------|-------------|-------------|-----------------|-------------| ----- | ------|------| +| **Weight** | - | 2 | 1 | 1 | 2 | - | - | +| **A. Disconnected pages** | Leave README/architecture/ADRs as loose markdown, quartify's reference pages separate. | ❌ | ✅ | ✅ | ⚠️ | 12 | No unified site at all — status quo, not a real option. | +| **B. Let quartify own the whole site** (`create_book = TRUE`) | quartify manages its own `_quarto.yml`/book project. | ❌ | ✅ | ✅ | ❌ | 14 | Confirmed via source: writes `_quarto.yml` **into `src/package_name/`** and has no mechanism to include external pages — can never host the README/ADRs. | +| **C. Hand-authored Quarto website rooted at `docs/`** | quartify demoted to a flat `.qmd` emitter (`create_book = FALSE`, `render_html = FALSE`); its output is relocated into `docs/reference/`; a hand-authored `docs/_quarto.yml` ties README (via `{{< include >}}`), architecture/ADR markdown (rendered natively, no conversion needed), and the reference pages into one site. | ✅ | ⚠️ | ✅ | ✅ | 20 | Chosen. Quarto CLI is already a required/installed tool (used for docs today); no new dependency. | +| **D. Drop quartify** | Hand-write all API docs, or adopt a different generator. | ✅ | ❌ | ❌ | ✅ | 13 | Throws away working roxygen→qmd conversion; `pkgdown` doesn't work here either (no `DESCRIPTION`, see README's Limitations section). | + +✅ = 3 (good), ⚠️ = 2 (acceptable), ❌ = 1 (poor) + +## Decision Outcome + +We will use Option C. `docs/_quarto.yml` is a hand-authored Quarto website project that owns the site's +structure end to end: `docs/index.qmd` pulls in the root `README.md` via `{{< include ../README.md >}}` as the +home page; `docs/architecture/index.md` and `docs/architecture/adr/*.md` are listed directly in the sidebar +(Quarto renders plain `.md` natively, no conversion step); and `docs/reference/*.qmd` (quartify's output, +relocated there by `just docs-build` after generation) is listed as the API reference section. A single +`quarto render docs/` produces `docs/html/`, which is what `generate-docs.yml` deploys to GitHub Pages. + +## Consequences + +* Good, because there's one deploy target (`docs/html/`) and one site combining everything, instead of + disconnected pages. +* Good, because `src/package_name/` never accumulates generated `.qmd`/`_quarto.yml` artifacts — quartify's + output is immediately relocated out of the source tree. +* Bad, because the "API Reference" sidebar section in `docs/_quarto.yml` needs one manual entry per + added/removed source module — quartify gives no way to auto-discover this. +* Unknown/risk: `{{< include >}}` splices README's markdown in literally, with no path rewriting — every + repo-relative link in README had to be converted to an absolute GitHub URL so it resolves correctly both on + GitHub and inside the transcluded docs page (done as part of this change). + +## Confirmation + +`docs/_quarto.yml` and `docs/index.qmd` are committed. `docs/reference/` and `docs/html/` are gitignored +(fully regenerated by `just docs-build` / CI every run). `justfile`'s `docs-build` recipe and +`.github/workflows/generate-docs.yml` both run the same two-stage pipeline: generate + relocate quartify's +output, then `quarto render docs/`. + +## Links + +| Type | Links | +| -----| ------| +| **ADRs** | | +| **Issues** | | +| **PRs** | | diff --git a/docs/architecture/adr/index.md b/docs/architecture/adr/index.md index fd2e904..b54699a 100644 --- a/docs/architecture/adr/index.md +++ b/docs/architecture/adr/index.md @@ -5,3 +5,4 @@ | [ADR-001: Use Architecture Decision Records](001-use-architectural-decision-records.md) | 🟢 Accepted | Use ADRs to explain the rationale behind architecturally significant design choices for future developers and AI assistants | | [ADR-002: Use prek for git hooks](002-use-prek-for-git-hooks.md) | 🟢 Accepted | Use prek, a dependency-free Rust binary, to run Git hooks with no Python/uv requirement | | [ADR-003: Manage R dependencies with rv](003-manage-r-dependencies-with-rv.md) | 🟢 Accepted | Use rv, not renv/packrat, for declarative R dependency management | +| [ADR-004: Unify docs into a single Quarto website](004-unify-docs-into-single-quarto-website.md) | 🟢 Accepted | Combine README, architecture/ADR markdown, and quartify-generated API reference into one Quarto website | diff --git a/docs/index.qmd b/docs/index.qmd new file mode 100644 index 0000000..f8cba1c --- /dev/null +++ b/docs/index.qmd @@ -0,0 +1 @@ +{{< include ../README.md >}} diff --git a/justfile b/justfile index dc961a3..abe0501 100644 --- a/justfile +++ b/justfile @@ -32,9 +32,12 @@ format: test: Rscript -e "testthat::test_dir('src/package_name/__tests__')" -# Build docs (Quartrify) +# Build docs (Quartify generates reference qmd, Quarto renders the docs/ website) docs-build: - Rscript -e "quartify::rtoqmd_dir('src/package_name/', render = TRUE, output_html_dir = '../../docs/html', exclude_pattern='__tests__')" + Rscript -e "quartify::rtoqmd_dir('src/package_name/', create_book = FALSE, render_html = FALSE, exclude_pattern = '__tests__')" + rm -rf docs/reference && mkdir -p docs/reference + for f in src/package_name/*.qmd; do mv "$f" "docs/reference/$(basename "$f" | sed 's/^_*//')"; done + quarto render docs/ # Install pre-commit hooks (via prek) pre-commit-install: From 27bfd8b7ec372a1e393ec54b42f5ff4db6575f26 Mon Sep 17 00:00:00 2001 From: novica Date: Sat, 4 Jul 2026 15:41:58 +0200 Subject: [PATCH 2/2] fix: drop __init__.qmd from generated API reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit __init__.r in a box module is just re-export wiring (box::use(...)), not a documented module — its converted qmd is normally empty of real content. Exclude it in docs-build before relocating quartify's output, and drop the corresponding "Package overview" nav entry. Assisted-by: Claude Sonnet 5 --- .github/workflows/generate-docs.yml | 2 ++ docs/_quarto.yml | 13 +++++-------- justfile | 2 ++ 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/.github/workflows/generate-docs.yml b/.github/workflows/generate-docs.yml index eed5e7e..d7c3288 100644 --- a/.github/workflows/generate-docs.yml +++ b/.github/workflows/generate-docs.yml @@ -43,6 +43,8 @@ jobs: run: | Rscript -e "quartify::rtoqmd_dir('src/package_name/', create_book = FALSE, render_html = FALSE, exclude_pattern = '__tests__')" rm -rf docs/reference && mkdir -p docs/reference + # __init__.r is just re-export wiring (box::use(...)), not a documented module — drop its qmd + rm -f src/package_name/__init__.qmd for f in src/package_name/*.qmd; do mv "$f" "docs/reference/$(basename "$f" | sed 's/^_*//')"; done - name: Render docs site (Quarto) diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 7d7a9cf..64a8fcf 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -10,7 +10,7 @@ website: text: Home - href: architecture/index.md text: Architecture - - href: reference/init.qmd + - href: reference/hello.qmd text: Reference right: - icon: github @@ -25,13 +25,10 @@ website: - architecture/adr/index.md - section: "API Reference" contents: - # Generated by quartify (see justfile's `docs-build`), one file per src/package_name/*.r - # module — this list isn't auto-discovered and needs a manual entry when a module is - # added or removed. Filenames have leading underscores stripped on relocation (e.g. - # __init__.qmd -> init.qmd) since Quarto excludes underscore-prefixed files from the - # project by default. - - text: "Package overview" - href: reference/init.qmd + # Generated by quartify (see justfile's `docs-build`), one file per documented module + # under src/package_name/*.r — this list isn't auto-discovered and needs a manual entry + # when a module is added or removed. __init__.r is excluded (see docs-build): it's just + # box::use() re-export wiring, not a documented module. - text: "hello" href: reference/hello.qmd diff --git a/justfile b/justfile index abe0501..3cd946f 100644 --- a/justfile +++ b/justfile @@ -36,6 +36,8 @@ test: docs-build: Rscript -e "quartify::rtoqmd_dir('src/package_name/', create_book = FALSE, render_html = FALSE, exclude_pattern = '__tests__')" rm -rf docs/reference && mkdir -p docs/reference + # __init__.r is just re-export wiring (box::use(...)), not a documented module — drop its qmd + rm -f src/package_name/__init__.qmd for f in src/package_name/*.qmd; do mv "$f" "docs/reference/$(basename "$f" | sed 's/^_*//')"; done quarto render docs/