pydata / pydata/xarray

DOC: Add Sphinx-autobuild to documentation environment

Open
#10,786 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

needs triage
Dominant language
Python
Stars
4.2k
Forks
1.4k
Avg merge
2d 15h
Merged PRs (30d)
14

Description

What is your issue?

I realised while doing #10732 that the contributing instructions for building documentation is the following:

https://github.com/pydata/xarray/blob/a3bd20d85ff03c70e54f3c777d1b2f385f514074/doc/contribute/contributing.rst#L452-L479

I find this build then manually open to be a bit out of my normal workflow (and for what I've seen quite a bit), as opposed to using sphinx-autobuild something like

sphinx-autobuild docs docs/_build

Which launches a server and rebuilds the documentation on change to the documentation.

Would this be something devs are interested in?

Changes needed:

  • add sphinx-autobuild as a dependency
  • add a task pixi run doc-watch to spin up the server (and still have pixi run doc in case people just want to build and not watch)
  • update contributing instructions

I can do this alongside the PR for #10732 (preferred from my end) or in a subsequent PR if you'd prefer that.

I searched the issue tracker - couldn't find a mention of sphinx-autobuild

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with doc/contribute/contributing.rst and the existing pixi run doc workflow, then locate the project configuration for documentation dependencies and tasks. Done means a pixi run doc-watch command starts the documented server and rebuilds on documentation changes, while the contributing instructions explain both workflows.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, tooling
Issue type
Feature
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.