Re: multiple images per figure, figure captions

[Guenter Milde]

On 2013-02-17, Matthew Newville wrote:

> First I should say that I'm really impressed with Sphinx, and thank you
> for providing and supporting it: Wonderful!

> OK, I'd like to see better capabilities for figures in documents, including
> * auto-numbering and referencing.
> * multiple parts to a figure (e.g, side-by-side, or in a grid).
> * good results in both html and latex/pdf.

> So far, I haven't quite found a solution with all these features, and was
> hoping either for some pointers on how to do this better, or pointers on
> how to make it so that sphinx can make this easier.

These problems are known issues in the Docutils_ which Sphinx is based on.
See http://docutils.sourceforge.net/docs/dev/todo.html#object-numbering-and-object-references
http://permalink.gmane.org/gmane.text.docutils.devel/5966
http://docutils.sourceforge.net/docs/dev/todo.html#configurable-placement-of-figure-and-table-floats

I would prefer a solution on the "Docutils level" very much over a
Sphinx-only extension to reStructuredtext.

A test input file
http://docutils.sourceforge.net/sandbox/latex-variants/tests/figure-reference.txt
With CSS2, figures could be auto-numbered but I don't know of a way to
use this auto-number in a reference. Maybe CSS3 offers support for this?


Workarounds:

> But this doesn't support auto-numbering or references.

> One could put figures in a table::

> +------------------------+------------------------+
> |.. _figa: |.. _figb: |
> | | |
> |.. figure:: left.png |.. figure:: right.png |
> | :width: 95 % | :width: 95 % |
> | :align: center | :align: center |
> | | |
> | Caption A here | Caption B here |
> +------------------------+------------------------+

> See :num:`Figure #figa` for details.

> But this has two problems: a) it leaves each figure as a separate entity,
> with it's own label and caption,

You can use the "table directive" that provides for a caption.
Drawback: the caption gets the "Table" prefix in LaTeX.

> b) it doesn't render correctly in
> latex / pdf, as it puts each figure environment as a portion of a table
> (tabulary) environment, which causes errors because the figure environment
> is not in "Outer par mode".

Try with the "image" directive instead of "figure".


.. table::
:class: borderless

+------------------------+------------------------+
|.. _figa: |.. _figb: |
| | |
|.. image:: left.png |.. image:: right.png |
| :width: 95 % | :width: 95 % |
| :align: center | :align: center |
| | |
|Caption A here |Caption B here |
+------------------------+------------------------+


> I tried many combinations of figure and image directives, but could not
> find a workable solution. As it is, I'm left with document tree with
> dozens of figures that have to be numbered by hand.

> Is there a way to accomplish all of these features (auto-numbering and
> referencing of figures, multiple parts to figures, rendering in both html
> and latex/pdf)?

> If not, is there any chance of adding better support for figures, say with
> a grid of sub-figures?

While the problem is known, ressources for discussing the right approach
(without backward-compatibility breaks) and developing a solution are
severely limited. Help is welcome.

Günter

[Matthew Newville]

Hi Guenter,

On Monday, February 18, 2013 2:29:18 AM UTC-6, Guenter Milde wrote:

On 2013-02-17, Matthew Newville wrote:

> First I should say that I'm really impressed with Sphinx, and thank you
> for providing and supporting it: Wonderful!

> OK, I'd like to see better capabilities for figures in documents, including
>   * auto-numbering and referencing.
>   * multiple parts to a figure (e.g, side-by-side, or in a grid).
>   * good results in both html and latex/pdf.

> So far, I haven't quite found a solution with all these features, and was
> hoping either for some pointers on how to do this better, or pointers on
> how to make it so that sphinx can make this easier.

These problems are known issues in the Docutils_ which Sphinx is based on.
See http://docutils.sourceforge.net/docs/dev/todo.html#object-numbering-and-object-references
http://permalink.gmane.org/gmane.text.docutils.devel/5966
http://docutils.sourceforge.net/docs/dev/todo.html#configurable-placement-of-figure-and-table-floats

I would prefer a solution on the "Docutils level" very much over a
Sphinx-only extension to reStructuredtext.

Thanks for the reply.   I appreciate that the limitation is essentially from docutils, and agree with the idea of "nesting with empty directive argument"  from the earlier conversation.   Expanding docutils "figure" to mean something a bit more rich than "1 image plus caption"  would be very good.   
   

But this won't allow auto-numbering with numfig.
 

> I tried many combinations of figure and image directives, but could not
> find a workable solution.  As it is, I'm left with document tree with
> dozens of figures that have to be numbered by hand.    

> Is there a way to accomplish all of these features (auto-numbering and
> referencing of figures, multiple parts to figures, rendering in both html
> and latex/pdf)?

> If not, is there any chance of adding better support for figures, say with
> a grid of sub-figures?

While the problem is known, ressources for discussing the right approach
(without backward-compatibility breaks) and developing a solution are
severely limited. Help is welcome.

 I haven't looked into the details of docutils or its development process at all.  Do you think it is reasonable to propose a change of this nature (either enhancing the figure directive or adding an extended figure directive to docutils? 

Thanks,

--Matt Newville