jupyter-book watch command

[patrickmineault]

Description / Summary

It would be nice if jupyter books automatically rebuilt upon changing a file, and fresh files were served over a development server.

Value / benefit

You need to keep several windows open to develop a jupyterbook - vscode, a terminal, a browser window, maybe the inspector. On a laptop, it's a lot of windows to keep around. It would be nice not to have to look at one of those windows. It would be nice to always be one Ctrl+R away from seeing the latest build of the docs.

Implementation details

The sphinx book theme has support for live building using the tox -e docs-live command. I presume this would be substantially similar to this.

Tasks to complete

No response

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[leouieda]

@patrickmineault you can do this with the livereload package. For example, I use this with JupyterBook here: https://github.com/leouieda/pgcap/blob/main/tools/serve.py

When developing, I call python serve.py (or in my case actually make serve) and everything rebuilds and reloads (no Ctrl + R needed) whenever a source file changes.

[patrickmineault]

@leouieda that's very helpful! How about we put this in the docs then, say under Build your book outputs?

[chrisjsewell]

Heya, a couple of things to note here:

1. there has been a previous discussion about this: live reload not working with make serve #213 (not really sure why it was closed)
2. It was certainly in my thinking to do this with sphinx-autobuild: Rebuild throttling sphinx-doc/sphinx-autobuild#87
3. jupyter-book now has the ability for external packages to "inject" commands in to the CLI, this is for example how jupyter-book toc works (https://github.com/executablebooks/sphinx-external-toc/blob/ec4a43904dde7e24b3d08bd2c717c696ef20aff9/setup.cfg#L43-L44). By the same mechanism, an external package (like sphinx-autobuild) could inject a jupyter-book serve command
   (see also Allow for generic build command (for use with jupyter-book) sphinx-doc/sphinx-autobuild#99)

[leouieda]

@chrisjsewell that seems like a more reliable solution that requires less manual intervention from users

[patrickmineault]

I saw that this is now feasible with sphinx-autobuild:

jupyter-book config sphinx .
sphinx-autobuild . _build/html -b html

There's a hint about this in the Sphinx section of the docs, but if it's relevant I can draft a larger section on setting this up in the docs.