docs: Document ReadTheDocs approaches

[bollwyvl]

references

• starts More documentation for hosted platform integration #1356

changes

• mkdocs.yml
  • create Third-Party Integrations section under Advanced
    • add ReadTheDocs
• docs/advanced/readthedocs.md
  • add a description of RTD
  • add the smallest-possible example with mkdocs
  • add a more advanced example with sphinx and a heavy dep

    • this is extracted from my experience with a work-in-progress project

[pavelzw]

can we raise an issue in the readthedocs repository for proper pixi support that we can link to in our docs?

[bollwyvl]

can we raise an issue

Not sure of the scope of we in this comment!

RTD is (understandably) conservative in what they add and then have to support in the build layer. Once requested, it could take rather a long time to get merged:

• Ability to pin Sphinx and friends in a conda environment readthedocs/readthedocs.org#3829
  ... and then would have to account for RTD extras in a predictable way:
• Support conda for builds readthedocs/readthedocs.org#857

Further, I think some of the first-party warning banners would have to come off the pixi API surface (e.g. minimum version, manifest versions, lockfile version, etc).

I feel like having something documented, even if was prefaced with a banner linking to such an issue, is a pragmatic step forward which would provide value to new and prospective pixi users.

[ruben-arts]

To be honest, and respectfully, I don't think this document fits our documentation. It's not really a third-party integration but more a way to run pixi in a Docker image with some extra steps specific to RTD. In contrast, the GitHub Action and the Authentication are genuinely pixi tools.

When pixi becomes a directly supported tool by RTD, this would make more sense to me.

However, I'm open to adding it as an example, possibly including this document as a README. We can also extend the examples section in the documentation. Would that suffice for your idea?

[bollwyvl]

Sure, examples are great. Tested examples are of course better but there's some complexity there with third-party providers that expect a whole repo... and putting a rust build inside RTD is a poor use of donated resources.