-
-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Open
Labels
needs triageIssue that has not been reviewed by xarray team memberIssue that has not been reviewed by xarray team member
Description
What is your issue?
I realised while doing #10732 that the contributing instructions for building documentation is the following:
xarray/doc/contribute/contributing.rst
Lines 452 to 479 in a3bd20d
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 havepixi 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
Labels
needs triageIssue that has not been reviewed by xarray team memberIssue that has not been reviewed by xarray team member