What's your workflow?

[Bram Geron]

Hi all,

I'm using Sphinx in multiple work-related projects, and I've kind of automated it, but I would love to hear: How do you edit a Sphinx project? How do you type, save, preview, and publish?

I'm doing a PhD on the theoretical aspect of programming languages. I write mainly English and mathematics¹, and not so much in actual programming language. Everyone everywhere seems to use LaTeX even though it's crappy in many many aspects², and I'm sure many of you agree with me that Sphinx is quite a nice way of writing documents. So I'm using that for now.

I write the actual letters using Sublime Text, quite a powerful programmer's text editor. On the side, I have Chromium open. When I press Ctrl+B in Sublime Text, it invokes make, which builds HTML with sphinx, and refreshes the page in Chromium.

The way this works is as follows. (Skip three paragraphs ahead if you're not interested.) In the background, I have two processes. One is a very simple web server that serves ~/livereload on port 12345 of 127.0.0.1, so that only my laptop can access that web server. In fact, I don't look at 127.0.0.1:12345 in Chromium, I look at live.localhos.tk:12345, which is exactly the same thing but it autocompletes nicely in Chromium when I start typing "live". Also, when I'm browsing hostnames, all my Chromium plugins keep working; not so when I'm browsing IP addresses. I registered localhos.tk myself, and intend to point all its subdomains to 127.0.0.1 forever.

In ~/livereload, I have symlinks to each of the _build/html directories of my recent projects. Furthermore, I'm running fb-flo, which listens on a different port, and can broadcast a "reload" signal from that port when a certain file is touched. I touch this file at the end of my `make html`. Then in Chromium, I have the fb-flo extension, so that when I open Developer Tools, the extension will connect to the fb-flo process and reload the page when that file is touched when I hit Ctrl+B from my editor. 

Sometimes, I want to publish updates to online presences of projects. In that case, I'll connect to my VPS using sshfs, and I have a command in my Makefile that builds HTML, then recursively copies over the _build/html directory to remote.

As you can see, this is all a bit involved and ugly, both because I need to have additional things open for it to work, and because I can't easily sphinx-quickstart a new project and preview that. Surely there must be a simpler solution. I'm looking for ideas; please let me know how you work!

Cheers, Bram

¹ I have an outdated draft at http://bram.xyz/output/leah-draft/leah.html , if you're curious for the type of thing I write.

² I'll spare you my powerflame for the moment. o:)