Allow configuring the separator used in numbering equations

[thfanning]

Subject: Sphinx configuration: math_numsep

Feature or Bugfix

• Feature

Purpose

• Allow users to configure the final separator used when numbering math elements.

Detail

• When numbering equations with math_numfig and numfig_secnum_depth > 0, section number are included in the equation number. For example, Eq. 1.2.3 is the third equation in section 1.2.
• A new Sphinx configuration option math_numsep allows users to select a different separator between the section number and the equation number.
• For example, math_numsep='-' will result in numbering such as Eq. 1.2-3.
• This helps visually distinguish equation number 1.2-3 from section number 1.2.3.
• Minimal code changes.
• Test case included for HTML. LaTeX does its own numbering.

Relates

• None

[AA-Turner]

I'm hesistant about adding new configuration values. What is the value proposition here, is it a broader request?

A

[thfanning]

I'm hesistant about adding new configuration values. What is the value proposition here, is it a broader request?

Understandable given the large number of existing configuration options. However, there are only 3 options for math (and math_number_all is of questionable utility). What we propose, math_numsep, has symmetry with math_numfig and only takes effect if numfig_secnum_depth is positive.

We maintain very technical code documentation that is thousands of pages long and contains over 4000 equations across 16 chapters. Our convention (for decades) is to use Chapter.Section-Equation. Although this is something that can readily be done in LaTeX, Sphinx is limited in equation number formatting in HTML (other than the math_eqref_format which has no bearing on numbering).

This feature would bring parity with LaTeX generation.

Thanks.

[AA-Turner]

Probably makes sense to unconditionally use math_numsep, and have a sensible default. If a user sets math_numsep to None or '', perhaps issue a warning/error, or silently use '.'.

Suggested change

	'math_numsep': _Opt(None, 'env', frozenset((str,))),
	'math_numsep': _Opt('.', 'env', frozenset((str,))),

[thfanning]

I've implemented the requested default separator, added to the CHANGES, and updated the documentation.

[AA-Turner]

Please can you also add an entry to CHANGES and documentation in doc/usage/configuration?

A

[AA-Turner]

Thanks Thomas!

A