Skip to content

Improve docs build ergonomics#250

Merged
jl-wynen merged 3 commits intomainfrom
docs-ergonomics
Mar 18, 2026
Merged

Improve docs build ergonomics#250
jl-wynen merged 3 commits intomainfrom
docs-ergonomics

Conversation

@jl-wynen
Copy link
Member

This PR makes a couple of changes:

  • It adds missing paths to gitignore
  • It moves the doctrees into the packages so that they don't collide with each other in /tmp (Plus, /tmp is a Unix path)
  • It adds a separate docs task for each package. Now we can run the docs using
pixi run docs-essimaging

Unfortunately, I could not find a way to reuse the sphinx command and also automatically activate the right environment.

How this works

Take for example ESSreduce: We have a docs-essreduce feature. This feature contains a task also called docs-essreduce. This connects the task to that feature. Since we only have one environment (also called ess-reduce) that contains the docs-essreduce feature, pixi knows to use that environment for this task. (And all tasks in this feature.)
This can be confusing, especially since there are 3 different things with the same name :/

The previous line only applies to the base directory, not the package dirs..
@nvaytet nvaytet added the documentation Improvements or additions to documentation label Mar 17, 2026
@jl-wynen
Copy link
Member Author

Correction: I had to add default-environment to the docs-essreduce task because the docs-essreduce feature appears in all docs-* environments and pixi was unable to figure out which env to use on its own.

@jl-wynen jl-wynen merged commit 984fead into main Mar 18, 2026
8 checks passed
@jl-wynen jl-wynen deleted the docs-ergonomics branch March 18, 2026 08:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants