diff options
| -rw-r--r-- | AUTHORS | 1 | ||||
| -rw-r--r-- | CHANGES | 2 | ||||
| -rw-r--r-- | doc/builders.rst | 19 | ||||
| -rw-r--r-- | doc/config.rst | 68 | ||||
| -rw-r--r-- | doc/faq.rst | 121 | ||||
| -rw-r--r-- | sphinx/builders/texinfo.py | 13 | ||||
| -rw-r--r-- | sphinx/writers/texinfo.py | 3 | ||||
| -rw-r--r-- | tests/test_build_texinfo.py | 11 |
8 files changed, 121 insertions, 117 deletions
@@ -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 @@ -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. diff --git a/doc/builders.rst b/doc/builders.rst index 71e28a7c..4a95e120 100644 --- a/doc/builders.rst +++ b/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 - 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 + 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``. diff --git a/doc/config.rst b/doc/config.rst index 493a7d83..fbf7fc40 100644 --- a/doc/config.rst +++ b/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 - 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. @@ -1049,32 +1049,31 @@ 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. + 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. + * *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 @@ -1088,23 +1087,24 @@ These options influence Texinfo output. .. 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'`` diff --git a/doc/faq.rst b/doc/faq.rst index bd516a5f..0c2d2c4f 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -155,92 +155,89 @@ some notes: 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: @@ -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 - closely resemble reST, add the following to your :file:`conf.py`:: - - texinfo_elements = {'preamble': """\ - @definfoenclose strong,**,** - @definfoenclose emph,*,* - @definfoenclose code,`@w{}`,`@w{}` - """} + ``@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{}` + """} diff --git a/sphinx/builders/texinfo.py b/sphinx/builders/texinfo.py index d65a4681..b08c0cd6 100644 --- a/sphinx/builders/texinfo.py +++ b/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 $(INSTALL_INFO) --delete --info-dir=$(infodir) "$$f" ;\\ +\t rm -f "$(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' diff --git a/sphinx/writers/texinfo.py b/sphinx/writers/texinfo.py index c3b8fdc0..6ea3a3fe 100644 --- a/sphinx/writers/texinfo.py +++ b/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 diff --git a/tests/test_build_texinfo.py b/tests/test_build_texinfo.py index 33dbcc91..295097ec 100644 --- a/tests/test_build_texinfo.py +++ b/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) |