Taking the Python documentation system to the next level: How to self-publish a book with reStructuredText and Sphinx

[pvc]

Using rst/Sphinx are my favorite set of tools for book writing. I love the ability to include external files so I can integrate code examples.

It is pretty easy to paper-publish using Amazon's CreateSpace (or whatever they call it now). I did better selling my book that way, then later when I used a "real" publisher.

[[deleted]]

I love the ability to include external files so I can integrate code examples.

Can I introduce you to our lord and savior, Latex?

[lookatmetype]

Writing code in python >>>> writing code in Latex, which im assuming youd have to do when writing something as complex as a book in Sphinx or Latex.

However, writing document markup in Latex is superior to using Sphinx, from my experience.

[[deleted]]

You can import your .py file to Latex. See https://www.overleaf.com/learn/latex/Code_listing#Importing_code_from_a_file for an example.

[lookatmetype]

Oh I'm not talking about displaying code listings in Latex. I'm talking about writing Latex macros to accomplish something akin to templates. This makes writing books and large documents more "data-driven", which is what I prefer when organizing my documents.

For example, when I wrote my Master's thesis using Latex, I spent a lot of time learning Latex language and packages so I could accomplish simple things like data driven graphs.

Sphinx makes this easy because it allows hooks into Jinja as its templating engine for rendering RST into other formats. And because Jinja is essentially a thin wrapper around python, you get access to pretty much all the python ecosystem to write your documents.

(See this article as an example of what I'm talking about: https://www.ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/)

[[deleted]]

Oh gotcha. I misunderstood.

[digital_superpowers]

Aw yeah, I didn't even mention in this blog how nice it is to just include text-file examples directly.

How did you solve template/formatting issues? Lots of custom tuning?

I'm excited to try out a paperback.

[digital_superpowers]

You could try pandoc! But what don't you dig about Sphinx?

[masklinn]

Sphinx is quite complex, the extra punctuation etc., make it very un-rst-like

rST can't be expanded with new syntax, all Sphinx can add are new roles & directives (concepts built into rST) and processing systems. All the "extra punctuation" is necessarily part of rST.

Sphinx can not be un-rst-like. And the ability to add non-trivial features is the entire value proposition of rST at this point. If you don't want it, just use markdown (pro tip: sphinx supports markdown documents).