Is anyone using Scrivener with Sphinx?
If so, how are you entering and saving your pages to best be used by Sphinx for its compiling? I am interested mostly in Sphinx’s PDF generation.
I had a look at Sphinx (or reStructuredText in general) about a year ago as someone was asking about using that with Scrivener. The main issue that I ran into with it, and Scrivener in particular, is its heading format. Generating the proper number of symbols at each level under each title is something that Scrivener wouldn’t be able to do on its own. You could get the right symbol at each level using Section Layouts, sure, but having the same amount of them as the length of the title itself would require additional scripting.
The one thing that could save the idea is that according to the specifications you can “overshoot” as you only need at least as many symbols as the title length. It would result in an uglier document in my opinion, but I suppose that is subjective. Some might prefer an even 75 character width (or whatever) to the heading breaks anyway.
Otherwise, the rest of the spec looked like it would work well with Scrivener’s styles and section layouts features, as well as the Markup pane available to TXT compiling. I never went so far as to make a compile format though. If you come up with something, feel free to post it to the #scrivener:multimarkdown-latex section!
I asked because I used Sphinx for years before discovering Scrivener. I still use Sphinx for tech manuals (I keep the .rst files on GitHub that web-hook their way into my readthedocs sites for .pdf downloading).
I accidentally learned of the “overshoot” from editing titles and forgetting to edit the symbols underneath them.
Not knowing all of the particulars involved, I do think Sphinx is something that, like Pandoc, can be entirely automated via the command-line, and given that one could pretty much automate the entire build workflow using Scrivener’s Processing compile format pane.
So in conjunction with being able to create a compile Format that aids in the construction/conversion of text to reStructureText format, and a post-compile processing script that turns that source into usable documentation with a build configuration, I think it could make for a nice platform.
It is definitely worth investigating if you already have a lot of material in that system and a desire to continue using it. When I looked at it, it was partially out of curiosity as stated, but I was also at the time looking at switching out of MMD for our documentation production as its customisation capabilities have fallen off over the years. It works great if the output is exactly what you want, but if it isn’t the only options are to fork the source code or mess with string manipulation on the product. I ultimately went with the later for the sake of expediency, but I think in the future I might look to other alternatives. Pandoc is a big one, as it would mean a minimal transition on the source side being another Markdown-oriented tool. But Sphinx does have some compelling arguments for it in that it is dedicated toward documentation rather than being general purpose.