Incompatibility with caption package, no hooks to style captions

[jessetan]

Problem

In Sphinx < 1.6, the caption package could be used to style captions, e.g.:

\usepackage{caption}
\captionsetup{font=it}

Since Sphinx 1.6, including the caption package causes the caption to jump to the right.

Procedure to reproduce the problem

index.rst:

.. list-table:: My table

    * - foo
      - foo
    * - foo
      - foo

conf.py:

latex_elements = {
    'preamble': '\\usepackage{caption}\n\\captionsetup{font=it}'
}

Expected results

Either:

• Sphinx is compatible with caption package so that it does not indent/move caption and can be used to style captions
• Or alternatively, allow caption styling using a Sphinx-specific LaTeX command that can be renewed (similar to \sphinxtablecontinued and \sphinxstyleemphasis)

Environment info

• Sphinx version: 1.6+
• TexLive version: MacTex 2.17

[jfbu]

You can go a long way by simply adding

\renewcommand\sphinxcaption{\caption}

via the preamble key of latex_elements.

I recommend using \captionsetup{width=\LTcapwidth} also, because longtable uses \LTcapwidth as wrapping width for long titles. The \sphinxcaption was a way to apply this also to tabular/tabulary, but caption package has this width option.

You are going to lose some exact same distance from title to top of tabular compared to from title to top of longtable (in my brief testing, and it depends if title ends with descender letters). I am not 100% sure (untested) if it will still work with captions used inside tabular cell but I think it should work because the \sphinxcaption was mainly for this story of width and for obtaining exact same distance to top of table in all cases. I admit having made a mistake in not inserting styling hooks in it. Sphinx also has special way of handling captions of literal blocks so it is all a bit involved.

Can you report how the above works out on your real use cases ?

[jfbu]

Fixed at 9c8c210.

Addition of \sphinxstylecaptiontext... kind of macros can still be considered for addition at 2.0. And there is still some work to do regarding captions of literal blocks and particularly for figures, because the latter currently do not allow customization of relative position.

Thanks for reporting.

[jessetan]

Update: using the captions package can result in a page break between the caption and table body for regular tables (not longtable). If the table does not fit on the remaining space, it will be pushed to the next page, but the caption will not come with it.

Workaround: make the table a longtable or do not use captions package.

This is not an issue for me since we use longtables exclusively, but may be useful information for other users, or may influence the path forward for Sphinx-native styling of captions (without extra packages)

[electronstudio]

So how can I style captions currently?

[astrojuanlu]

@electronstudio This is a very old issue, please use the support channels of Sphinx for your question (a new issue, the sphinx-users mailing list, or Stack Overflow)