search

readthedocs / readthedocs.org

The source code that powers readthedocs.org
https://readthedocs.org/
MIT License
7.99k stars 3.58k forks source link

Add Pixi Build Support #11548

Open saulshanabrook opened 4 weeks ago

saulshanabrook commented 4 weeks ago

What's the problem this feature will solve?

I am switching to pixi and would like to use it to build my Sphinx docs in the RTD. It provides lockfiles and allows conda + pip installations of packages, and uses the uv resolver.

Describe the solution you'd like

It would be great to be able to specify pixi like you can with conda or pip in the read the docs config.

Alternative solutions

There is an alternative example posted in the Pixi docs (https://github.com/prefix-dev/pixi/pull/1423), but it requires installing Pixi through conda and then running a custom command to build the docs using pixi.

Additional context

humitos commented 4 weeks ago

(quick reply from the phone)

You can use build.commands to install pixi and use it, see https://docs.readthedocs.io/en/latest/config-file/v2.html#build-commands for more info about build.commands

akhmerov commented 4 weeks ago

build.commands seems to not be compatible with reusing existing tools for sphinx or mkdocs. I believe the idea of this issue is to only have the environment provided by pixi without needing to replicate the rest of the build process.

humitos commented 4 weeks ago

I understand. We don't currently support that use case. Also, from past discussions I can say we won't implement this "natively" and expose a configuration option like python.install that uses pixi or uv or poetry or any other package manager.

Instead, we will be working on a way to override pre-defined jobs, like build.jobs.install, and support this use case in a more generic way that will allow you to use any package manager:

build:
  jobs:
    install:
      - pixi global install starship
      - pixi global install ruff

(read more about this idea in this other GitHub comment)

As a workaround until we implement this, I recommend you to follow similar steps than Poetry users: https://docs.readthedocs.io/en/stable/build-customization.html#install-dependencies-with-poetry or something around those lines. If you find a way to do this that you are happy with, feel free to open a PR to update that documentation page.