Sphinx is pretty great for generating nice looking documents in a variety of output formats, but one place it is pretty weak is in handling figures and references to figures. In html output, figures aren't automatically numbered, while they are in latex output. Despite having nicely numbered figures in latex, when you use :ref: to refer to them, it still replaces the reference with the full text of the figure caption, instead of refering to them by number.
My attempt at a solution is this sphinx extension: numfig. It adds figure numbers to html figure captions and provides two new sphinx roles, :num: and :page:. The :num: role can be used to refer to figures by figure number instead of caption, while the :page: role can be used to refer to the page number the figure occurs on. More detailed documentation and example usage can be found in the bitbucket page wiki.
