docs: Add readthedocs examples

[bollwyvl]

references

• starts More documentation for hosted platform integration #1356
• supersedes docs: Document ReadTheDocs approaches #1408

changes

• update examples/README.md
• add two examples/readthedocs-*

[ruben-arts]

Thank you @bollwyvl sorry for the slow response, I missed it for some reason. I added some more platforms which makes the examples runable from all platforms.

What is the reason for using mamba to install pixi. Instead of using a pixi-docker image?

[ruben-arts]

What about adding a test task which can run in CI, we have a tests/test_examples.sh which runs some of our examples in the CI to verify no weird behavior was introduced.

Not a must, but could be a good example to run more often.

[bollwyvl]

Seems out-of-scope for this PR (which, if you'll recall, is the second PR to try to get this content based on trying to share my experiences using pixi to get open source work done), but can do so if we're spinning for the CF issue.

I'm likely not qualified to add test tasks to each of the examples, as many of them are intended to be interactive, and may require exotic techniques to properly test beyond

• does it pixi r install
• does pixi r start result in a process that stays running for more than five seconds

The interesting wrinkle in this case is that one would really want pixi to be matrixed across:

• a minimum-pixi or whatever from old pixi cannot parse parse project manifests from new version #1346 as a baseline
  • as a stopgap, examples/p{ixi,yproject}.toml#tool.pixi-example-test could provide a temporary place for this, as the point is they continue to work with older versions
• the system-under-test nightly or whatever from an upstream GHA artifact from that last-good main
  • the rust build is... not fast, and this matrix will be... really not fast

However... also out-of-scope, and while this could be done out-of-band, this points to a very real use case for #1285. As I keep thinking about these issues, I keep coming back to a future grammar of depends-on (along with #1330, #1272).

this repo's root pixi.toml would only need to declare a single task

[tasks.test-examples]
depends-on = [
  {task = "test", project=["examples/*/"]},
]

The advantage here over punting to a .sh (always a problem on stock windows) would be in e.g. reporting and listing (a la #1434, #1344). Indeed, being able to pixi task list --status (and always in --json) to show the last-known error code would be wonderful for projects trying to adopt pixi at scale.

[ruben-arts]

I'm likely not qualified to add test tasks to each of the examples, as many of them are intended to be interactive, and may require exotic techniques to properly test beyond

Don't worry was just curious if you knew a neat way of testing the RTD examples in an on interactive way. I've never tried RTD in a production setting myself, that was the source of the question.

When we get pixi build (which depends on rattler-build) in a proper state, we'll most likely try to start on a way to do "workspaces". Which in my idea of a "workspace" includes a lot of those ideas. Which our examples would be an first user of. So please hold tight! 😄

[bollwyvl]

As with any third-party integration, the RTD case wouldn't be testable without some kind of real event (usually a commit) and then an API request. It would require secrets, which would ratchet up the complexity significantly.

pixi build (which depends on rattler-build)

Welp... not to keep telling you and your team your business, but... maybe just a little: this perspective suggests a team's goal is delivering a matrix of .conda packages as a first-class output of both its subprojects and its ultimate deliverable. This is totally awesome for e.g. conda-forge, which basically exists only to ship .conda packages, and indeed, a near term PR to use pixi in conda-smithy would be... amazing. Indeed, miniforge would benefit substantially from this, if #1375 (or even #1216, as a stopgap) took some of that pain away.

In a corporate, research, or even large open source project setting, the ultimate output of a whole team's multi-month effort might be a horrifying contraption of nodejs -> python -> rattler -> constructor -> packer (plus a bunch of docs, tests, static analysis reports, etc.), which pixi could probably reduce to a single command on a devleoper's desktop. But this is probably not feasible for every task to be defined inside a single pixi.toml file (and even YAML &anchors might not help too much) and pixi-calling-pixi-from-cmd feels... bad.

Looking across even smaller open source projects, there's an enormous value proposition in a generalized, self-documenting, observable, schema-constrained, rework-reducing task model that does predictable, non-magical environment provisioning based on a number of smaller projects, stored in one or more repos, that keeps working, even for historic builds.

[bollwyvl]

What is the reason for using mamba to install pixi. Instead of using a pixi-docker image?

At a guess: as a startup providing basically free building and hosting, and encouraging "golden path" builds based on relatively simple toolchains, RTD doesn't want to provide support for when an unlimited number of docker images of indeterminate size and security posture break, or otherwise screw up their infrastructure.

[ruben-arts]

At a guess: as a startup providing basically free building and hosting, and encouraging "golden path" builds based on relatively simple toolchains, RTD doesn't want to provide support for when an unlimited number of docker images of indeterminate size and security posture break, or otherwise screw up their infrastructure.

I see, my assumption from looking at the configuration was that it could run any docker image. But if it is just a selected set, this makes total sense.

[bollwyvl]

could run any docker image

Yep, here's the infra repo for their images available to open source projects, and the last discussion about it:

https://github.com/readthedocs/readthedocs.org/issues/6162

[ruben-arts]

Thanks, it's going in!