docs: include full _copier_conf attributes list

[wgordon17]

No description provided.

[wgordon17]

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]

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]

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]

@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

[codecov]

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]

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

[sisp]

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]

@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]

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]

@sisp Thoughts on the content for this one?

[wgordon17]

@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 🤦‍♂️