67
Sphinx Documentation, Release 1.4.1
anarrower font, you can get more characters on a line. You may even useFontForge
190
and create
narrow variants ofsome free font. In mycase I getup 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 areEpubcheck
191
,
Calibre
192
,FBreader
193
(although it does not render the CSS), andBookworm
194
. For bookworm you
can download the source fromhttps://code.google.com/archive/p/threepress and run your own
local server.
• Large floating divs are not displayed properly.
If they cover more than one page, the
div is only shown on the first page. In that case you can copy the epub.css from the
sphinx/themes/epub/static/ directory to your local _static/ directory and remove the float
settings.
• Files that are inserted outsideof the toctree directive must be manually included. This sometimes
appliestoappendixes,e.g. theglossaryortheindices. You can add themwiththeepub_post_files
option.
• Thehandlingofthe epubcoverpagediffers from thereStructuredTextprocedure which automatically
resolves image paths and puts the images into the _images directory. For the epub cover page put
the imagein thehtml_static_path directoryand reference itwith itsfullpath in theepub_cover
config option.
17.4 Texinfo info
There are two main programs for reading Info files, info and GNU Emacs. The info program has less
features butis availablein most Unix environments and can bequickly accessed from theterminal. Emacs
provides betterfontand color display and supports extensivecustomization (ofcourse).
17.4.1 Displaying Links
One noticeable problem you may encounter with the generated Info files is how references are displayed.
If you read thesource of an Info file, a referencetothis section would looklike:
*
note Displaying Links: target-id
In the stand-alone reader, info, references are displayed just as they appear in the source. Emacs, on the
other-hand, will by default replace
*
note: with see and hidethe target-id. Forexample:
Displaying Links
The exact behavior of how
Emacs displays references is dependent on the variable
Info-hide-note-references. If set to the value of hide, Emacs will hide both the
*
note:
part and thetarget-id. This is generally the best way to view Sphinx-based documents since they often
make frequent use of links and do not take this limitation into account. However, changing this variable
affects how all Infodocumentsare displayed and mostdue take this behaviorinto account.
If you want Emacs to display Info files produced by Sphinx using the value hide for
Info-hide-note-references and the default value for all other Info files, try adding the following
Emacs Lisp codetoyourstart-up file,~/.emacs.d/init.el.
190
http://fontforge.github.io/
191
https://code.google.com/archive/p/epubcheck
192
http://calibre-ebook.com/
193
https://fbreader.org/
194
http://www.oreilly.com/bookworm/index.html
17.4. Texinfo info
193