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: Document ReadTheDocs approaches #1408

Closed

Conversation

bollwyvl
Copy link
Contributor

@bollwyvl bollwyvl commented May 18, 2024

references

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

@bollwyvl bollwyvl changed the title Document ReadTheDocs approaches docs: Document ReadTheDocs approaches May 18, 2024
@bollwyvl bollwyvl marked this pull request as ready for review May 18, 2024 18:38
@pavelzw
Copy link
Contributor

pavelzw commented May 18, 2024

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

@bollwyvl
Copy link
Contributor Author

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:

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

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

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.

@bollwyvl bollwyvl closed this May 21, 2024
@bollwyvl bollwyvl mentioned this pull request May 21, 2024
2 tasks
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.

3 participants