Make it possible to disable numfig for certain elements

[choldgraf]

Is your feature request related to a problem? Please describe.

Numfig is a useful way to automatically add numbering to many kinds of elements. However, by default it automatically adds numbers to many different kinds of elements, not just Figures. There are many cases where you'd want to number one element (e.g. Figures) but not other elements (e.g., code blocks). It is not currently possible to do this.

Describe the solution you'd like

I'd like to be able to configure numfig to disable automatic numbering for certain directives. For example, something like:

# Only apply numfig numbering to figures and tables
numfig_enabled_classes = ["figure", "table"]

Describe alternatives you've considered

Alternatively you could just "live with" the numbering for all these different types of directives But this creates some awkward patterns (e.g. it adds Listing N before each code block caption, which doesn't make sense if you're following the common pattern of using the caption block to show the file name for a code snippet).

[marc-hb]

For what it's worth I found that numfig slows down BOTH the incremental build and build from scratch in the zephyr project by a factor of ... 5-6 times!!

• https://github.com/zephyrproject-rtos/zephyr/pull/37572#discussion_r1102411281

I've disabled it locally.

[tsutterley]

I ran into this issue today and dug into the sphinx html build code. If it is still relevant, you can set the format for the unwanted elements to None. It pops up a (harmless) warning during the doc build, but seems to work.

numfig_format = {
    'code-block': None,
    'figure': 'Figure %s:',
    'table': 'Table %s:',
}

[marc-hb]

FWIW Zephyr disabled numfig a few years ago in:

• https://github.com/zephyrproject-rtos/zephyr/pull/57624

[jdillard]

Ah interesting, here are the docs on numfig_format.

I've noticed big performance hits when there are lots of tables with numfig turned on, I wonder if all numfig types are equal in that regard.

Edit: It seems a lot of tables are slow regardless of numfig