[Docs] Add sequence diagrams to timeout strategy

[peter-csala]

Pull Request

The issue or feature being addressed

• When I was working on the Polly-Samples migration I've added several mermaid diagrams (for example: 1, 2 to visualize the relationships).
• I thought it might make sense to further enhance the Polly documentation by adding sequence diagrams to it

Details on the issue fix or feature implementation

• Added a happy path and unhappy path sequence diagram to the timeout strategy

Preview

• Live

Confirm the following

• I started this PR by branching from the head of the default branch
• I have targeted the PR to merge into the default branch
• I have included unit tests for the issue/feature
• I have successfully run a local build

[martintmk]

Two notes:

• Please check whether this is supported by DocFx since that one is used for our docs: https://www.pollydocs.org/strategies/timeout.html
• I would move these under the Defaults section under Diagram or Diagram flow since these diagrams are for more advanced readers and w don't want to obscure the usage samples.

[codecov]

Codecov Report

All modified lines are covered by tests ✅

Comparison is base (862690e) 84.63% compared to head (7c795eb) 84.63%.
Report is 1 commits behind head on main.

❗ Current head 7c795eb differs from pull request most recent head 1b224a1. Consider uploading reports for the commit 1b224a1 to get more accurate results

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1699   +/-   ##
=======================================
  Coverage   84.63%   84.63%           
=======================================
  Files         306      306           
  Lines        6819     6819           
  Branches     1045     1045           
=======================================
  Hits         5771     5771           
  Misses        839      839           
  Partials      209      209           

Flag	Coverage Δ
linux	84.63% <ø> (?)
macos	84.63% <ø> (ø)
windows	84.63% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[martincostello]

I'm not sure whether the pollydocs.org will do the same dynamic rendering as github.

Yeah, that was my first thought too.

[peter-csala]

* Please check whether this is supported by DocFx since that one is used for our docs: https://www.pollydocs.org/strategies/timeout.html

I've found these comments:

• Addin for diagrams support dotnet/docfx#2292 (comment)
• Addin for diagrams support dotnet/docfx#2292 (comment)

and this plugin: https://github.com/dpvreony/docfx-mermaidjs

* I would move these under the `Defaults` section under `Diagram` or `Diagram flow` since these diagrams are for more advanced readers and w don't want to obscure the usage samples.

• Done

[martintmk]

* Please check whether this is supported by DocFx since that one is used for our docs: https://www.pollydocs.org/strategies/timeout.html

I've found these comments:

• Addin for diagrams support dotnet/docfx#2292 (comment)
• Addin for diagrams support dotnet/docfx#2292 (comment)

and this plugin: https://github.com/dpvreony/docfx-mermaidjs

* I would move these under the `Defaults` section under `Diagram` or `Diagram flow` since these diagrams are for more advanced readers and w don't want to obscure the usage samples.

• Done

Maybe just include these as images under docs/media ?

[martincostello]

Maybe just include these as images under docs/media ?

That's probably the least friction way. We can still leave the diagrams in as HTML comments to make regenerating them easy.

[peter-csala]

Maybe just include these as images under docs/media ?

On pollydocs you can switch back and forth between light and dark themes.

If we could add mermaid support then the diagrams would align with the selected theme as well.

If we stick with the image then which theme do we prefer?

[martincostello]

I would go with "normal" black on white if we don't go with a plugin.

[peter-csala]

@martincostello , @martintmk Do you have any idea why the pictures are not shown on pollydocs?

• ❌ Pollydocs: https://www.pollydocs.org/strategies/timeout.html#diagrams
• 👍 Github: https://github.com/App-vNext/Polly/blob/main/docs/strategies/timeout.md#diagrams

[martincostello]

My guess would be the paths are slightly different when the docfx website is built.

I suggest running it locally and seeing what path it outputs and then tweaking the file to have the right path for pollydocs even if it breaks GitHub.