https://pantsbuild.org/ logo
#general
Title
# general
j

jolly-midnight-72759

05/28/2020, 3:40 PM
The TOML web linter that I believe our documentation recommends to use chokes on valid
pants.toml
format:
Copy code
[GLOBAL]

backend_packages2.add = [
	"loop",
    "de",
]
Returns
Expected "=", Whitespace, or [a-z], [A-Z], [0-9], "-", "_" but "." found.
for the third line. Removing
.add
produces valid TOML according to this linter. Is the linter broken? (https://www.toml-lint.com/)
e

enough-analyst-54434

05/28/2020, 3:52 PM
I think that linter is broken. Dotted keys are supported. See the spec here and search for "Dotted keys": https://github.com/toml-lang/toml#keys
That site is based on TOML 0.4.0 and it looks like "Dotted keys" was added to the spec in 0.5.0: https://github.com/toml-lang/toml/tree/v0.5.0
So you might update your doc to note that linter is old and will report some erroneous errors given modern toml content.
j

jolly-midnight-72759

05/28/2020, 3:59 PM
Sweet. I should of looked before posting.
https://github.com/gscho/toml-lint hasn't been updated in two years.
h

hundreds-father-404

05/28/2020, 4:11 PM
Is this Pants docs or your org’s docs? We used to recommend toml lint until realizing this problem
There is an alternative syntax you can use with + and -, like pants.ini style. But it’s fairly clunky https://pants.readme.io/docs/options#config-file-entries-3
j

jolly-midnight-72759

05/28/2020, 4:15 PM
I think I got it from Pants docs.
We have not fully moved over to
pants.toml
yet.
h

hundreds-father-404

05/28/2020, 4:16 PM
I think I got it from Pants docs.
Very possible. We used to recommend it. We might still have some stale references - I’ll audit
We have not fully moved over to
pants.toml
yet.
No worries. We’re keeping support until 1.31. You can also have some with Toml and some with Ini till then for an incremental migration
j

jolly-midnight-72759

05/28/2020, 4:21 PM
I prefer the
.toml
format. Now that I know about the version issue, we can ignore that error when checking.
If I find the references again, I'll post it.
h

hundreds-father-404

05/28/2020, 4:22 PM
Glad you like it :) TOML config files was a 10% side project because I got really frustrated with Ini hah
👍 2
No, those are the old docs. New ones are at https://pants.readme.io/docs/welcome-to-pants We’ve been chipping away at moving stuff from the old ones to new ones
j

jolly-midnight-72759

05/28/2020, 4:23 PM
Maybe that's something I can help with.
❤️ 1
I asked a question about it in #documentation but have not followed up on it.
h

hundreds-father-404

05/28/2020, 4:27 PM
Oh, oops. I wasn’t a member of that channel. Gotta run to a meeting but will look at your question after
👍🏽 1
In general, any help is extremely appreciated! Thanks for the offer!
In particular, there would be a really helpful change to Pants that would help with the transition: teach the target-types goal how to output Json so that we can set up an API reference in the new site. If you’re interested, I can write out more and give some steps to get started :)
j

jolly-midnight-72759

05/28/2020, 5:56 PM
That sounds like something I could take on. What timescale are you looking to get it implemented?
h

hundreds-father-404

05/28/2020, 6:15 PM
That sounds like something I could take on
Yay! Before writing this up, I’m trying to figure out how this will work.. Have you used Swagger/OpenAPI before? readme.com has an API reference feature where you can upload an OpenAPI document and it will set everything up for you. I think this is what we’ll want to use, but if you look at their examples at https://docs.readme.com/developers/reference/api-specification, they’re all HTTP end points.
What timescale are you looking to get it implemented?
No particular deadline. The sooner it happens, the sooner people will have much better documentation on the site (compare
/pants targets --details=python_library
vs
./pants target-types --details=python_library
). But not something that needs to be done by a certain firm date. Whenever someone is contributing, we try to remind them that it’s voluntary and should only be because you want to learn something new and/or improve the project 🙂 What does help for roadmap planning is communicating rough timelines, like “I hope to get to this this next week”. (Keeping in mind that doesn’t need to be a firm commitment)
Okay I reached out to readme.com for their suggestions on how to get this working with their API feature 🙂 once I hear back, I’ll write up an issue about this.
j

jolly-midnight-72759

05/28/2020, 6:39 PM
Sounds reasonable and fit for a human to take on. I spell devOPS like 👈🏽 , so I've worked with Swagger/OpenAPI but in the context of a team and changes to an existing codebase.
💯 1
h

hundreds-father-404

05/28/2020, 6:42 PM
Indeed, that integration is what I’m hoping we can use! We’ll have to set up some logic because the new doc site is versioned, so we only want to sync certain GitHub branches to certain readme.com versions. But I think that’ll be possible to do. As a first step, we can just manually upload the OpenAI document.
👍🏽 1
My only concern is if readme.com’s API feature solely supports HTTP API endpoints. I’d be surprised if so.
Okay, turns out readme.com does only support REST API docs 🤦‍♂️ I’m thinking there are two approaches we could take: 1) Pretend Pants’ APIs are Rest APIs. For example, we have the “end points”
/target-types/python_library
and
options/pytest
. It’s a little weird to do this, e.g. it would show “GET” next to them all. But it would work I think and allow us to use Readme.com. 2) Use an external host for API docs. Have readme.com simply link to it. Any thoughts? Would #1 be confusing? cc @happy-kitchen-89482
h

happy-kitchen-89482

05/29/2020, 6:04 PM
Possibly we can use "Custom Pages" for this
👍 1
I'll look into it
7 Views