mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
100 lines
3.4 KiB
ReStructuredText
100 lines
3.4 KiB
ReStructuredText
.. _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
|