Few cleanups after texinfo builder merge (#529). Add CHANGES and AUTHORS entries. To do: add node handlers for all extension nodes so that the test documents can be handled without warnings.

AUTHORS

@@ -30,6 +30,7 @@ Other contributors, listed alphabetically, are:
 * Antonio Valentino -- qthelp builder
 * Pauli Virtanen -- autodoc improvements, autosummary extension
 * Stefan van der Walt -- autosummary extension
+* John Waltman -- Texinfo builder
 * Barry Warsaw -- setup command improvements
 * Sebastian Wiesner -- image handling, distutils support
 

CHANGES

@@ -8,6 +8,8 @@ Release 1.1 (in development)
 
 * Added the ``websupport`` library.
 
+* Added a Texinfo builder.
+
 * #460: Allow limiting the depth of section numbers for HTML.
 
 * #138: Add an ``index`` role, to make inline index entries.

doc/builders.rst

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

doc/config.rst

@@ -1031,9 +1031,9 @@ These options influence manual page output.
      well as the name of the manual page (in the NAME section).
    * *description*: description of the manual page.  This is used in the NAME
      section.
-   * *authors*: A list of strings with authors, or a single string.  Can be
+   * *authors*: A list of strings with authors, or a single string.  Can be an
-     an empty string or list if you do not want to automatically generate
+     empty string or list if you do not want to automatically generate an
-     an AUTHORS section in the manual page.
+     AUTHORS section in the manual page.
    * *section*: The manual page section.  Used for the output file name as well
      as in the manual page header.
 
@@ -1049,32 +1049,31 @@ These options influence Texinfo output.
 
 .. confval:: texinfo_documents
 
-   This value determines how to group the document tree into Texinfo
+   This value determines how to group the document tree into Texinfo source
-   source files.  It must be a list of tuples ``(startdocname,
+   files.  It must be a list of tuples ``(startdocname, targetname, title,
-   targetname, title, author, dir_entry, description, category,
+   author, dir_entry, description, category, toctree_only)``, where the items
-   toctree_only)``, where the items are:
+   are:
 
-   * *startdocname*: document name that is the "root" of the Texinfo
+   * *startdocname*: document name that is the "root" of the Texinfo file.  All
-     file.  All documents referenced by it in TOC trees will be
+     documents referenced by it in TOC trees will be included in the Texinfo
-     included in the Texinfo file too.  (If you want only one Texinfo
+     file too.  (If you want only one Texinfo file, use your
-     file, use your :confval:`master_doc` here.)
+     :confval:`master_doc` here.)
-   * *targetname*: file name (no extension) of the Texinfo file in
+   * *targetname*: file name (no extension) of the Texinfo file in the output
-     the output directory.
+     directory.
    * *title*: Texinfo document title.  Can be empty to use the title of the
      *startdoc*.
-   * *author*: Author for the Texinfo document.  Use ``\and`` to
+   * *author*: Author for the Texinfo document.  Use ``\and`` to separate
-     separate multiple authors, as in: ``'John \and Sarah'``.
+     multiple authors, as in: ``'John \and Sarah'``.
-   * *dir_entry*: The name that will appear in the top-level ``DIR``
+   * *dir_entry*: The name that will appear in the top-level ``DIR`` menu file.
-     menu file.
+   * *description*: Descriptive text to appear in the top-level ``DIR`` menu
-   * *description*: Descriptive text to appear in the top-level
+     file.
-     ``DIR`` menu file.
+   * *category*: Specifies the section which this entry will appear in the
-   * *category*: Specifies the section which this entry will appear in
+     top-level ``DIR`` menu file.
-     the top-level ``DIR`` menu file.
+   * *toctree_only*: Must be ``True`` or ``False``.  If ``True``, the *startdoc*
-   * *toctree_only*: Must be ``True`` or ``False``.  If ``True``, the
+     document itself is not included in the output, only the documents
-     *startdoc* document itself is not included in the output, only
+     referenced by it via TOC trees.  With this option, you can put extra stuff
-     the documents referenced by it via TOC trees.  With this option,
+     in the master document that shows up in the HTML, but not the Texinfo
-     you can put extra stuff in the master document that shows up in
+     output.
-     the HTML, but not the Texinfo output.
 
    .. versionadded:: 1.1
 
@@ -1088,23 +1087,24 @@ These options influence Texinfo output.
 
 .. confval:: texinfo_elements
 
-   A dictionary that contains Texinfo snippets that override those Sphinx usually
+   A dictionary that contains Texinfo snippets that override those Sphinx
-   puts into the generated ``.texi`` files.
+   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,
+        Number of spaces to indent the first line of each paragraph, default
-       default ``2``.  Specify ``0`` for no indentation.
+        ``2``.  Specify ``0`` for no indentation.
 
      ``'exampleindent'``
-       Number of spaces to indent the lines for examples or literal blocks, default ``4``.
+        Number of spaces to indent the lines for examples or literal blocks,
-       Specify ``0`` for no indentation.
+        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:
+   * Keys that are set by other options and therefore should not be overridden
+     are:
 
      ``'filename'``
      ``'title'``

doc/faq.rst

@@ -155,92 +155,89 @@ some notes:
 Texinfo info
 ------------
 
-The Texinfo builder is currently in an experimental stage but has
+The Texinfo builder is currently in an experimental stage but has successfully
-successfully been used to build the documentation for both Sphinx and
+been used to build the documentation for both Sphinx and Python.  The intended
-Python.  The intended use of this builder is to generate Texinfo that
+use of this builder is to generate Texinfo that is then processed into Info
-is then processed into Info files.
+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).
 
-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
+One noticeable problem you may encounter with the generated Info files is how
-is how references are displayed.  If you read the source of an Info
+references are displayed.  If you read the source of an Info file, a reference
-file, a reference to this section would look like::
+to this section would look like::
 
     * note Displaying Links: target-id
 
-In the stand-alone reader, ``info``, references are displayed just as
+In the stand-alone reader, ``info``, references are displayed just as they
-they appear in the source.  Emacs, on the other-hand, will by default
+appear in the source.  Emacs, on the other-hand, will by default replace
-replace ``\*note:`` with ``see`` and hide the ``target-id``.  For
+``\*note:`` with ``see`` and hide the ``target-id``.  For example:
-example:
 
     :ref:`texinfo-links`
 
-The exact behavior of how Emacs displays references is dependent on
+The exact behavior of how Emacs displays references is dependent on the variable
-the variable ``Info-hide-note-references``.  If set to the value of
+``Info-hide-note-references``.  If set to the value of ``hide``, Emacs will hide
-``hide``, Emacs will hide both the ``\*note:`` part and the
+both the ``\*note:`` part and the ``target-id``.  This is generally the best way
-``target-id``.  This is generally the best way to view Sphinx-based
+to view Sphinx-based documents since they often make frequent use of links and
-documents since they often make frequent use of links and do not take
+do not take this limitation into account.  However, changing this variable
-this limitation into account.  However, changing this variable affects
+affects how all Info documents are displayed and most due take this behavior
-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
+If you want Emacs to display Info files produced by Sphinx using the value
-value ``hide`` for ``Info-hide-note-references`` and the default value
+``hide`` for ``Info-hide-note-references`` and the default value for all other
-for all other Info files, try adding the following Emacs Lisp code to
+Info files, try adding the following Emacs Lisp code to your start-up file,
-your start-up file, ``~/.emacs.d/init.el``.
+``~/.emacs.d/init.el``.
 
 ::
 
-    (defadvice info-insert-file-contents (after
+   (defadvice info-insert-file-contents (after
-                                          sphinx-info-insert-file-contents
+                                         sphinx-info-insert-file-contents
-                                          activate)
+                                         activate)
-      "Hack to make `Info-hide-note-references' buffer-local and
+     "Hack to make `Info-hide-note-references' buffer-local and
-    automatically set to `hide' iff it can be determined that this file
+   automatically set to `hide' iff it can be determined that this file
-    was created from a Texinfo file generated by Docutils or Sphinx."
+   was created from a Texinfo file generated by Docutils or Sphinx."
-      (set (make-local-variable 'Info-hide-note-references)
+     (set (make-local-variable 'Info-hide-note-references)
-           (default-value 'Info-hide-note-references))
+          (default-value 'Info-hide-note-references))
-      (save-excursion
+     (save-excursion
-        (save-restriction
+       (save-restriction
-          (widen) (goto-char (point-min))
+         (widen) (goto-char (point-min))
-          (when (re-search-forward
+         (when (re-search-forward
-                 "^Generated by \\(Sphinx\\|Docutils\\)"
+                "^Generated by \\(Sphinx\\|Docutils\\)"
-                 (save-excursion (search-forward "" nil t)) t)
+                (save-excursion (search-forward "" nil t)) t)
-            (set (make-local-variable 'Info-hide-note-references)
+           (set (make-local-variable 'Info-hide-note-references)
-                 'hide)))))
+                'hide)))))
 
 
 Notes
 ~~~~~
 
-The following notes may be helpful if you want to create Texinfo
+The following notes may be helpful if you want to create Texinfo files:
-files:
 
 - Each section corresponds to a different ``node`` in the Info file.
 
-- Some characters cannot be properly escaped in menu entries and
+- Some characters cannot be properly escaped in menu entries and xrefs.  The
-  xrefs.  The following characters are replaced by spaces in these
+  following characters are replaced by spaces in these contexts: ``@``, ``{``,
-  contexts: ``@``, ``{``, ``}``, ``.``, ``,``, and ``:``.
+  ``}``, ``.``, ``,``, and ``:``.
 
-- In the HTML and Tex output, the word ``see`` is automatically
+- In the HTML and Tex output, the word ``see`` is automatically inserted before
-  inserted before all xrefs.
+  all xrefs.
 
-- Links to external Info files can be created using the somewhat
+- Links to external Info files can be created using the somewhat official URI
-  official URI scheme ``info``.  For example::
+  scheme ``info``.  For example::
 
-      info:Texinfo#makeinfo_options
+     info:Texinfo#makeinfo_options
 
   which produces:
 
-      info:Texinfo#makeinfo_options
+     info:Texinfo#makeinfo_options
 
 - Inline markup appears as follows in Info:
 
@@ -249,11 +246,11 @@ files:
   * literal -- \`literal'
 
   It is possible to change this behavior using the Texinfo command
-  ``@definfoenclose``.  For example, to make inline markup more
+  ``@definfoenclose``.  For example, to make inline markup more closely resemble
-  closely resemble reST, add the following to your :file:`conf.py`::
+  reST, add the following to your :file:`conf.py`::
 
-      texinfo_elements = {'preamble': """\
+     texinfo_elements = {'preamble': """\
-      @definfoenclose strong,**,**
+     @definfoenclose strong,**,**
-      @definfoenclose emph,*,*
+     @definfoenclose emph,*,*
-      @definfoenclose code,`@w{}`,`@w{}`
+     @definfoenclose code,`@w{}`,`@w{}`
-      """}
+     """}

sphinx/builders/texinfo.py

@@ -9,7 +9,6 @@
     :license: BSD, see LICENSE for details.
 """
 
-import os
 from os import path
 
 from docutils import nodes
@@ -17,12 +16,12 @@ from docutils.io import FileOutput
 from docutils.utils import new_document
 from docutils.frontend import OptionParser
 
-from sphinx import package_dir, addnodes
+from sphinx import addnodes
 from sphinx.locale import _
 from sphinx.builders import Builder
 from sphinx.environment import NoUri
 from sphinx.util.nodes import inline_all_toctrees
-from sphinx.util.osutil import SEP, copyfile
+from sphinx.util.osutil import SEP
 from sphinx.util.console import bold, darkgreen
 from sphinx.writers.texinfo import TexinfoWriter
 
@@ -49,13 +48,13 @@ pdf: $(addsuffix .pdf,$(ALLDOCS))
 install-info: info
 \tfor f in *.info; do \\
 \t  cp -t $(infodir) "$$f" && \\
-\t  $(INSTALL_INFO) --info-dir=$(infodir) "$$f" ;\\
+\t  $(INSTALL_INFO) --info-dir=$(infodir) "$$f" ; \\
 \tdone
 
 uninstall-info: info
 \tfor f in *.info; do \\
-\t  rm -f "$(infodir)/$$f"  ;\\
+\t  rm -f "$(infodir)/$$f"  ; \\
-\t  $(INSTALL_INFO) --delete --info-dir=$(infodir) "$$f" ;\\
+\t  $(INSTALL_INFO) --delete --info-dir=$(infodir) "$$f" ; \\
 \tdone
 
 %.info: %.texi
@@ -83,7 +82,7 @@ clean:
 
 class TexinfoBuilder(Builder):
     """
-    Builds Texinfo output to create Info.
+    Builds Texinfo output to create Info documentation.
     """
     name = 'texinfo'
     format = 'texinfo'

sphinx/writers/texinfo.py

@@ -9,7 +9,6 @@
     :license: BSD, see LICENSE for details.
 """
 
-import docutils
 from docutils import nodes, writers
 
 from sphinx import addnodes
@@ -564,7 +563,7 @@ class TexinfoTranslator(nodes.NodeVisitor):
         text = node.astext()
         self.add_text('@cite{%s}' % escape_arg(text))
         raise nodes.SkipNode
-    def visit_title_reference(self, node):
+    def depart_title_reference(self, node):
         pass
 
     ## Blocks

tests/test_build_texinfo.py

@@ -10,12 +10,11 @@
 """
 
 import os
+import re
 import sys
 from StringIO import StringIO
 from subprocess import Popen, PIPE
 
-from sphinx.writers.texinfo import TexinfoTranslator
-
 from util import *
 from test_build_html import ENV_WARNINGS
 
@@ -26,6 +25,8 @@ def teardown_module():
 
 texinfo_warnfile = StringIO()
 
+TEXINFO_WARNINGS = ENV_WARNINGS
+
 if sys.version_info >= (3, 0):
     TEXINFO_WARNINGS = remove_unicode_literals(TEXINFO_WARNINGS)
 
@@ -33,6 +34,12 @@ if sys.version_info >= (3, 0):
 @with_app(buildername='texinfo', warning=texinfo_warnfile, cleanenv=True)
 def test_texinfo(app):
     app.builder.build_all()
+    texinfo_warnings = texinfo_warnfile.getvalue().replace(os.sep, '/')
+    texinfo_warnings_exp = TEXINFO_WARNINGS % {'root': app.srcdir}
+    #assert re.match(texinfo_warnings_exp + '$', texinfo_warnings), \
+    #       'Warnings don\'t match:\n' + \
+    #       '--- Expected (regex):\n' + texinfo_warnings_exp + \
+    #       '--- Got:\n' + texinfo_warnings
     # now, try to run makeinfo over it
     cwd = os.getcwd()
     os.chdir(app.outdir)