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?

Thank you for raising this question. Imho I think Sphinx is one of the rare candidates to replace LaTex at least in some of its use cases. — jsalonen, Mar 18 '11 at 08:45

score 13 · Accepted Answer · answered Apr 08 '09 at 11:00

13

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.

answered Apr 08 '09 at 11:00

Oli

15,345
8
30
36

@Oli: Which one is in your opinion better for writing books, Sphinx or directly by LaTex? – Léo Léopold Hertz 준영 Apr 08 '09 at 11:24
3

It's easier for us with sphinx because we just wrote restructured text. Our book is only text and images. You can also easily create Sphinx directives and tags if you need it. – Oli Apr 08 '09 at 11:28
@Oli: Can I see those files or are they private? – Léo Léopold Hertz 준영 Apr 08 '09 at 11:32
4

It's open. Everything is on Launchpad (https://launchpad.net/openobject-doc). You just need to install Bazaar (bzr) and use it to get the branch. For example: bzr branch http://bazaar.launchpad.net/%7Eopenerp-community/openobject-doc/features/ openobject_doc – Oli Apr 09 '09 at 07:10
@Oli the linked thread has been removed... – Saullo G. P. Castro Mar 14 '14 at 07:24

score 4 · Answer 2 · edited Nov 14 '14 at 14:13

4

Well, there is at least one book printed using sphinx and rst2pdf

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.

edited Nov 14 '14 at 14:13

Ibn Saeed

3,171
11
50
59

answered Sep 10 '09 at 16:42

Roberto Alsina

782
4
8

link to netmanagers.com is dead – Macke Jul 04 '12 at 10:51
http://lateral.netmanagers.com.ar/weblog/posts/BB822.html – Roberto Alsina Jul 04 '12 at 16:08
Thanks. Note that you can edit your post... – Macke Jul 05 '12 at 08:02

score 3 · Answer 3 · answered Mar 12 '10 at 08:05

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

You can build nice HTML, PDF, htmlhelp and qthelp versions of the manual with minimal effort.
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.

score 1 · Answer 4 · answered Apr 07 '09 at 13:52

1

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

answered Apr 07 '09 at 13:52

vartec

131,205
36
218
244

Your answer raised another question. I currently provide reference documention for myself by the Unix application ToDo. Is Sphinx better than Todo in the purpose? – Léo Léopold Hertz 준영 Apr 07 '09 at 14:24
1

@vartex: You can find it by the word devtodo by apt-get. – Léo Léopold Hertz 준영 Apr 08 '09 at 11:21
1

@Masi: found it. Seems very straight forward. I think using Sphinx for that would be an overkill. – vartec Apr 08 '09 at 11:46
I completely agree with you: it is better for creating reference documentation than for writing books. However, that was not the question here! – jsalonen Mar 18 '11 at 08:42
@jsalonen: than again, that's not what my answer is. My answer is it that it's better for documentation, not better for books. – vartec Mar 18 '11 at 16:58

score 1 · Answer 5 · answered Apr 08 '09 at 11:24

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).

Is it better for you? Maybe.
Is it better for me? Unlikely.
Is it better for the average person? Define 'average' then go to point 1.

Is Sphinx better than LaTex in writing manuals/books?

5 Answers5