Automatic Makefile integration

[asmeurer]

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

%: Makefile
	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

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 add make 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.

[pradyunsg]

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.

[asmeurer]

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.

[asmeurer]

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.

[pradyunsg]

monkeypatch Sphinx

Uhhhhh... I'm not a fan of monkeypatching to provide functionality as part of an addon/extension.

[asmeurer]

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.

[pradyunsg]

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: sphinx-doc/sphinx#5618

[asmeurer]

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 #79 (comment)?