https://pantsbuild.org/ logo
Join Slack
Powered by
Hi! I finished rewriting our docs for Targets to g...
# general
h
Hi! I finished rewriting our docs for Targets to get more to the point. And to also talk about "target generation", which we were always doing since Pants 2.0 but was not explicitly modeled until Pants 2.8 (e.g. 
python_tests
generating 
python_test
targets) Any feedback would be welcomed! https://www.pantsbuild.org/v2.8/docs/targets
https://www.pantsbuild.org/docs/targets for the original Feel free to comment here or "suggest edits" in the top right corner 🙂
w
looks great: thanks.
given that the Target generators section says that we recommend using them over per-file targets, it’s odd that they are below single-file targets on the page
folks should only very rarely need to create single file targets, right?
which also means that they will overwhelmingly interact with the 
sources
argument rather than the 
source
argument
h
My thinking was: start with the simplest thing possible, the atom targets. They are the core building blocks. Also the docs are pretty simple on those. So get through those quickly Then, get into the really important parts with target generation, which end up talking up half the page
Would it help if I change the first few sections to focus more on file-less targets like 
pex_binary
rather than 
python_test
? The reason I didn't do that is it is more abstract
w
while i agree that the atoms are the most important… i think that the atom is the file, rather than necessarily the file target
and discussing how the per-file targets are implemented first, rather than what you do to create them is a bit too detailed. it’s more architecturey than “what do i put in my BUILD file”
h
Okay I think I can rewrite the examples to talk about target generators sooner while still saving the nitty gritty details until the end. Will fork the page. Thanks for the feedback! (Altho probably after finishing other docs changes and the blog, those seem even higher priority)
w
sounds good… thanks!
fwiw, i’ve a bit more experience using pants in a from-scratch `tailor`’d repo recently, and the effect of 
tailor
is that ~everything renders as a file address, except tests… so particularly for new folks, i expect that they’ll think that “target” means “a file, most of the time”
đź‘Ť 1
h
I don't think this is the time and place to have this discussion, but: ack. And I've been wondering how desirable that is, whether it suggests a false friend when it's not really a file (but also mostly is) Lots to discuss/figure out in the near future!
đź‘Ť 1
@witty-crayon-22786 fyi I finished the rewrite. Less dramatic than I expected, mostly just changed the examples
w
looks great, thanks. i think that introducing file addresses early in https://www.pantsbuild.org/docs/targets#target-addresses might make sense, since that’s what folks will see 95% of the time. but not a huge deal.
đź‘Ť 1
h
I'll mention reading below to see what the address of generated targets are. It's too nuanced to get into the details that early imo
Open in Slack
PreviousNext
Powered by