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?

share|improve this question

closed as not constructive by Paŭlo Ebermann, templatetypedef, Merlyn Morgan-Graham, abatishchev, Graviton Sep 21 '11 at 7:20

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance. If this question can be reworded to fit the rules in the help center, please edit the question.

1  
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 8:45
up vote 13 down vote accepted

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.

share|improve this answer
    
@Oli: Which one is in your opinion better for writing books, Sphinx or directly by LaTex? – Léo Léopold Hertz 준영 Apr 8 '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 8 '09 at 11:28
    
@Oli: Can I see those files or are they private? – Léo Léopold Hertz 준영 Apr 8 '09 at 11:32
4  
It's open. Everything is on Launchpad (launchpad.net/openobject-doc). You just need to install Bazaar (bzr) and use it to get the branch. For example: bzr branch bazaar.launchpad.net/%7Eopenerp-community/openobject-doc/… openobject_doc – Oli Apr 9 '09 at 7:10
    
@Oli the linked thread has been removed... – Saullo Castro Mar 14 '14 at 7:24

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.

share|improve this answer
    
link to netmanagers.com is dead – Macke Jul 4 '12 at 10:51
    
    
Thanks. Note that you can edit your post... – Macke Jul 5 '12 at 8:02

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.

share|improve this answer

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

share|improve this answer
    
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 7 '09 at 14:24
    
¿ToDo? Don't know that one. – vartec Apr 8 '09 at 7:59
1  
@vartex: You can find it by the word devtodo by apt-get. – Léo Léopold Hertz 준영 Apr 8 '09 at 11:21
1  
@Masi: found it. Seems very straight forward. I think using Sphinx for that would be an overkill. – vartec Apr 8 '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 8:42

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.

share|improve this answer

Not the answer you're looking for? Browse other questions tagged or ask your own question.