The TOML web linter that I believe our documentation recommends to use chokes on valid

pants.toml

format:

[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/)

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

Sweet. I should of looked before posting.

Is this Pants docs or your org’s docs? We used to recommend toml lint until realizing this problem

I think I got it from Pants docs.

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

I prefer the

.toml

format. Now that I know about the version issue, we can ignore that error when checking.

Glad you like it :) TOML config files was a 10% side project because I got really frustrated with Ini hah

Maybe that's something I can help with.

Oh, oops. I wasn’t a member of that channel. Gotta run to a meeting but will look at your question after

That sounds like something I could take on. What timescale are you looking to get it implemented?

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)

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.

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.

Possibly we can use "Custom Pages" for this