Georg Brandl avatar Georg Brandl committed 0c12286

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.

Comments (0)

Files changed (8)

 * 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
 
 
 * 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.
 .. 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.
+   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
+   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``.
      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
-     an empty string or list if you do not want to automatically generate
-     an AUTHORS section in the manual page.
+   * *authors*: A list of strings with authors, or a single string.  Can be an
+     empty string or list if you do not want to automatically generate an
+     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.
 
 
 .. 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:
+   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.
+   * *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.
+   * *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_elements
 
-   A dictionary that contains Texinfo snippets that override those Sphinx usually
-   puts into the generated ``.texi`` files.
+   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.
+        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.
+        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:
+   * Keys that are set by other options and therefore should not be overridden
+     are:
 
      ``'filename'``
      ``'title'``
 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.
+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).
+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::
+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:
+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
+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``.
+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 Docutils or 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\\|Docutils\\)"
-                 (save-excursion (search-forward "" nil t)) t)
-            (set (make-local-variable 'Info-hide-note-references)
-                 'hide)))))
+   (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 Docutils or 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\\|Docutils\\)"
+                (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:
+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 ``:``.
+- 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.
+- 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::
+- Links to external Info files can be created using the somewhat official URI
+  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:
 
   * 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`::
+  ``@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{}`
-      """}
+     texinfo_elements = {'preamble': """\
+     @definfoenclose strong,**,**
+     @definfoenclose emph,*,*
+     @definfoenclose code,`@w{}`,`@w{}`
+     """}

sphinx/builders/texinfo.py

     :license: BSD, see LICENSE for details.
 """
 
-import os
 from os import path
 
 from docutils import nodes
 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
 
 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  $(INSTALL_INFO) --delete --info-dir=$(infodir) "$$f" ;\\
+\t  rm -f "$(infodir)/$$f"  ; \\
+\t  $(INSTALL_INFO) --delete --info-dir=$(infodir) "$$f" ; \\
 \tdone
 
 %.info: %.texi
 
 class TexinfoBuilder(Builder):
     """
-    Builds Texinfo output to create Info.
+    Builds Texinfo output to create Info documentation.
     """
     name = 'texinfo'
     format = 'texinfo'

sphinx/writers/texinfo.py

     :license: BSD, see LICENSE for details.
 """
 
-import docutils
 from docutils import nodes, writers
 
 from sphinx import addnodes
         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

 """
 
 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
 
 
 texinfo_warnfile = StringIO()
 
+TEXINFO_WARNINGS = ENV_WARNINGS
+
 if sys.version_info >= (3, 0):
     TEXINFO_WARNINGS = remove_unicode_literals(TEXINFO_WARNINGS)
 
 @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)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.