Add documentation for Texinfo builder

doc/Makefile

@@ -29,6 +29,8 @@ help:
 	@echo "  epub       to make an epub file"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  latexpdf   to make LaTeX files and run pdflatex"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
 	@echo "  gettext    to make PO message catalogs"
 	@echo "  changes    to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck  to check all external links for integrity"
@@ -131,3 +133,16 @@ linkcheck:
 
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) _build/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in _build/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) _build/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C _build/texinfo info
+	@echo "makeinfo finished; the Info files are in _build/texinfo."

doc/builders.rst

@@ -144,6 +144,27 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf
 
    .. versionadded:: 1.0
 
+
+.. module:: sphinx.builders.texinfo
+.. class:: TexinfoBuilder
+
+   This builder produces Texinfo files that can be processed into Info
+   files by the :program:`makeinfo` program.  You have to specify which
+   documents are to be included in which Texinfo files via the
+   :confval:`texinfo_documents` configuration value.
+
+   The Info format is the basis of the on-line help system used by GNU
+   Emacs and the terminal-based program :program:`info`.  See
+   :ref:`texinfo-faq` for more details.  The Texinfo format is the
+   official documentation system used by the GNU project.  More
+   information on Texinfo can be found at
+   `<http://www.gnu.org/software/texinfo/>`_.
+
+   Its name is ``texinfo``.
+
+   .. versionadded:: 1.1
+
+
 .. currentmodule:: sphinx.builders.html
 .. class:: SerializingHTMLBuilder
 

doc/conf.py

@@ -64,6 +64,12 @@ man_pages = [
      'template generator', '', 1),
 ]
 
+texinfo_documents = [
+    ('contents', 'sphinx', 'Sphinx Documentation', 'Georg Brandl',
+     'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools',
+     1),
+]
+
 # We're not using intersphinx right now, but if we did, this would be part of
 # the mapping:
 intersphinx_mapping = {'python': ('http://docs.python.org/dev', None)}

doc/config.rst

@@ -1040,6 +1040,79 @@ These options influence manual page output.
    .. versionadded:: 1.0
 
 
+.. _texinfo-options:
+
+Options for Texinfo output
+--------------------------
+
+These options influence Texinfo output.
+
+.. confval:: texinfo_documents
+
+   This value determines how to group the document tree into Texinfo
+   source files.  It must be a list of tuples ``(startdocname,
+   targetname, title, author, dir_entry, description, category,
+   toctree_only)``, where the items are:
+
+   * *startdocname*: document name that is the "root" of the Texinfo
+     file.  All documents referenced by it in TOC trees will be
+     included in the Texinfo file too.  (If you want only one Texinfo
+     file, use your :confval:`master_doc` here.)
+   * *targetname*: file name (no extension) of the Texinfo file in
+     the output directory.
+   * *title*: Texinfo document title.  Can be empty to use the title of the
+     *startdoc*.
+   * *author*: Author for the Texinfo document.  Use ``\and`` to
+     separate multiple authors, as in: ``'John \and Sarah'``.
+   * *dir_entry*: The name that will appear in the top-level ``DIR``
+     menu file.
+   * *description*: Descriptive text to appear in the top-level
+     ``DIR`` menu file.
+   * *category*: Specifies the section which this entry will appear in
+     the top-level ``DIR`` menu file.
+   * *toctree_only*: Must be ``True`` or ``False``.  If ``True``, the
+     *startdoc* document itself is not included in the output, only
+     the documents referenced by it via TOC trees.  With this option,
+     you can put extra stuff in the master document that shows up in
+     the HTML, but not the Texinfo output.
+
+   .. versionadded:: 1.1
+
+
+.. confval:: texinfo_appendices
+
+   A list of document names to append as an appendix to all manuals.
+
+   .. versionadded:: 1.1
+
+
+.. confval:: texinfo_elements
+
+   A dictionary that contains Texinfo snippets that override those Sphinx usually
+   puts into the generated ``.texi`` files.
+
+   * Keys that you may want to override include:
+
+     ``'paragraphindent'``
+       Number of spaces to indent the first line of each paragraph,
+       default ``2``.  Specify ``0`` for no indentation.
+
+     ``'exampleindent'``
+       Number of spaces to indent the lines for examples or literal blocks, default ``4``.
+       Specify ``0`` for no indentation.
+
+     ``'preamble'``
+        Text inserted as is near the beginning of the file.
+
+   * Keys that are set by other options and therefore should not be overridden are:
+
+     ``'filename'``
+     ``'title'``
+     ``'direntry'``
+
+   .. versionadded:: 1.1
+
+
 .. rubric:: Footnotes
 
 .. [1] A note on available globbing syntax: you can use the standard shell

doc/faq.rst

@@ -148,3 +148,112 @@ some notes:
 .. _Calibre: http://calibre-ebook.com/
 .. _FBreader: http://www.fbreader.org/
 .. _Bookworm: http://bookworm.oreilly.com/
+
+
+.. _texinfo-faq:
+
+Texinfo info
+------------
+
+The Texinfo builder is currently in an experimental stage but has
+successfully been used to build the documentation for both Sphinx and
+Python.  The intended use of this builder is to generate Texinfo that
+is then processed into Info files.
+
+There are two main programs for reading Info files, ``info`` and GNU
+Emacs.  The ``info`` program has less features but is available in
+most Unix environments and can be quickly accessed from the terminal.
+Emacs provides better font and color display and supports extensive
+customization (of course).
+
+.. _texinfo-links:
+
+Displaying Links
+~~~~~~~~~~~~~~~~
+
+One noticeable problem you may encounter with the generated Info files
+is how references are displayed.  If you read the source of an Info
+file, a reference to this section would look like::
+
+    * 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 hide the ``target-id``.  For
+example:
+
+    :ref:`texinfo-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 the
+``target-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 Info documents are displayed and most due take this behavior
+into 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 code to
+your start-up file, ``~/.emacs.d/init.el``.
+
+::
+
+    (defadvice info-insert-file-contents (after
+                                          sphinx-info-insert-file-contents
+                                          activate)
+      "Hack to make `Info-hide-note-references' buffer-local and
+    automatically set to `hide' iff it can be determined that this file
+    was created from a Texinfo file generated by Sphinx."
+      (set (make-local-variable 'Info-hide-note-references)
+           (default-value 'Info-hide-note-references))
+      (save-excursion
+        (save-restriction
+          (widen) (goto-char (point-min))
+          (when (re-search-forward
+                 "^Generated by Sphinx"
+                 (save-excursion (search-forward "" nil t)) t)
+            (set (make-local-variable 'Info-hide-note-references)
+                 'hide)))))
+
+
+Notes
+~~~~~
+
+The following notes may be helpful if you want to create Texinfo
+files:
+
+- Each section corresponds to a different ``node`` in the Info file.
+
+- Some characters cannot be properly escaped in menu entries and
+  xrefs.  The following characters are replaced by spaces in these
+  contexts: ``@``, ``{``, ``}``, ``.``, ``,``, and ``:``.
+
+- In the HTML and Tex output, the word ``see`` is automatically
+  inserted before all xrefs.
+
+- Links to external Info files can be created using the somewhat
+  official URI scheme ``info``.  For example::
+
+      info:Texinfo#makeinfo_options
+
+  which produces:
+
+      info:Texinfo#makeinfo_options
+
+- Inline markup appears as follows in Info:
+
+  * strong -- \*strong\*
+  * emphasis -- _emphasis_
+  * literal -- \`literal'
+
+  It is possible to change this behavior using the Texinfo command
+  ``@definfoenclose``.  For example, to make inline markup more
+  closely resemble reST, add the following to your :file:`conf.py`::
+
+      texinfo_elements = {'preamble': """\
+      @definfoenclose strong,**,**
+      @definfoenclose emph,*,*
+      @definfoenclose code,`@w{}`,`@w{}`
+      """}

doc/invocation.rst

@@ -40,6 +40,10 @@ The :program:`sphinx-build` script has several options:
    **man**
       Build manual pages in groff format for UNIX systems.
 
+   **texinfo**
+      Build Texinfo files that can be processed into Info files using
+      :program:`makeinfo`.
+
    **text**
       Build plain text files.