IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'stable'

Browse Source
This commit is contained in:
Takeshi KOMIYA
2017-06-13 00:32:39 +09:00
parent 5e2d4ca77b 5f610b7a8b
commit f6d0b07704
9 changed files with 245 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
doc/builders.rst
View File

@@ -206,11 +206,17 @@ The builder's "name" must be given to the **-b** command-line option of
.. autoattribute:: supported_image_types
Note that a direct PDF builder using ReportLab is available in `rst2pdf
<https://github.com/rst2pdf/rst2pdf>`_ version 0.12 or greater. You need to add
``'rst2pdf.pdfbuilder'`` to your :confval:`extensions` to enable it, its name is
``pdf``. Refer to the `rst2pdf manual <https://ralsina.me/static/manual.pdf>`_
for details.
Note that a direct PDF builder is being provided by `rinohtype`_. The builder's
name is ``rinoh``. Refer to the `rinohtype manual`_ for details. There is also
PDF builder using ReportLab in `rst2pdf`_ version 0.12 or greater. However,
rst2pdf is no longer being actively maintained and suffers from some problems
when used with recent Sphinx versions. See the `rst2pdf manual`_ for usage
instructions.
.. _rinohtype: https://github.com/brechtm/rinohtype
.. _rinohtype manual: http://www.mos6581.org/rinohtype/quickstart.html#sphinx-builder
.. _rst2pdf: https://github.com/rst2pdf/rst2pdf
.. _rst2pdf manual: http://ralsina.me/static/manual.pdf
.. module:: sphinx.builders.text
.. class:: TextBuilder

10
doc/faq.rst
View File

@@ -10,9 +10,13 @@ How do I...
-----------
... create PDF files without LaTeX?
You can use `rst2pdf <https://github.com/rst2pdf/rst2pdf>`_ version 0.12 or
greater which comes with built-in Sphinx integration. See the
:ref:`builders` section for details.
`rinohtype`_ provides a PDF builder that can be used as a drop-in
replacement for the LaTeX builder. Alternatively, you can use `rst2pdf`_
version 0.12 or greater which comes with built-in Sphinx integration. See
the :ref:`builders` section for details.
.. _rinohtype: https://github.com/brechtm/rinohtype
.. _rst2pdf: https://github.com/rst2pdf/rst2pdf
... get section numbers?
They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to

14
doc/intro.rst
View File

@@ -7,19 +7,21 @@ formats, automatically producing cross-references, indices etc. That is, if
you have a directory containing a bunch of reST-formatted documents (and
possibly subdirectories of docs in there as well), Sphinx can generate a
nicely-organized arrangement of HTML files (in some other directory) for easy
browsing and navigation. But from the same source, it can also generate a
LaTeX file that you can compile into a PDF version of the documents, or a
PDF file directly using `rst2pdf <https://github.com/rst2pdf/rst2pdf>`_.
browsing and navigation. But from the same source, it can also generate a PDF
file using LaTeX, `rinohtype`_ or `rst2pdf`_ (see :ref:`builders`).
The focus is on hand-written documentation, rather than auto-generated API docs.
Though there is support for that kind of docs as well (which is intended to be
freely mixed with hand-written content), if you need pure API docs have a look
at `Epydoc <http://epydoc.sourceforge.net/>`_, which also understands reST.
Though there is support for that kind of documentation as well (which is
intended to be freely mixed with hand-written content), if you need pure API
docs have a look at `Epydoc <http://epydoc.sourceforge.net/>`_, which also
understands reST.
For a great "introduction" to writing docs in general -- the whys and hows, see
also `Write the docs <http://write-the-docs.readthedocs.org/>`_, written by Eric
Holscher.
.. _rinohtype: https://github.com/brechtm/rinohtype
.. _rst2pdf: https://github.com/rst2pdf/rst2pdf
Conversion from other systems
-----------------------------

127
doc/latex.rst
View File

@@ -60,7 +60,7 @@ It is achieved via usage of the
.. highlight:: latex
If the size of the ``'preamble'`` contents become inconvenient, one may put
If the size of the ``'preamble'`` contents becomes inconvenient, one may move
all needed macros into some file :file:`mystyle.tex` of the project source
repertory, and get LaTeX to import it at run time::
@@ -166,7 +166,7 @@ The available styling options
For Japanese ``'manual'`` docclass with pointsize ``11pt`` or ``12pt``,
use the ``nomag`` extra document class option (cf.
``'extraclassoptions'`` key of :confval:`latex_elements`) or so-called
TeX "true" units:
TeX "true" units::
'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
@@ -224,9 +224,12 @@ The available styling options
``TitleColor``
default ``{rgb}{0.126,0.263,0.361}``. The colour for titles (as configured
via use of package "titlesec".) It must obey the syntax of the
``\definecolor`` command. Check the documentation of packages ``color`` or
``xcolor``.
via use of package "titlesec".)
.. warning::
Colours set via ``'sphinxsetup'`` must obey the syntax of the
argument of the ``color/xcolor`` packages ``\definecolor`` command.
``InnerLinkColor``
default ``{rgb}{0.208,0.374,0.486}``. A colour passed to ``hyperref`` as
@@ -260,85 +263,35 @@ The available styling options
``shadowrule``
default ``\fboxrule``. The width of the frame around :dudir:`topic` boxes.
``noteBorderColor``
default ``{rgb}{0,0,0}``. The colour for the two horizontal rules used by
Sphinx in LaTeX for styling a
:dudir:`note` admonition. Defaults to black.
|notebdcolors|
default ``{rgb}{0,0,0}`` (black). The colour for the two horizontal rules
used by Sphinx in LaTeX for styling a :dudir:`note` type admonition.
.. note::
.. note::
The actual name of the colour as declared to "color" or "xcolor" is
``sphinxnoteBorderColor``. The same "sphinx" prefix applies to all
colours for notices and admonitions.
The actual colour names declared to "color" or "xcolor" are prefixed with
"sphinx".
``hintBorderColor``
default ``{rgb}{0,0,0}``. id.
``importantBorderColor``
default ``{rgb}{0,0,0}``. id.
``tipBorderColor``
default ``{rgb}{0,0,0}``. id.
``noteborder``
``noteborder``, ``hintborder``, ``importantborder``, ``tipborder``
default ``0.5pt``. The width of the two horizontal rules.
``hintborder``
default ``0.5pt``. id.
.. only:: not latex
``importantborder``
default ``0.5pt``. id.
|warningbdcolors|
default ``{rgb}{0,0,0}`` (black). The colour for the admonition frame.
``tipborder``
default ``0.5pt``. id.
.. only:: latex
``warningBorderColor``
default ``{rgb}{0,0,0}``. The colour of the frame for :dudir:`warning` type
admonitions. Defaults to black.
|wgbdcolorslatex|
default ``{rgb}{0,0,0}`` (black). The colour for the admonition frame.
``cautionBorderColor``
default ``{rgb}{0,0,0}``. id.
|warningbgcolors|
default ``{rgb}{1,1,1}`` (white). The background colours for the respective
admonitions.
``attentionBorderColor``
default ``{rgb}{0,0,0}``. id.
``dangerBorderColor``
default ``{rgb}{0,0,0}``. id.
``errorBorderColor``
default ``{rgb}{0,0,0}``. id.
``warningBgColor``
default ``{rgb}{1,1,1}``. The background colour for :dudir:`warning` type
admonition, defaults to white.
``cautionBgColor``
default ``{rgb}{1,1,1}``. id.
``attentionBgColor``
default ``{rgb}{1,1,1}``. id.
``dangerBgColor``
default ``{rgb}{1,1,1}``. id.
``errorBgColor``
default ``{rgb}{1,1,1}``. id.
``warningborder``
|warningborders|
default ``1pt``. The width of the frame.
``cautionborder``
default ``1pt``. id.
``attentionborder``
default ``1pt``. id.
``dangerborder``
default ``1pt``. id.
``errorborder``
default ``1pt``. id.
``AtStartFootnote``
default ``\mbox{ }``. LaTeX macros inserted at the start of the footnote
text at bottom of page, after the footnote number.
@@ -353,6 +306,28 @@ The available styling options
``HeaderFamily``
default ``\sffamily\bfseries``. Sets the font used by headings.
.. |notebdcolors| replace:: ``noteBorderColor``, ``hintBorderColor``,
``importantBorderColor``, ``tipBorderColor``
.. |warningbdcolors| replace:: ``warningBorderColor``, ``cautionBorderColor``,
``attentionBorderColor``, ``dangerBorderColor``,
``errorBorderColor``
.. |wgbdcolorslatex| replace:: ``warningBorderColor``, ``cautionBorderColor``,
``attentionB..C..``, ``dangerB..C..``,
``errorB..C..``
.. else latex goes into right margin, as it does not hyphenate the names
.. |warningbgcolors| replace:: ``warningBgColor``, ``cautionBgColor``,
``attentionBgColor``, ``dangerBgColor``,
``errorBgColor``
.. |warningborders| replace:: ``warningBorder``, ``cautionBorder``,
``attentionBorder``, ``dangerBorder``,
``errorBorder``
LaTeX macros and environments
-----------------------------
@@ -443,10 +418,10 @@ Environments
.. versionadded:: 1.5
options ``verbatimwithframe``, ``verbatimwrapslines``,
``verbatimsep``, ``verbatimborder``.
- the bibliography and Python Module index are typeset respectively within
environments ``sphinxthebibliography`` and ``sphinxtheindex``, which are
simple wrappers of the non-modified ``thebibliography`` and ``theindex``
environments.
- the bibliography uses ``sphinxthebibliography`` and the Python Module index
as well as the general index both use ``sphinxtheindex``; these environments
are wrappers of the ``thebibliography`` and respectively ``theindex``
environments as provided by the document class (or packages).
.. versionchanged:: 1.5
formerly, the original environments were modified by Sphinx.