Fix docs/components

[furqan463]

Fixes issue: #1278

Changes proposed in this PR include:

multi-line equations inside $$ delimiter do not render properly. I've replaced them with multiple $$ math blocks.

Checks

• review other pages.

[furqan463]

I could fix equation rendering in components.md, but I've also observed the same issue in calculations.md with multi-line arrays inside $$ delimiter. However, I'm unable to find a solution for that.

[nitbharambe]

There are errors in other files too like LU solver and in calculations.

Initial idea about the ticket was to find out a way which does not require modifying each equation with such issue. Maybe there is a way we can resolve this at sphinx or myst or mathjax side directly.

[furqan463]

There are errors in other files too like LU solver and in calculations.

Initial idea about the ticket was to find out a way which does not require modifying each equation with such issue. Maybe there is a way we can resolve this at sphinx or myst or mathjax side directly.

I had the same intention but couldn't find a way.

[figueroa1395]

I allowed the workflow run and align* seems to render all the equations correctly. @furqan463 Perhaps you can give it a try at the other instances where this is an issue? There is some documentation (don't forget to install Doxygen) to build the docs locally, so you can see whether this works or not and not depend on the CI.

The only remaining thing on the current edited file is to fix formatting, but otherwise it looks good (please double check that I didn't miss any potentially badly rendered equation).

Side note for @nitbharambe: Because align aligns differently, some consecutive equations "look" differently compared to before this broke. I think that's fine, but perhaps we want to align in a specific fashion?

[furqan463]

I allowed the workflow run and align* seems to render all the equations correctly. @furqan463 Perhaps you can give it a try at the other instances where this is an issue? There is some documentation (don't forget to install Doxygen) to build the docs locally, so you can see whether this works or not and not depend on the CI.

The only remaining thing on the current edited file is to fix formatting, but otherwise it looks good (please double check that I didn't miss any potentially badly rendered equation).

Side note for @nitbharambe: Because align aligns differently, some consecutive equations "look" differently compared to before this broke. I think that's fine, but perhaps we want to align in a specific fashion?

@figueroa1395 thanks for the review. I already built the docs locally, and docs are built in PR without CI. I'll try in other instances, my only concern in the first place was that we loose live preview without $$ delimiter. So we've 2 options:

1. Keep $$ delimiter that supports live preview in editor. Trade off: Place all equations separately in $$ blocks without grouping.
2. Use align* delimiter and keep equations grouped together. Trade off: Loos live preview in editor.

[figueroa1395]

Hello @furqan463,

The correct approach should be to use both $$ and align*, that way doc generation renders correctly and the preview still works in VS Code.

Taking the following as an example (this is from the current state in this PR):

\begin{align*}
    & |Z_{\text{series}}| = u_k*z_{\text{base,transformer}} \\
    & \mathrm{Re}(Z_{\text{series}}) = \frac{p_k}{s_n}*z_{\text{base,transformer}} \\
    & \mathrm{Im}(Z_{\text{series}}) = \sqrt{|Z_{\text{series}}|^2-\mathrm{Re}(Z_{\text{series}})^2}
\end{align*}

can be put in between $$s, like:

$$
\begin{align*}
    & |Z_{\text{series}}| = u_k*z_{\text{base,transformer}} \\
    & \mathrm{Re}(Z_{\text{series}}) = \frac{p_k}{s_n}*z_{\text{base,transformer}} \\
    & \mathrm{Im}(Z_{\text{series}}) = \sqrt{|Z_{\text{series}}|^2-\mathrm{Re}(Z_{\text{series}})^2}
\end{align*}
$$

I quickly tried locally and it seems to work without issue.

So basically replacing eqnarray with align*, while keeping all the $$ blocks should work as intended.

[furqan463]

Hello @furqan463,

The correct approach should be to use both $$ and align*, that way doc generation renders correctly and the preview still works in VS Code.

Taking the following as an example (this is from the current state in this PR):

\begin{align*}
    & |Z_{\text{series}}| = u_k*z_{\text{base,transformer}} \\
    & \mathrm{Re}(Z_{\text{series}}) = \frac{p_k}{s_n}*z_{\text{base,transformer}} \\
    & \mathrm{Im}(Z_{\text{series}}) = \sqrt{|Z_{\text{series}}|^2-\mathrm{Re}(Z_{\text{series}})^2}
\end{align*}

can be put in between $$s, like:

$$
\begin{align*}
    & |Z_{\text{series}}| = u_k*z_{\text{base,transformer}} \\
    & \mathrm{Re}(Z_{\text{series}}) = \frac{p_k}{s_n}*z_{\text{base,transformer}} \\
    & \mathrm{Im}(Z_{\text{series}}) = \sqrt{|Z_{\text{series}}|^2-\mathrm{Re}(Z_{\text{series}})^2}
\end{align*}
$$

I quickly tried locally and it seems to work without issue.

So basically replacing eqnarray with align*, while keeping all the $$ blocks should work as intended.

@figueroa1395 I tried locally and also updated 1 equation, line electrical model, here.
It did work with the equation but messed with following text.
Preview works fine but when built, $$ delimiter before /begin{align*} is not treated as math-block delimiter, while $$ delimiter after /end{align*} is treated as start of math block which messes with following text up to next $$ delimiter in the file.

[mgovers]

Since this is a high-prio issue, maybe it's a good idea to first just use \begin{align*} everywhere first to fix the rendering on readthedocs and then do a follow-up PR to try to fix the preview

[figueroa1395]

@furqan463 You are right, my approach was incorrect. My apologies.

After doing some experimentation locally, I didn't see a different quick and easy way to fix this, providing good rendering and VS code preview at the same time, that is not using $$ only for each individual equation, as you suggested initially:

Keep $$ delimiter that supports live preview in editor. Trade off: Place all equations separately in $$ blocks without grouping.

Furthermore, this is a high priority issue, as mentioned by @mgovers, so I suggest to go with that option in all files. Then we have to make sure all equations are rendered correctly. If we later want/need a fancier fix, we can do it as a follow up PR.

In conclusion, let's just use $$ for each individual equation.

C.C. @nitbharambe

[furqan463]

@furqan463 You are right, my approach was incorrect. My apologies.

After doing some experimentation locally, I didn't see a different quick and easy way to fix this, providing good rendering and VS code preview at the same time, that is not using $$ only for each individual equation, as you suggested initially:

Keep $$ delimiter that supports live preview in editor. Trade off: Place all equations separately in $$ blocks without grouping.

Furthermore, this is a high priority issue, as mentioned by @mgovers, so I suggest to go with that option in all files. Then we have to make sure all equations are rendered correctly. If we later want/need a fancier fix, we can do it as a follow up PR.

In conclusion, let's just use $$ for each individual equation.

C.C. @nitbharambe

@figueroa1395 multiple $$ doesn't work everywhere, e.g., vertical matrices in calculations.md. Therefore, I used align*.