<div dir="ltr"><div><div><div><div><div><div><div><div><div><div>Hi all,<br><br></div>Currently, most of the figures in QGIS doc are preceded by a kind of numbered title (ex: <strong>Figure Vector General 2)</strong> [1], meaning that when a new figure is added, the documenter should update the number of the following figures in the chapter. Not a really fulfilling task.<br></div><div>In the .rst file, those "titles" are also preceded by a numbered reference (<b>_figure_vector_general_2</b> e.g., which follows the spelling of the title, unless it's the inverse. never mind).<br><br></div>So as discussed with Yves Jacolin and Alexander Neto (I can't recall when nor where), I began to fix these "titles" by replacing the number by a text related to the figure content, meaning that, for the example above, I'd have <b>_figure_vector_query builder</b> and <b>Figure Vector Query Builder</b>. This ensures unicity of reference and title and no need to update when new figure is inserted.<br><br>BUT, i wonder if there is any real value/benefit in my fix, so would like to have your opinions and understand the reason of this design [2] :<br><br></div>- what is the real purpose of this title? It appears only in html (not in the pdf doc), the text is currently meaningless and with my proposal will simply be a kind of shortened duplicate of the real caption of the figure (present at the bottom of the figure). If it's about figure numbering then upgrading Sphinx and use the numfig variable  [3] in the configuration file would ensure to cover numbering of captions in both pdf and html.<br>So should we keep it?<br><br></div></div>- Is it mandatory to have a reference before every "title"?  As they follow the numbering system, the contributor must ensure to have updated all occurrences in the doc (if any) otherwise they lead to a wrong image (--> more work). Using a unique and not sequential naming would solve also this issue.<br></div>But actually, few references are used in the doc to point the reader to a figure. And when they are, they make the pdf doc incomprehensible as they refer to a "title" that doesn't appear in the pdf doc [4].<br><br></div>So, my plan therefore is to:<br><br></div>- remove (instead of renaming) the "false" title at the top of the figure<br></div>- remove (instead of renaming) the reference if it isn't used elsewhere. If used elsewhere, then it'll render the real caption of the figure in the text, for both html and pdf outputs. And if i'm not wrong, it'll also be possible to reference images from another chapter<br></div>- and expect migration to a newer sphinx version to have all these changes cleaned for the next release.<br><div><br></div><div>Any comments?<br></div><div><div><div><div><div><br></div><div>Greetings,<br></div><div>Harrissou<br></div><div><div><div><div><br><div><div>[1] <a href="http://docs.qgis.org/2.14/fr/docs/user_manual/working_with_vector/vector_properties.html">http://docs.qgis.org/2.14/fr/docs/user_manual/working_with_vector/vector_properties.html</a><br>[2] <a href="http://docs.qgis.org/2.14/en/docs/documentation_guidelines/writing.html#figure">http://docs.qgis.org/2.14/en/docs/documentation_guidelines/writing.html#figure</a><br>[3]  <a href="http://www.sphinx-doc.org/en/stable/config.html?highlight=figure#confval-numfig">http://www.sphinx-doc.org/en/stable/config.html?highlight=figure#confval-numfig</a><br>[4] <a href="https://github.com/qgis/QGIS-Documentation/issues/788">https://github.com/qgis/QGIS-Documentation/issues/788</a><br></div></div></div></div></div></div></div></div></div></div></div>