Change numbering and referencing in figures, equations, tables, and sections to auto

[paulremo]

Currently, all figures, equations, and tables are numbered and referenced manually. This is cumbersome, error-prone, and will lead to problems when new equations are inserted into the digital handbook in the future. We will therefore switch to automatic numbering and references wherever possible. Therefore, figures, tables, and equations should be inserted and referenced in the document in the following way:

Note

• It shouldn't be necessary to use target headers (i.e., (target_header)= ) for any auto-numbered items.
• The number used in the name or label field will not be displayed to the user and is only important for internal reference.
• References inside titles (or captions) are not permitted!

Figures

• Insertion

  ```{figure} ../../pictures/figure4_1.png
  ---
  width: 600px
  name: misc_fig_4_1
  ---
  Failure rate as a function of time for typical mechanical components.

• Reference {numref}`misc_fig_4_1`

Tables

• Insertion (standard tables)

  
  ```{list-table}
  :header-rows: 1
  :name: misc_table_4_8

• • Col1
  • Col2
• • Row1 under Col1
  • Row1 under Col2
• • Row2 under Col1
  • Row2 under Col2

• Insertion (interactive tables)

  
  ```{list-table} Some interactive table title
  :class: interactive-table
  :name: misc_table_4_8

• Reference {numref}`misc_table_4_8`

Equations

As it is not possible to automatically number admonition tiles, I suggest not to use equations inside admonitions extensively. Instead, the equation admonition class should be used to highlight certain important equations and then give them a meaningful title.

• Insertion (equation outside admonition)

  ```{math}
  :label: misc_eq_14
  w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}

• Insertion (equation inside admonition)

  ````{admonition} Equation title
  :class: equation
  ``
  ``  
  ```{math}
  :label: misc_eq_14
  R_{S}(t) = R_{A}(t) * R_{B}(t)

• Reference Eq. {eq}`misc_eq_14`

Sections/Chapters

Apparently, this only works until the H2 tag (##). The H3 tag (###) does not produce an automatically numbered reference.

• Insertion

  (misc_section)=
  ## Standard model for generic miscellaneous items

• Reference {numref}`misc_section`

[csxADS]

Changed all figure references (77 in 16 files)

[csxADS]

````{admonition} {eq}`misc_eq_14`
:class: equation
``
``  
```{math}
:label: misc_eq_14
R_{S}(t) = R_{A}(t) * R_{B}(t)

doesn't work (breaks the admonition) @paulremo

[paulremo]

Yes! You're right - I actually mentioned this right below the Equation section. You can't put references in titles/captions - we'll have to find a different way to do this 😄.

How about the following (to also summarize successive equations in one admonition):

````{admonition} Equation description
:class: equation
``
``  
```{math}
:label: misc_eq_14
R_{S}(t) = R_{A}(t) * R_{B}(t)

:label: misc_eq_15
R_{S}(t) = R_{A}(t) * R_{B}(t)

:label: misc_eq_16
R_{S}(t) = R_{A}(t) * R_{B}(t)

Can you test it?

[csxADS]

You mean removing the reference in the title and only put "Equation" instead ?

[paulremo]

Yes, either "Equation" or some meaningful two-word description of what the equation shows. The number should be shown automatically inside brackets next to the equation.

[paulremo]

@csxADS please also number section and chapter references with numref (see the updated main comment above)

[csxADS]

Done for tables miscellaneous, it will be very long for titles

[paulremo]

It will save a lot of time down the line 😄.

As I mentioned in the main note above, this will not work for H3 sections (###). For those sections, leave the current manual reference, but remove the number, i.e., change:

[Section 4.4.1](misc_4_4_1)

to anything that matches the sentence

as discussed in the [standard model section](misc_4_4_1)

But avoid using relative references like next section or previous section.

[csxADS]

Seems that it does not work for section titles

(Reliability Models for miscellaneous items)=

Reliability Models for miscellaneous items

appears like

(Reliability Models for miscellaneous items)= 5.4.4. Reliability Models for miscellaneous items

Seems that there is an issue with labeling titles, trying to get it

[csxADS]

Found the issue

[csxADS]

Done commit 27b52b99bfdce5534d8eba33756a6110b471a39f

[paulremo]

Thanks for that! It looks like you changed the hierarchy of certain sections - is that correct? If so, we should discuss this at today's meeting.

[csxADS]

There was just titles using too much # so that the build did not take it into account. That was a mistake during the copy of texts so I just removed useless #

[paulremo]

Okay, great! Did you take care of this in all chapters or just Miscellaneous?

[csxADS]

No but shouldn't we wait for the final decision to be taken on this subject ?

[paulremo]

@csxADS is this issue addressed for the Miscellaneous chapter?

[csxADS]

I'll have a check this morning and I keep you updated as soon as possible !

[csxADS]

Everything seems to be ok for miscellaneous @paulremo

[paulremo]

Thanks! I'll close this issue then.