Fully document pixi.toml format

[kszlim]

Problem description

Hi, I think to increase the ease of adopting pixi, please document fully all the different options in the pixi.toml format and explain each section.

Most of the basics are available, but when I look at examples, there are some uses like (build-dependencies) and host/target that aren't fully documented.

Also some references to other package managers and their features and how they can be replicated within pixi would be helpful (for example dependency groups or optional dependencies).

[baszalmstra]

Yes you are completely right. A detailed document about the details of the pixi.toml is already underway. Should probably be online this week. We are also planning on writing some comparisons with other package managers but I cant give you a date yet.

[baszalmstra]

And here it is: https://prefix.dev/docs/pixi/configuration

[kszlim]

Awesome, I see there are a lot of proposed enhancements to pixi.toml (as well as supporting pyproject.toml). It would be great to ensure that any such changes are also documented as soon as they land!

Eg.:
#79
#179
#239
#175

Thanks! Pixi is looking really great!

I also notice that you reference pixi build on that page, but the corresponding CLI page doesn't say anything about pixi build

[baszalmstra]

Yeah we should definitely pay attention to update the docs as we add/change features. We will be merging the docs in this repository soon so we can make sure they are updated with a PR.

pixi build is indeed still in development (see this PR: #85). Do you think it would be better if we'd remove that reference from the documentation until that feature lands? Im a bit on the fence about it because some of the configuration in the pixi.toml is mostly there to support pixi build.

[kszlim]

I think it'd be fine to keep reference to it, but make note that it's coming soon (and if you have time add a page about pixi build with a huge header that says it's not available yet and links to the issue).

[ruben-arts]

I updated it in the new documentation!