is there like a dev presentation of pants internal...
# general
is there like a dev presentation of pants internals ?
have you seen the pants task developer’s guide too? i would love to know if you see any gaps in those docs (or rather if there was anything they didn’t explain at all)
yes, I've read it. It gives a lot of details but IMHO it lacks kind of "the big picture" of what is the control flow. With python being dynamicly type I have much trouble (at least since I'm starting using pants) figuring out what is in the context and how it got there. Given my use case I also find missing an explanation on how you plug a cli written in another language. Apart from that the doc is really complete
The build dictionary and reference are really great even if I think it misses the list of possible values when it's an enum of string.
Another confusing thing is the
--[no]-some-option (Default = True)
. So is it the
or the
that is defaulted to True ? In the end I got that it's the former, but it really puzzled me at first
it absolutely lacks a big picture view of the control flow. with the v2 engine being introduced that control flow is changing, but that's definitely not there and would be useful to add
if I think it misses the list of possible values when it's an enum of string.
there is i think a subtle bug rendering many types of options in the reference which is shown in several places, which i've tried to fix and may have, but i didn't push that branch. separarately, this pr: is an example of another documentation bug, so it's definitely happening, and reporting errors is useful. if you have a simple repro of the error (just a link to the documentation page and the option value which isn't being rendered) that would be a useful github issue to make, i think
i'm not sure how to address the
--[no]-some-option (Default = True)
bit. i agree that it's not obvious (and things not being obvious at the start is important! the square brackets around
are used in a lot of cli tools to denote an optional argument, and the expected interpretation is that
would be considered the optional part of the option name, which would then still default to
. if the option defaults to
, though, i think it looks like that might be really confusing? has the answer to this, but it's not clear if we should link that in
./pants help
, or something else, because without that context it's definitely just not clear. does anything jump to mind as being useful here?
about enum values, I don't think it's a doc generation error. I have the values of scope in mind (like 'runtime', 'compile' … ) it's not really an enum but there are usual cases.
I'm don't have any idea for now about the
--[no]-some-option (Default = True)
. If I come with one, I'll tell you. To be fair, it's not puzzling really long. It's just the first time you stumble upon you're like "wait, what ?". But you understand it quite quickly
about the enum values I have a good one here I think :
Copy code
--test-junit-default-concurrency=<str> (default: 'SERIAL')
Set the default concurrency mode for running tests not annotated with @TestParallel or @TestSerial.
hm, it looks like
in master has a test for that help output, and when i run
./pants help-advanced
, I can see e.g.:
Copy code
--glob-expansion-failure=<str> (one of: [ignore, warn, error] default: ignore)
    Raise an exception if any targets declaring source files fail to match any
    glob provided in the 'sources' argument.
which is an enum option. does that seem to match up with your desired output?
indeed, the junit_tests target doc I found
Copy code
java_tests: <Add description>
concurrency = ...,     One of 'SERIAL', 'PARALLEL_CLASSES', 'PARALLEL_METHODS', or 'PARALLEL_CLASSES_AND_METHODS'. Overrides the setting of --test-junit-default-concurrency. (default: None)