Skip to content

DOC: Add Sphinx-autobuild to documentation environment #10786

@VeckoTheGecko

Description

@VeckoTheGecko

What is your issue?

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

Building the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~
To build the documentation run::
cd doc/
make html
Then you can find the HTML output files in the folder ``xarray/doc/_build/html/``.
To see what the documentation now looks like with your changes, you can view the HTML build locally by opening the files in your local browser.
For example, if you normally use Google Chrome as your browser, you could enter::
google-chrome _build/html/quick-overview.html
in the terminal, running from within the ``doc/`` folder.
You should now see a new tab pop open in your local browser showing the ``quick-overview`` page of the documentation.
The different pages of this local build of the documentation are linked together,
so you can browse the whole documentation by following links the same way you would on the officially-hosted xarray docs site.
The first time you build the docs, it will take quite a while because it has to run
all the code examples and build all the generated docstring pages. In subsequent
evocations, Sphinx will try to only build the pages that have been modified.
If you want to do a full clean build, do::
make clean
make html

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    needs triageIssue that has not been reviewed by xarray team member

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions