qgis
Mismatch between figure/table numbering in PDF vs. HTML docs
Description
HTML documentation
Figure/table numbering does not reset across chapters of the separate manuals/guides. For example, in the QGIS Desktop User Guide, the fourth chapter, "4. The Browser panel," contains two captioned figures, which Sphinx has numbered 4.1 and 4.2. In the QGIS Server Guide, the fourth chapter, "4. Catalog," contains five figures, which Sphinx has numbered 4.3 to 4.7. In other words, the "Chapter 4" numbering carries over from the Desktop User Guide to the Server Guide.
PDF documentation
When I build the PDF documentation (version 3.40) with make pdf, however, the figure/table numbering resets across each manual. In other words, in the example above, the QGIS Desktop User Guide contains two figures in Chapter 4, both numbered 4.1 and 4.2 (same as the HTML), but the QGIS Server Guide contains five figures numbered 4.1 to 4.5 (different than the HTML).
Possible issue
The Sphinx conf.py file groups the document tree into separate LaTeX files:
latex_documents = [
('docs/about/index', 'AboutQGIS.tex',
f'About QGIS {version}', u'QGIS Project', 'manual'),
('docs/user_manual/index', 'DesktopUserGuide.tex',
f'QGIS Desktop {version} User Guide', u'QGIS Project', 'manual'),
('docs/server_manual/index', 'ServerUserGuide.tex',
f'QGIS Server {version} User Guide', u'QGIS Project', 'manual'),
('docs/pyqgis_developer_cookbook/index', 'PyQGISDeveloperCookbook.tex',
f'PyQGIS {version} developer cookbook', u'QGIS Project', 'manual'),
('docs/training_manual/index', 'TrainingManual.tex',
u'QGIS Training Manual', u'QGIS Project', 'manual'),
('docs/gentle_gis_introduction/index', 'GentleGISIntroduction.tex',
u'Gentle GIS Introduction', u'QGIS Project', 'manual'),
('docs/documentation_guidelines/index', 'DocumentationGuidelines.tex',
u'QGIS Documentation Guidelines', u'QGIS Project', 'manual'),
make pdf then runs XeLaTeX on each of the seven .tex files separately. Hence, XeLaTeX numbers the figures/tables for each manual separately.
With make html, in contrast, Sphinx treats all of the manuals as a single work, and, as a result, continues numbering figures/tables in each "Chapter 4" based on the last figure/table number in "Chapter 4" in the previous manual.
Follow up: This seems to be a known issue with Sphinx (https://github.com/sphinx-doc/sphinx/issues/8170) that has yet to be resolved.
@DelazJ My pleasure. I'll circle back around on this issue if the Sphinx team decide to accept the pull request.