[Qgis-community-team] Issues with figure numerotation cleanup

[DelazJ]

Hi all,

Currently, most of the figures in QGIS doc are preceded by a kind of
numbered title (ex: *Figure Vector General 2)* [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.
In the .rst file, those "titles" are also preceded by a numbered reference (
*_figure_vector_general_2* e.g., which follows the spelling of the title,
unless it's the inverse. never mind).

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 *_figure_vector_query builder* and *Figure Vector Query Builder*. This
ensures unicity of reference and title and no need to update when new
figure is inserted.

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] :

- 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.
So should we keep it?

- 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.
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].

So, my plan therefore is to:

- remove (instead of renaming) the "false" title at the top of the figure
- 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
- and expect migration to a newer sphinx version to have all these changes
cleaned for the next release.

Any comments?

Greetings,
Harrissou

[1]
http://docs.qgis.org/2.14/fr/docs/user_manual/working_with_vector/vector_properties.html
[2]
http://docs.qgis.org/2.14/en/docs/documentation_guidelines/writing.html#figure
[3]
http://www.sphinx-doc.org/en/stable/config.html?highlight=figure#confval-numfig
[4] https://github.com/qgis/QGIS-Documentation/issues/788
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20161020/42048b99/attachment.html>