mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
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.
This commit is contained in:
Georg Brandl
parent
e6f5d36a0b
commit
bd268c7182
1
AUTHORS
1
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
|
||||
|
||||
|
||||
2
CHANGES
2
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.
|
||||
|
||||
@ -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.
|
||||
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``.
|
||||
|
||||
@ -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:
|
||||
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
|
||||
|
||||
@ -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'``
|
||||
|
||||
73
doc/faq.rst
73
doc/faq.rst
@ -155,48 +155,46 @@ 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``.
|
||||
|
||||
::
|
||||
|
||||
@ -221,20 +219,19 @@ your start-up file, ``~/.emacs.d/init.el``.
|
||||
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
|
||||
|
||||
@ -249,8 +246,8 @@ 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`::
|
||||
``@definfoenclose``. For example, to make inline markup more closely resemble
|
||||
reST, add the following to your :file:`conf.py`::
|
||||
|
||||
texinfo_elements = {'preamble': """\
|
||||
@definfoenclose strong,**,**
|
||||
|
||||
@ -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'
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user