Sphinx PDF themes

[Minkai Li]

Does the Sphinx documentation tool offer different PDF themes？Sphinx doesn't generate PDF output by itself，Ituse the Latex builder。How to set the sphinx pdf themes?

[gilberto dos santos alves]

[1] https://www.tug.org/texlive/doc.html
hi. there are many ways for builing pdf from Latex please see [1]

--
gilberto dos santos alves
+55(11)9-8646-5049
sao paulo - sp - brasil

2016-10-06 9:20 GMT-03:00 Minkai Li <limin...@gmail.com>:

Does the Sphinx documentation tool offer different PDF themes？Sphinx doesn't generate PDF output by itself，Ituse the Latex builder。How to set the sphinx pdf themes?

--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users+unsubscribe@googlegroups.com.
To post to this group, send email to sphinx...@googlegroups.com.
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.

[Peter Burdine]

For Sphinx, most people create a preamble.tex file that modifies the formatting Sphinx uses.  As of 1.4.x of Sphinx, there isn't much in the way of global styling options.  You have to learn a bit of Latex.

[Minkai Li]

sphinx can generate Latex,the pdf it produces via latex, I'm using sphinx to generate documentations. The tables it produces via latex are pretty ugly, so I'd like to give them some global styling. I'd like to customize tableheader row color.I add the directive 

在此输入代\usepackage{tabu,tabulary}码...\usepackage[table]{xcolor}\definecolor{tablehead}{rgb}{153,153,153 }

into my conf.py peramble  but it does not work.

在 2016年10月7日星期五 UTC+8上午8:23:47，Peter Burdine写道：

[Peter Burdine]

Sphinx tables in latex are inconsistent at the moment.  There is a ticket open to use just one package for tables, but right now I think it picks 1 of 4(?) packages depending on what it thinks it best.  In all of the documentation we write, I always add :class: longtable to all of the table definitions to allow for (what I think) is better layout, plus the header/footer for continuations.

You can format the columns and overall table width using the tabularcolumns directive, eg

.. tabularcolumns:: |>{\RaggedRight}p{\dimexpr 0.3\linewidth-2\tabcolsep}
                    |>{\RaggedRight}p{\dimexpr 0.5\linewidth-2\tabcolsep}
                    |>{\RaggedRight}p{\dimexpr 0.2\linewidth-2\tabcolsep}|

Adding that everywhere tends to get annoying quickly, plus is is difficult for most people understand what is going on (FYI this produces a table with 3 columns, all left aligned, with 30%, 50%, and 20% of the page widths).

IIRC, xcolor doesn't work with all table packages, hence why it might be working for you.  I'd have to look through the latex writer code to find all of the table packages that are used, but it possible that it may work with one of the table packages, then you could use the :class: option to always use that package.

[Warren Block]

On Mon, 10 Oct 2016, Peter Burdine wrote:

> Sphinx tables in latex are inconsistent at the moment.  There is a ticket open to use just one package for tables, but right now I think it picks 1 of 4(?) packages depending on what it thinks it best.  In all of the documentation we write, I always
> add :class: longtable to all of the table definitions to allow for (what I think) is better layout, plus the header/footer for continuations.
>
> You can format the columns and overall table width using the tabularcolumns directive, eg
> .. tabularcolumns:: |>{\RaggedRight}p{\dimexpr 0.3\linewidth-2\tabcolsep}
>                     |>{\RaggedRight}p{\dimexpr 0.5\linewidth-2\tabcolsep}
>                     |>{\RaggedRight}p{\dimexpr 0.2\linewidth-2\tabcolsep}|
>
> Adding that everywhere tends to get annoying quickly, plus is is difficult for most people understand what is going on (FYI this produces a table with 3 columns, all left aligned, with 30%, 50%, and 20% of the page widths).

What else is needed to use this? If I add it, PDF creation halts in the
middle, with

! Undefined control sequence.
<template> ...inewidth -2\tabcolsep }\RaggedRight
\ignorespaces
l.5169 \textsf
{\relax
?

This is sphinx 1.4.6.

[Peter Burdine]

Please post the tabularcolumns directive you are using and enough of the table definition to see the first header row.  There isn't enough info to see what the issue could be.

One thing to verify is that the number of columns in the tabularcolumns directive is the same as the actual table.

--
You received this message because you are subscribed to a topic in the Google Groups "sphinx-users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/sphinx-users/LBGxmGESUhg/unsubscribe.
To unsubscribe from this group and all its topics, send an email to sphinx-users+unsubscribe@googlegroups.com.

[Warren Block]

On Tue, 25 Oct 2016, Peter Burdine wrote:

>
> Please post the tabularcolumns directive you are using and enough of the table definition to see the first header row.  There isn't enough info to see what the issue could be.
>
> One thing to verify is that the number of columns in the tabularcolumns directive is the same as the actual table.

Sorry, here's a bit:

.. tabularcolumns:: |R|R|L|

.. _tasks_rsync_opts_tab:

.. table:: Rsync Configuration Options
:class: longtable

+------------+----------+----------------+
| Setting | Value | Description |


This produces

! Missing # inserted in alignment preamble.
<to be read again>
\cr
l.5164 \begin{longtable}{|p{1.0cm}|p{1.0cm}|L|}

The \RaggedRight colspec produces the "undefined control sequence" shown
earlier. Using |p{1.0cm}|p{1.0cm}|L| gives

! Missing # inserted in alignment preamble.
<to be read again>
\cr
l.5164 \begin{longtable}{|p{1.0cm}|p{1.0cm}|L|}

I have no preamble, so maybe it's that. Or maybe another extension is
needed, at the moment only ifconfig and httpdomain are declared. But
without the tabularcolumns directive, it does produce a PDF.

Thanks!

> On Oct 24, 2016 4:40 PM, "Warren Block" <wbl...@wonkity.com> wrote:
> On Mon, 10 Oct 2016, Peter Burdine wrote:
>
> Sphinx tables in latex are inconsistent at the moment.  There is a ticket open to use just one package for tables, but right now I think it picks 1 of 4(?) packages depending on what it thinks it best.  In all of the
> documentation we write, I always
> add :class: longtable to all of the table definitions to allow for (what I think) is better layout, plus the header/footer for continuations.
>
> You can format the columns and overall table width using the tabularcolumns directive, eg
> .. tabularcolumns:: |>{\RaggedRight}p{\dimexpr 0.3\linewidth-2\tabcolsep}
>                     |>{\RaggedRight}p{\dimexpr 0.5\linewidth-2\tabcolsep}
>                     |>{\RaggedRight}p{\dimexpr 0.2\linewidth-2\tabcolsep}|
>
> Adding that everywhere tends to get annoying quickly, plus is is difficult for most people understand what is going on (FYI this produces a table with 3 columns, all left aligned, with 30%, 50%, and 20% of the page widths).
>
>
> What else is needed to use this?  If I add it, PDF creation halts in the middle, with
>
>   ! Undefined control sequence.
>   <template> ...inewidth -2\tabcolsep }\RaggedRight
>                                                     \ignorespaces
>   l.5169 \textsf
>                 {\relax
>   ?
>
> This is sphinx 1.4.6.
>
> --
> You received this message because you are subscribed to a topic in the Google Groups "sphinx-users" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/topic/sphinx-users/LBGxmGESUhg/unsubscribe.

> To unsubscribe from this group and all its topics, send an email to sphinx-users...@googlegroups.com.

> To post to this group, send email to sphinx...@googlegroups.com.
> Visit this group at https://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/d/optout.
>
>

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.

[Peter Burdine]

The following worked fine for me:

    .. tabularcolumns:: |>{\RaggedRight}p{\dimexpr 0.3\linewidth-2\tabcolsep}

                        |>{\RaggedRight}p{\dimexpr 0.4\linewidth-2\tabcolsep}
                        |>{\RaggedLeft}p{\dimexpr 0.3\linewidth-2\tabcolsep}|

    .. _tasks_rsync_opts_tab:                        
                       
    .. table:: Rsync Configuration Options
        :class: longtable

        +------------+----------+----------------+
        | Setting    | Value    | Description    |

        +------------+----------+----------------+
        | Setting    | Value    | Description    |
        +------------+----------+----------------+  

Also, the commands are l, r, and c, not L, R, C.  So the following also works:

.. tabularcolumns:: |r|r|l|

See https://en.wikibooks.org/wiki/LaTeX/Tables

I always specify the width I want for PDF output to ensure that latex doesn't do anything weird with the wrapping or have text run into the next cell.  Normally I use list tables because I think they are easier to maintain (and contain other nodes, like lists and admonitions), so I am not sure if the same behavior happens with simple tables.

[Warren Block]

On Wed, 26 Oct 2016, Peter Burdine wrote:

> The following worked fine for me:
>     .. tabularcolumns:: |>{\RaggedRight}p{\dimexpr 0.3\linewidth-2\tabcolsep}
>                         |>{\RaggedRight}p{\dimexpr 0.4\linewidth-2\tabcolsep}
>                         |>{\RaggedLeft}p{\dimexpr 0.3\linewidth-2\tabcolsep}|
>
>     .. _tasks_rsync_opts_tab:                        
>                        
>     .. table:: Rsync Configuration Options
>         :class: longtable
>
>         +------------+----------+----------------+
>         | Setting    | Value    | Description    |
>         +------------+----------+----------------+
>         | Setting    | Value    | Description    |
>         +------------+----------+----------------+  

Not here, the same ! Undefined control sequence error as before. My
guess is this is some TeX stuff that would normally be included from a
file that is not present on my system.

> Also, the commands are l, r, and c, not L, R, C.  So the following also works:
> .. tabularcolumns:: |r|r|l|

In fairness, http://www.sphinx-doc.org/en/1.4.8/markup/misc.html?highlight=tabularcolumns
shows this in an ambiguous form. An example of actual usage would be
useful there. Or in so many other places in the Sphinx docs.
Actually, the more I look at that explanation, the less clear it
becomes.

(Much experimentation later...)

The "p notation" vaguely mentioned in the docs is p{}, with a width
value and unit in the brackets, like 'p{1.0in}'. Used alone, this value
specifies an absolute width for a column, with the default being
fill-justified, wrapped text in that column. Example:

.. tabularcolumns:: |p{1.0in}|p{1.2in}|p{3.8in}|

That gives a three-column table with fill-justified, wrapped text in
each column.

'l' and 'r' are used to left- or right-justify *and prevent wrapping*.
These letters can be added after the p{} width, but doing so resulted in
unpredictable column rendering. I did not find a way to get specific or
relative column widths without fill-justification and word breaks.

The upper-case letters mentioned did not work in any context I tried,
with or without the p{} width. It is not clear why they are shown at
all, or whether that is some misguided capitalization of a name that is
not actually meant to be capitalized.

[Peter Burdine]

Sorry about that, now that I think about it, that requires the following in your preamble:

\usepackage{array,ragged2e}

Sorry about that, it is difficult to remember all of the requirements.  Does that help?

[Warren Block]

On Thu, 27 Oct 2016, Peter Burdine wrote:

> Sorry about that, now that I think about it, that requires the following in your preamble:
> \usepackage{array,ragged2e}
>
> Sorry about that, it is difficult to remember all of the requirements.  Does that help?

It does and I might try it, but after adding table column widths,
several pages of the PDF have non-table text running off the bottom of
the page. So it's looking it might be necessary to use rst2pdf.

[Brecht Machiels]

Hi,

I don't have much experience with the Sphinx LaTeX builder and tables,
so I can't offer any useful advice about that specifically.

However, I will take this opportunity to suggest that you try the
rinohtype Sphinx builder, which also produces PDF output. rinohtype is
still in beta phase, but should be able to render most Sphinx
documents. More importantly, styling of the document should be much
easier compared to LaTeX. You can find more information here:
http://www.mos6581.org/rinohtype/

I would be very interested to receive feedback on how it handles
documents with complex tables requirements. Please report any issues or
submit suggestions on the project's issue tracker:
https://github.com/brechtm/rinohtype/issues

I will be making a new release in the next couple of days. I'll
announce it on this mailing list when it is available.

Best regards,
Brecht

[Warren Block]

rinohtype is on the short remaining list of PDF renderers to test. I
actually started, but ran out of time before a business trip. Maybe our
docs can be a helpful test case.

Thanks!