[build.numbering]

Section, figure, table, code-block and equation numbering, shared by every builder.

Which items carry a number, how numbers are written, and the text a numbered reference (:numref:, :eq:) prints. Each builder also has a numbering table of its own, [build.html.numbering] and [build.pdf.numbering], which inherits every key it does not set from this one and wins on every key it does — so the PDF can be numbered where the site is not. ubc check and the editor report their findings against this shared table; ubc build html and ubc build pdf each report a numbered reference against the numbers that build prints.

Guide: Numbering.

build.numbering.code
Type:
table

Code-block caption numbering.

build.numbering.code.caption
Type:
string

The label printed before the caption.

Defaults to "Fig. {number}" (tables "Table {number}", code "Listing {number}"). Must contain {number} (or %s). Replaces the caption half of Sphinx’s numfig_format.

build.numbering.code.enabled
Type:
boolean

Number the captions of this kind.

Off by default. Only an item with a caption (a table: a title) is numbered; one with the class unnumbered is not, and takes no number. Replaces Sphinx’s numfig (which switches all three kinds at once).

build.numbering.code.reference
Type:
string

The :numref: text for an item of this kind.

Defaults to the same text as the caption label’s default. {name} prints the caption text. Must contain {number} (or %s). Replaces the reference half of Sphinx’s numfig_format.

build.numbering.code.within
Type:
integer or string

What prefixes the number, and where its count restarts.

Defaults to 1: the number of the enclosing section, truncated to that many levels, prefixes the item’s own count, which restarts for every prefix (Fig. 2.3). 0 is one count over the whole project (Fig. 17); "document" restarts on every page with no prefix. A prefix needs numbered sections: where no section is numbered, every item shares the one unprefixed count. Replaces Sphinx’s numfig_secnum_depth.

build.numbering.enabled
Type:
boolean

Print numbers at all.

On by default. false prints no number anywhere in the output — headings, captions and equations — and a numbered reference prints the target’s title instead.

build.numbering.equation
Type:
table

Equation numbering.

build.numbering.equation.all
Type:
boolean

Number unlabelled display equations too.

Off by default. Replaces Sphinx’s math_number_all.

build.numbering.equation.enabled
Type:
boolean

Number labelled display equations.

On by default, as in Sphinx: a math block with a :label: (else a :name:, or a MyST (label)) prints (N) and :eq: refers to it. No other equation prints a number (unless all is set): an unstarred equation or align environment the author writes draws none, as with Sphinx’s MathJax, though an explicit \tag{…} is still drawn.

build.numbering.equation.reference
Type:
string

The :eq: text.

Defaults to "({number})". Must contain {number} (or %s); an equation has no {name}. Replaces Sphinx’s math_eqref_format.

build.numbering.equation.separator
Type:
string

The text between an equation number’s section prefix and its own count.

Defaults to "." ((2.4)). Replaces Sphinx’s math_numsep.

build.numbering.equation.within
Type:
integer or string

What prefixes an equation number, and where its count restarts.

The same values as a figure’s within. Defaults to the figure table’s within when figure numbering is on, and to "document" (restart on every page) when it is off — Sphinx’s math_numfig behaviour.

build.numbering.figure
Type:
table

Figure caption numbering.

Takes the same keys as build.numbering.code.

build.numbering.sections
Type:
table

Section numbering.

build.numbering.sections.appendix
Type:
table

Appendix lettering, for ubc build pdf’s [build.pdf] appendices.

build.numbering.sections.appendix.pattern
Type:
string

The pattern appendix numbers are written in.

Defaults to "A.1": the appendix itself is lettered (A, B …) and its sections, figures and tables carry the letter (A.1, Fig. A.1). Only ubc build pdf has appendices ([build.pdf] appendices); the HTML site prints no appendix numbers. Applies only when sections are numbered.

build.numbering.sections.appendix.reference
Type:
string

The :numref: text for an appendix itself (level 1).

Defaults to "Appendix {number}". A section inside an appendix uses sections.reference.

build.numbering.sections.depth
Type:
integer

How many levels are numbered.

0 (the default) numbers as deep as each :numbered: N says (with from = "toctree"), or every level (with from = "all"). A number above zero numbers levels 1 to N only, whatever :numbered: says. Level 1 is the titles of the documents a numbered toctree lists.

build.numbering.sections.from
Type:
string

Which documents’ sections are numbered.

"toctree" (the default) numbers the documents a :numbered: toctree lists, their sections, and the documents their own toctrees list, as Sphinx does; the document holding the numbered toctree is not numbered itself. "all" numbers as if every toctree of the root document said :numbered:. "none" numbers no section and ignores :numbered:.

Values:

  • "toctree": The documents a :numbered: toctree lists, as Sphinx numbers them.

  • "all": As if every toctree of the root document said :numbered:.

  • "none": No section numbers; :numbered: is ignored.

build.numbering.sections.pattern
Type:
string

How a section number is written.

Defaults to "1.1". Write one counter style per level — 1 arabic, a / A letters, i / I roman numerals — separated by the text printed between levels; the last style repeats for deeper levels. "I.A.1" prints II.B.3, "1.a" prints 2.b.c. Letters continue past z as aa, ab …. Figure, table, code and equation numbers write their section prefix in these styles and their own count in arabic.

build.numbering.sections.reference
Type:
string or array of strings

The :numref: text for a section.

Defaults to "Section {number}". A list gives one template per level, the last repeating: ["Chapter {number}", "Section {number}"]. {name} prints the section title. Replaces Sphinx’s numfig_format['section'].

Forms:

  • a string: Text printed for a numbered item: {number} (or %s) is the number and {name} the caption or title; {{ and }} print a brace.

Each entry: Text printed for a numbered item: {number} (or %s) is the number and {name} the caption or title; {{ and }} print a brace.

build.numbering.table
Type:
table

Table caption numbering.

Takes the same keys as build.numbering.code.