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
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
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/_buildWhich launches a server and rebuilds the documentation on change to the documentation.
Would this be something devs are interested in?
Changes needed:
sphinx-autobuildas a dependencypixi run doc-watchto spin up the server (and still havepixi run docin case people just want to build and not watch)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