https://pantsbuild.org/ logo
Powered by
b

brief-engineer-67497

11/08/2018, 5:19 PM
is there like a dev presentation of pants internals ?
a

aloof-angle-91616

11/16/2018, 11:38 PM
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)
b

brief-engineer-67497

11/19/2018, 8:51 AM
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 
some-option
or the 
no-some-option
that is defaulted to True ? In the end I got that it's the former, but it really puzzled me at first
a

aloof-angle-91616

11/20/2018, 12:31 AM
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: https://github.com/pantsbuild/pants/issues/5026 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 
[no]
are used in a lot of cli tools to denote an optional argument, and the expected interpretation is that 
[no]
would be considered the optional part of the option name, which would then still default to 
True
. if the option defaults to 
False
, though, i think it looks like that might be really confusing? https://www.pantsbuild.org/options.html 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?
b

brief-engineer-67497

11/20/2018, 2:08 PM
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.
a

aloof-angle-91616

11/27/2018, 1:58 AM
hm, it looks like 
test_help_formatter.py
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?
b

brief-engineer-67497

11/27/2018, 9:16 AM
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)
3 Views
Powered by