sphinx/doc/faq.rst

.. _faq:

Sphinx FAQ
==========

This is a list of Frequently Asked Questions about Sphinx.  Feel free to
suggest new entries!

How do I...
-----------

... create PDF files without LaTeX?
   You can use `rst2pdf <http://rst2pdf.googlecode.com>`_ version 0.12 or greater
   which comes with built-in Sphinx integration.  See the :ref:`builders`
   section for details.

... get section numbers?
   They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to
   the :dir:`toctree` directive where you want to start numbering.

... customize the look of the built HTML files?
   Use themes, see :doc:`theming`.

... add global substitutions or includes?
   Add them in the :confval:`rst_epilog` config value.

... write my own extension?
   See the :ref:`extension tutorial <exttut>`.

... convert from my existing docs using MoinMoin markup?
   The easiest way is to convert to xhtml, then convert `xhtml to reST`_.  You'll
   still need to mark up classes and such, but the headings and code examples
   come through cleanly.


Using Sphinx with...
--------------------

Epydoc
   There's a third-party extension providing an `api role`_ which refers to
   Epydoc's API docs for a given identifier.

Doxygen
   Michael Jones is developing a reST/Sphinx bridge to doxygen called `breathe
   <http://github.com/michaeljones/breathe/tree/master>`_.

SCons
   Glenn Hutchings has written a SCons build script to build Sphinx
   documentation; it is hosted here: http://bitbucket.org/zondo/sphinx-scons

github pages
   You can use `Michael Jones' sphinx-to-github tool
   <http://github.com/michaeljones/sphinx-to-github/tree/master>`_ to prepare
   Sphinx HTML output.


Epub
----

The EpubBuilder is currently in an experimental stage.
It has only been tested with the Sphinx documentation itself.
If you want to create epubs, here are some notes:

* Split the text into several files. The longer the individual HTML files
  are, the longer it takes the ebook reader to render them.
  In extreme cases, the rendering can take up to one minute.

* Try to minimize the markup. This also pays in rendering time.

* For some readers you can use embedded or external fonts
  using the CSS ``@font-face`` directive.
  This is *extremely* useful for code listings which are often cut
  at the right margin. The default Courier font (or variant) is quite
  wide and you can only display up to 60 characters on a line.
  If you replace it with a narrower font, you can get more characters
  on a line. You may even use
  `fontforge <http://fontforge.sourceforge.net/>`_
  and create narrow variants
  of some free font. In my case I get up to 70 characters on a line.

  You may have to experiment a little until you get reasonable results.

* Test the created epubs. You can use several alternatives.
  The ones I am aware of are
  Epubcheck
  (`http://code.google.com/p/epubcheck/
  <http://code.google.com/p/epubcheck/>`_),
  Calibre 
  (`http://calibre-ebook.com/ <http://calibre-ebook.com/>`_),
  FBreader (`http://www.fbreader.org/ <http://www.fbreader.org/>`_,
  although it does not render the CSS), and
  Bookworm (`http://bookworm.oreilly.com/ <http://bookworm.oreilly.com/>`_).
  For bookworm you can download the source from
  `http://code.google.com/p/threepress/ <http://code.google.com/p/threepress/>`_
  and run you own local server.


.. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
.. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py