From 4749157bd378ed9d23424a263f75d6f0e611e1bb Mon Sep 17 00:00:00 2001 From: Brecht Machiels Date: Mon, 5 Jun 2017 14:51:35 +0200 Subject: [PATCH] Docs: mention rinohtype as an alternative PDF builder --- doc/builders.rst | 16 +++++++++++----- doc/faq.rst | 10 +++++++--- doc/intro.rst | 14 ++++++++------ 3 files changed, 26 insertions(+), 14 deletions(-) diff --git a/doc/builders.rst b/doc/builders.rst index 190f62cb9..9aad16a5f 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -226,11 +226,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 -`_ 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 `_ -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 diff --git a/doc/faq.rst b/doc/faq.rst index 133614ef2..1ae9a7792 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -10,9 +10,13 @@ How do I... ----------- ... create PDF files without LaTeX? - You can use `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 diff --git a/doc/intro.rst b/doc/intro.rst index b79f7f4a4..d3328a5ea 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -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 `_. +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 `_, 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 `_, which also +understands reST. For a great "introduction" to writing docs in general -- the whys and hows, see also `Write the docs `_, written by Eric Holscher. +.. _rinohtype: https://github.com/brechtm/rinohtype +.. _rst2pdf: https://github.com/rst2pdf/rst2pdf Conversion from other systems -----------------------------