Is Sphinx better than LaTex in writing manuals/books?

Question

Only a few people recommended to use Sphinx at the beginning of the year.

Sphinx has developed rather fast recently. I noted today that Sage has made a change from direct editing with LaTex to Sphinx. This is evident in William Stein's answer on 2nd April about Sage's tutorial

The tutorial is not a latex document anymore. It's an entirely different Sphinx document that can output pdf.

It suggests me that Sphinx may be at a level such that it is suitable for me.

Is Sphinx better than LaTex in writing manuals/books?

Answer 1

It's better for creating reference documentation, not for writing books.

Answer 2

We wrote a book with sphinx but we had to tweak the tex file produced with a Python script.

Take a look at this thread, in the book building tool section

Here a some changes we made to the original LaTeX file:

• documentclass = 'book'
• added frontmatter, mainmatter and backmatter
• added a new style to fncychap.sty
• two columns index instead of one columns
• some changes in the page header
• everything is black & white
  • links
  • titles
  • images (using imagemagick to convert the images in greyscale)
• tips and notes displayed in a nicer box with icon
• better float placement on pages to optimize the space used

We also made minor changes to book.cls and sphinx.sty

With all these tweaks, we are very happy with the result.

Answer 3

Is Word a better document production tool?

LaTeX (and TeX) have been around for longer than most of us realise that there were programmes to do that sort of thing and that we were interested in them. LaTeX is almost certainly better than Sphinx (or Word).

1. Is it better for you? Maybe.

2. Is it better for me? Unlikely.

3. Is it better for the average person? Define 'average' then go to point 1.

Answer 4

Well, there is at least one book printed using sphinx and rst2pdf (http://rst2pdf.googlecode.com) see here: http://lateral.netmanagers.com.ar/weblog/2009/09/07.html#BB822 (No LaTeX used at all)

Some sample documents generated via sphinx and rst2pdf here:

http://freedrive.com/folder/236385

And here:

http://freedrive.com/folder/236380

Specially check the python library reference and the django book.

This is output from the development branch and has bugs (for example, the TOC is often on the wrong side of the page) which are being fixed.

Answer 5

I prefer Sphinx to Latex for writing manuals for two reasons:

1. You can build nice HTML, PDF, htmlhelp and qthelp versions of the manual with minimal effort.
2. reST syntax is faster to write and I find easier to remember (it's more simple)

A book, however, might be a different story. If I wanted to write a book that has only a printed and a pdf version and contains equations and citations I would go with Latex, because I think it is much more mature than reST and I find it easy to customize.

Btw. I have much more experience in using Latex.