Skip to content

docs: include full _copier_conf attributes list #2127

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.

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
wants to merge 2 commits into
base: master
Choose a base branch
from

Conversation

wgordon17
Copy link
Contributor

No description provided.

@wgordon17
Copy link
Contributor Author

Here's the funny thing, I hadn't even noticed the introduction sentence with

_copier_conf includes a representation of the current Copier [Worker](https://copier.readthedocs.io/en/stable/reference/main/#copier._main.Worker) object

until I went back and looked after I had found the Attributes table. Now that I know it's there, this PR is really just intended to give some additional clarity (feel free to close as well if you feel that the extra Note shouldn't be necessary ¯\_(ツ)_/¯ )

@sisp
Copy link
Member

sisp commented May 8, 2025

Thanks for aspiring to improve the docs! 🙇 I agree that the render context isn't documented as well as it could be. There's only one concern I have with this addition: copier.main will become an internal-only module and copier.main.Worker will become an internal-only class. So the API reference will become unavailable. IMO, we should model public interfaces (like the copier.yml content specification and the render context) with Pydantic to have declarative and explicit representations as single source of truth of information, static typing, runtime validation, and (exportable) JSON schema. I've resumed work on this long-standing idea of mine, but it's a quite massive change. In the meantime, how about documenting the render context explicitly and manually? We'll need to keep it synchronous with the actual implementation, but changes are quite infrequent.

@wgordon17
Copy link
Contributor Author

Hey @sisp, thanks for the review. If y'all are good with ensuring that the docs are just always in-sync, I'm absolutely happy to help copy over the data. Let me do a quick fix, and I'll let you give it another review 😊

@wgordon17 wgordon17 changed the title docs: clarifying _copier_conf attributes reference docs: include full _copier_conf attributes list May 8, 2025
@wgordon17
Copy link
Contributor Author

@sisp I think this should be ready for a review now. Direct link to docs preview: https://copier--2127.org.readthedocs.build/en/2127/creating/#_copier_conf

A few things that I adjusted (if you're OK with that)

  • Alphabetized the attributes to ideally make it easier to skim, versus the previous order matching _main.py
  • Included Defaults on the rows where I could easily see what the defaults were in _main.py
  • Added a NOTE in _main.py to hopefully provide a reminder to folks that any changes there need to also be reflected on the, now static, Attributes table in docs

Copy link

codecov bot commented May 8, 2025

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.03%. Comparing base (b4b40ad) to head (7a0a10d).

Additional details and impacted files
@@           Coverage Diff           @@
##           master    #2127   +/-   ##
=======================================
  Coverage   98.03%   98.03%           
=======================================
  Files          55       55           
  Lines        6005     6005           
=======================================
  Hits         5887     5887           
  Misses        118      118           
Flag Coverage Δ
unittests 98.03% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@wgordon17
Copy link
Contributor Author

@sisp Just checking if you're good with the changes?

Copy link
Member

@sisp sisp left a comment

Choose a reason for hiding this comment

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

Thanks for compiling the render context attributes table so meticulously! 🙇 I have a couple of suggestions regarding clarity, consistency, and style.

Seeing this table makes it much clearer (IMO) that the render context and Worker class attributes are not the same and not even as similar as it seemed with the previous documentation. Clarifying the render context is crucial for providing template authors with the necessary information to create good templates. Thanks for taking on this important task! 🙇

@wgordon17
Copy link
Contributor Author

@sisp awesome review, and definitely makes things clearer! I wonder...would it make sense to group setting attributes that are just sets of booleans, and then separate some of the more "in depth" attributes into their own group?

@sisp
Copy link
Member

sisp commented May 16, 2025

I think it's fine to keep all attributes in one table. There, they are sorted alphabetically and references to related settings are provided where applicable. Having a complete overview of all _copier_conf attributes in one table feels more useful than splitting them according to some rule that some may find intuitive and others may not.

I've noticed that the skip_answered setting isn't documented yet, and hence the Markdown reference isn't resolved. I've just created #2152 to add it.

I stumbled over one more thing: The settings attribute is still missing. Could you please add it?

@wgordon17 wgordon17 force-pushed the patch-2 branch 3 times, most recently from 0d51bf8 to 3b1f596 Compare May 31, 2025 14:05
| `pretend` | `bool` | When `True`, produce no real rendering.<br>See the [`pretend`][] setting for related information. |
| `quiet` | `bool` | When `True`, disable all output.<br>See the [`quiet`][] setting for related information. |
| `sep` | `str` | The operating system-specific directory separator. |
| `settings` | `pydantic.BaseModel` | Specified settings that control copier's behavior.<br>See the [`settings`][] page for related information. |
Copy link
Contributor Author

Choose a reason for hiding this comment

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

@sisp Thoughts on the content for this one?

@wgordon17 wgordon17 requested a review from sisp May 31, 2025 14:06
@@ -127,8 +127,8 @@ Attributes:
| `unsafe` | `bool` | When `True`, allow usage of unsafe templates.<br>See the [`unsafe`][] setting for related information. |
| `use_prereleases` | `bool` | When `True`, `vcs_ref`/`vcs_ref_hash` may refer to a prerelease version of the template.<br>See the [`use_prereleases`][] setting for related information. |
| `user_defaults` | `dict[str, Any]` | Specified user defaults that may override a template's defaults during question prompts. |
| `vcs_ref` | `str | None` | The VCS tag/commit of the template, `None` if the template is not VCS-tracked.<br>See the [`vcs_ref`][] setting for related information. |
| `vcs_ref_hash` | `str | None` | The VCS commit hash of the template, `None` if the template is not VCS-tracked. |
| `vcs_ref` | `str | None` | The VCS tag/commit of the template, `None` if the template is not VCS-tracked.<br>See the [`vcs_ref`][] setting for related information. |
Copy link
Contributor Author

Choose a reason for hiding this comment

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

@sisp we might have to disable autoformat for this PR (not sure if you can). Leaving the \ in str \| None caused the \ to actually print in the assembled docs, however removing it causes autoformat to think that it's a column separator and add extra whitespace which then breaks the table layout 🤦‍♂️

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants