Supporting PDF builds

[mgielda]

I was wondering if it would be possible to use sphinx-autobuild also for PDF output. Since viewers like evince support reloading documents on change, it is actually just as convenient as previewing in the browser, and much of the documentation we generate is intended for PDF usage.

Currently I am using a dirty script which reruns make latexpdf every time files change, but it would be interesting to move to sphinx-autobuild if possible.

The problem with using sphinx-autobuild easily is that it replaces sphinx-build, while in reality make latexpdf is two actions (for me actually three actions, as I also use texfot to filter tex output, but that's just an extension of the same problem) - sphinx-build and make all-pdf.

Would anyone have any ideas how to do that using sphinx-autobuild? This could be a useful feature in general.

[mgeier]

I don't know if it is feasible to include this directly into sphinx-autobuild.

However, I'm using sphinx-autobuild for updating the LaTeX output and at the same time latexmk in "preview continuous" mode. I have to start two processes (in two terminals), but apart from that, the update of the PDF happens automatically.

I don't know about your additional build steps, but latexmk is quite nicely configurable, so you can probably incorporate your additional steps there.

Additional information:
http://nbsphinx.readthedocs.io/en/latest/usage.html#Watching-for-Changes-with-sphinx-autobuild
http://mg.readthedocs.io/latexmk.html

[mgielda]

Thanks for the info, latexmk sounds like a very good idea. Well then, my question would be - would it be possible to have a flag not to turn on the built-in web server? If you just want to build LaTeX, that's kind of unnecessary.

[pradyunsg]

AFAIK, this should be possible today with -b latex. Am I missing something here?

[mgielda]

Hi @pradyunsg thanks for the question. I meant latexpdf, which is not available as an option?

Since then I moved away from using sphinx-autobuild; generally speaking I wanted to get a single command in one terminal (some of my users are not advanced in Sphinx/bash) and no server to be launched (not needed for a PDF). Seems like this is not something that's planned to be implemented, which is OK :)

[pradyunsg]

I meant latexpdf, which is not available as an option?

It'll be -b latexpdf then. -b specifies the builder for sphinx, so if you can do it in a makefile, you can do it with sphinx-autobuild.

no server

I personally don't see why having a redundant server that doesn't affect anything about the builds is an issue TBH. Worst case, it's eating an I/O port since the server basically sits idle unless there's a network request.

Given that you're on a different workflow now, I think it's perfectly fine to defer this until someone else asks for behavior like this. :)

[mgielda]

[mgielda@thalxps docs]$ sphinx-autobuild -b latexpdf source/ build/pdf
+--------- manually triggered build ---------------------------------------------
| Running Sphinx v3.2.1

Sphinx error:
Builder name latexpdf not registered or available through entry point
+--------------------------------------------------------------------------------

That's what I meant. Perhaps I just have a wrong version or something.

[Dzordzu]

Actually it's 'cause -b does not use Sphinx make_mode module. The proper way, would be to allow passing directly -M to the sphinx-build, and then specify

sphinx-autobuild -M latexpdf source build

[holmboe]

Actually it's 'cause -b does not use Sphinx make_mode module. The proper way, would be to allow passing directly -M to the sphinx-build, and then specify

sphinx-autobuild -M latexpdf source build

It seems this is not a valid solution as -M is not a supported argument to sphinx-autobuild:

$ sphinx-autobuild -M latexpdf "." "_build"
usage: sphinx-autobuild [-h] [--port PORT] [--host HOST] [--re-ignore RE_IGNORE] [--ignore IGNORE] [--no-initial] [--open-browser]
                        [--delay DELAY] [--watch DIR] [--pre-build COMMAND] [--version]
                        sourcedir outdir [filenames ...]
sphinx-autobuild: error: unrecognized arguments: -M

[deliciouslytyped]

xref
#151
#64

[deliciouslytyped]

@AA-Turner is this also solved now by your recent patch? (I didn't check).