search

sphinx-doc / sphinx-autobuild

Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a hot-reload web server.
MIT License
523 stars 75 forks source link

Allow for generic build command (for use with jupyter-book) #99

Open amichuda opened 3 years ago

amichuda commented 3 years ago

I wanted to see if it was possible to use sphinx-autobuild with building with jupyter-book. As of now it seems that this is possible as the get_builder function runs sphinx explicitly. Would it be possible to have the server watch a sourcedir and outdir but for a generic command (such as jb build)?

welcome[bot] commented 3 years ago

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
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! :tada:

pradyunsg commented 3 years ago

You can add --pre-build "jb build" today, to run that build and pass additional --watch options as well.

As it stands, this is a really thin wrapper over livereload (the Python package). It might make sense for jupyter-book to get a serve command that uses that directly. FWIW, it's even pretty straightforward to write a script that does the right thing, using only livereload.

import subprocess
import livereload

def run():
    subprocess.run(["jupyter-book", "build"])

server = livereload.Server()
server.watch('docs/source', run)

server.serve(root='docs/build/html')
ashwin153 commented 3 years ago

I want to use sphinx-autorebuild with sphinx-multiversion, which itself wraps the sphinx-build command to build versioned documentation. Would it be possible to parameterize the currently hard-coded sphinx-build invocation via a command line option (e.g., --build-cmd)?

chrisjsewell commented 2 years ago

Heya, as I note in https://github.com/executablebooks/jupyter-book/issues/1455:

jupyter-book now has the ability for external packages to "inject" commands in to its CLI, this is for example how jupyter-book toc works (executablebooks/sphinx-external-toc@ec4a439/setup.cfg#L43-L44). By the same mechanism, sphinx-autobuild could inject a jupyter-book serve command, that is customized for jupyter-book