Skip to content

docs: drop the inverted draft setup (#948) - #949

Merged
ocots merged 1 commit into
mainfrom
docs/drop-draft-overrides
Sep 2, 2026
Merged

docs: drop the inverted draft setup (#948)#949
ocots merged 1 commit into
mainfrom
docs/drop-draft-overrides

Conversation

@ocots

@ocots ocots commented Sep 2, 2026

Copy link
Copy Markdown
Member

Closes #948.

Before

docs/make.jl: draft = true global, and 43 content pages each carrying

```@meta
Draft = false

to opt back into `@example` / `@repl` execution — a double negative across 44 files. The
guided tour additionally got `Draft = false` injected by a Literate `postprocess`.

- A new page without the marker is silently **not executed**.
- No fast `draft = true` pass possible (nav / link / `@ref` / `@extref` / render checks)
  without stripping 43 markers first.

## After

- `make.jl`: `draft = false` default — every page executes (what a published build does).
  Flip the one flag locally for a fast build.
- 43 `@meta Draft = false` blocks removed; guided-tour injection removed.
- `make.jl` comments refreshed; stale `:example_block` note trimmed (CTParser#341 closed).
- Opt a single page **out** of execution with `Draft = true` in its `@meta`.

Safe: only `api/ecosystem.md` (no code) and generated `guided-tour.md` lacked a marker;
neither relied on being skipped.

## Verification

Full local build, `julia --project=. docs/make.jl` (`draft = false`):

- exit 0; `Doctest`, `ExpandTemplates`, `ExtCrossReferences`, `CrossReferences`,
  `CheckDocument`, `RenderDocument` all pass
- every `@example` / `@repl` executes — inline SVG figures present in `results/plot.html`,
  `getting-started/guided-tour.html`, …; computed values rendered in
  `getting-started/first-problem.html`
- `@extref` unresolved: **0**; `@ref` unresolved: **0**
- only residual warnings: 2× "Failed to load inventory CTDirect/CTParser" (local
  `objects.inv` absent → network fallback), deploy-env, favicon — all pre-existing

`docs/src/assets/Manifest.toml` deliberately **not** touched here — no dep/compat change;
the CTModels 0.19.4-beta / CTBase 0.30.4-beta Manifest refresh belongs in its own PR.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

`docs/make.jl` shipped `draft = true` globally with a `@meta Draft = false`
block repeated across 43 pages to opt each one back into execution — a double
negative, and it blocked a fast `draft = true` pass for link/nav checks.

- `make.jl`: `draft = false` default (every page executes — what a published
  build must do); flip the one flag locally for a fast build.
- Remove the 43 per-page `@meta Draft = false` blocks.
- Remove the guided-tour `Draft = false` Literate injection.
- Refresh the make.jl comments; trim the stale :example_block note (CTParser#341
  closed).

A page that must stay drafted now opts out with `Draft = true` in its `@meta`
(one marker) instead of 43 pages opting in.

Verified: full `julia --project=. docs/make.jl` with `draft = false` — exit 0,
all @example/@repl blocks execute (figures embedded, computed values rendered),
doctests run, @extref 0, @ref 0.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@ocots ocots added documentation Improvements or additions to documentation run documentation Trigger Documentation labels Sep 2, 2026
@ocots
ocots merged commit e6397e2 into main Sep 2, 2026
12 of 14 checks passed
@ocots
ocots deleted the docs/drop-draft-overrides branch September 2, 2026 15:50
ocots added a commit that referenced this pull request Sep 2, 2026
Both cross-reference backlogs are cleared:
- @extref: `_strategy_parameter` (#944) + CTModels' extension docstrings
  (CTModels.jl#428, shipped in CTModels 0.19.4-beta)
- @ref/DOCPCache: CTDirect#630 (closed)

So `makedocs` no longer needs `warnonly` — an unresolved `@ref`/`@extref`, or a
broken `@example`/`@repl`, now fails the build. Verified with the sibling
inventories forced to resolve remotely (as on CI): full build, exit 0, zero
unresolved references.

Also:
- docs env moves to CTBase 0.30.4-beta + CTModels 0.19.4-beta;
  docs/src/assets/Manifest.toml regenerated.
- Project.toml 2.2.0-beta -> 2.2.1-beta (docs-infra patch, no API/runtime
  change); CHANGELOG + BREAKING get a 2.2.1-beta section collecting this plus
  the already-merged #944 (extref), #949 (draft=false default) and #951
  (CI-only remote inventories).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation run documentation Trigger Documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: drop the inverted draft setup (draft=true global + 43 per-page Draft=false overrides)

1 participant