Figure caption for python figures

[hagenw]

For the figures created with .. plot::, there is in theory the possibility to gave them a caption, but this seems to work only for code included from files.

At the moment I solved the problem, by adding another figure:

.. plot::

    # some code here that produces a figure

.. _fig-some-figure:

.. figure:: img/placeholder.png
    :align: center

    Caption of the figure.

The placeholder.png file is a 1px large file as we have to include something.

Another disadvantage is that the provided permalink will only point to this small image (so, only to the caption) and the actual figure will be hidden and you have to scroll up.

[mgeier]

Does "numfig" help?

http://www.sphinx-doc.org/en/stable/config.html?highlight=numfig#confval-numfig
https://bitbucket.org/birkenfeld/sphinx/pull-requests/303/add-numref-role-to-refer-figures-tables/diff
https://bitbucket.org/arjones6/sphinx-numfig/wiki/Home
http://sourceforge.net/p/numfig/wiki/Home/
https://pypi.python.org/pypi/sphinx_numfig

[hagenw]

We are using already numfig.
The problem is you cannot write the code in this way:

.. _fig-some-figure:

.. plot::

    # some code here that produces a figure

    Caption of the figure.

This will return a SyntaxError: invalid syntax error.

That is the reason why I added an additional .. figure:: command. If you look at the generated HTML it looks ok, but it generates two divs that are called figure, which is of course not so nice.

So, the problem is not, that it is not working altogether, but that it should work in a better way ;)

[mgeier]

This might be interesting: jupyter/notebook#811

[mgeier]

These might be interesting: sphinx-doc/sphinx#1858 and sphinx-doc/sphinx#2317.

[hagenw]

OK, so hopefully it will work with sphinx 1.4

[hagenw]

The proposed changes to sphinx are included now, but the problem is that also plot_directive.py of Matplotlib has to change, and this is not done yet: matplotlib/matplotlib#9346
So we have to stick with the workaround for a while, I guess.

Considering also sphinx-doc/sphinx#4080, there seems to be a general problem or maybe a not so elegant implementation of references in sphinx.

[hagenw]

This is currently solved by the following workaround implemented by ef70c7b

.. plot::
    :nofigs:

    # some code here that produces a figure

.. plot::
    :context:
    :include-source: false
    :nofigs:

    save_fig('some-figure')

.. _fig-some-figure:

.. figure:: some-figure.*
    :align: center

    Caption of the figure.

Whereas save_fig() is a custom function using Matplotlib to save to png and pdf.