Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add readthedocs examples #1423

Merged
merged 4 commits into from
Jun 12, 2024

Conversation

bollwyvl
Copy link
Contributor

references

changes

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

@bollwyvl bollwyvl changed the title Add readthedocs examples docs: Add readthedocs examples May 21, 2024
@bollwyvl bollwyvl marked this pull request as ready for review June 5, 2024 02:06
@ruben-arts
Copy link
Contributor

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?

examples/readthedocs-extend/pixi.toml Show resolved Hide resolved
rtd = ["docs", "rtd"]
docs = ["docs", "dev"]

[feature.dev.tasks.start]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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! 😄

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor Author

bollwyvl commented Jun 5, 2024

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
Copy link
Contributor

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
Copy link
Contributor Author

bollwyvl commented Jun 5, 2024

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

Copy link
Contributor

@ruben-arts ruben-arts left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, it's going in!

@ruben-arts ruben-arts enabled auto-merge (squash) June 12, 2024 15:31
@ruben-arts ruben-arts merged commit 1a08bd2 into prefix-dev:main Jun 12, 2024
25 checks passed
@bollwyvl bollwyvl deleted the gh-1356-rtd-examples branch June 12, 2024 18:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants