Open asmeurer opened 4 years ago
I don't think we can add a Sphinx builder for this (that's what -M would call).
Instead of adding a layer of complexity in the form of trying to automate the modification of the Makefile, I think documenting how a user can add a livehtml
task should be sufficient. The instructions need updating AFAICT.
I think with a little bit of modification on the Sphinx side it would be straightforward for projects like this to add custom Sphinx make entrypoints.
Just to be clear, I agree that sphinx-autobuild shouldn't attempt to modify people's Makefiles. If I'm reading the code in the module I linked to correctly, to make sphinx-build -M work it should be sufficient to monkeypatch Sphinx like
import sphinx.cmd.make_mode
sphinx.cmd.make_mode.BUILDERS.append(("", "livehtml", "to automatically rebuild the html whenever the sources change"))
def build_livehtml(self):
# Add code here to run livehtml
sphinx.cmd.make_mode.build_livehtml = build_livehtml
If for some reason that doesn't work we should work with Sphinx to make it so extensions can more easily extend this (and that should probably be done anyway so that they don't have to monkeypatch).
I haven't actually tried this, so if I'm missing something why this can't work let me know.
monkeypatch Sphinx
Uhhhhh... I'm not a fan of monkeypatching to provide functionality as part of an addon/extension.
Well then we circle back to "Sphinx should be modified so that extensions can more easily add makefile integrations.". Although I expect such a Sphinx modification would be nothing more than a register_make_mode()
function which would do exactly what I wrote here.
Indeed. I guess we're blocked on Sphinx making changes on their end. And, that seems unlikely given that they're trying to move away from generating makefiles: https://github.com/sphinx-doc/sphinx/issues/5618
I didn't know about that. Hopefully the new sphinx
command is properly extensible by extensions.
@tk0miya what are your thoughts on this? Is the new sphinx
command coming soon? Should Sphinx add a register_make_mode
function for extensions to add their own make entry points? Is it OK for extensions to patch sphinx.cmd.make_mode
as I described here https://github.com/GaretJax/sphinx-autobuild/issues/79#issuecomment-677812307?
I wonder if you've considered whether it's possible to add the Makefile integration automatically? Sphinx projects that are generated with a modern version of Sphinx use
which calls out to https://github.com/sphinx-doc/sphinx/blob/0bb43d6b99abd1c31885489765d4fe5469d56e21/sphinx/cmd/make_mode.py.
You could monkey-patch the
Make
object in that file to addmake livehtml
. The only thing is I'm not sure if the entry points mechanism that Sphinx extensions use make it possible. Alternately, perhaps Sphinx should be modified so that extensions can more easily add makefile integrations.