Skip to content

Add new example VCR scripts and corresponding SVG assets for CLI documentation #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
phil-scott-78 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add new example VCR scripts and corresponding SVG assets for CLI documentation #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-customizing-help-usage.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Set DisableCursor true
Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 80
Set Rows 20
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.CustomizingHelpText.Demo.RunAsync(System.String[])"

Exec "./example --help"
Wait
Sleep 1s
Screenshot "Spectre.Docs/Content/assets/cli-customizing-help-usage.svg"
14 changes: 14 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-defining-arguments-help.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Set DisableCursor true
Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 80
Set Rows 20
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.DefiningCommandsAndArguments.Demo.RunAsync(System.String[])"

Exec "./example --help"
Wait
Sleep 1s
Screenshot "Spectre.Docs/Content/assets/cli-defining-arguments-help.svg"
17 changes: 17 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-di-step1.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
Set DisableCursor true
Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 70
Set Rows 10
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.DependencyInjection.NoDI.Demo.RunAsync(System.String[])"

Exec "./example Alice"
Wait
Sleep 1s
Exec "./example Alice --formal"
Wait
Sleep 1s
Screenshot "Spectre.Docs/Content/assets/cli-di-step1.svg"
14 changes: 14 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-di-step2.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Set DisableCursor true
Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 70
Set Rows 8
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.DependencyInjection.WithService.Demo.RunAsync(System.String[])"

Exec "./example Alice"
Wait
Sleep 1s
Screenshot "Spectre.Docs/Content/assets/cli-di-step2.svg"
20 changes: 20 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-di-step3.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
Set DisableCursor true
Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 70
Set Rows 12
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.DependencyInjection.DIComplete.Demo.RunAsync(System.String[])"

Exec "./example Alice"
Wait
Sleep 1s
Exec "./example Alice --style Formal"
Wait
Sleep 1s
Exec "./example Alice --style Enthusiastic"
Wait
Sleep 1s
Screenshot "Spectre.Docs/Content/assets/cli-di-step3.svg"
14 changes: 14 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-dictionary-lookup-output.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Set DisableCursor true
Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 80
Set Rows 14
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.DictionaryOptions.Demo.RunAsync(System.String[])"

Exec "./example --lookup env=dev --lookup env=staging --lookup env=prod --lookup region=us"
Wait
Sleep 1s
Screenshot "Spectre.Docs/Content/assets/cli-dictionary-lookup-output.svg"
14 changes: 14 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-flag-arguments-help.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Set DisableCursor true
Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 80
Set Rows 20
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.FlagArguments.Demo.RunAsync(System.String[])"

Exec "./example --help"
Wait
Sleep 1s
Screenshot "Spectre.Docs/Content/assets/cli-flag-arguments-help.svg"
14 changes: 14 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-logging-step1.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Set DisableCursor true
Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 70
Set Rows 12
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.Logging.NoLogging.Demo.RunAsync(System.String[])"

Exec "./example myfile.txt"
Wait
Sleep 1s
Screenshot "Spectre.Docs/Content/assets/cli-logging-step1.svg"
14 changes: 14 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-logging-step2.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Set DisableCursor true
Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 70
Set Rows 14
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.Logging.WithLogging.Demo.RunAsync(System.String[])"

Exec "./example myfile.txt"
Wait
Sleep 1s
Screenshot "Spectre.Docs/Content/assets/cli-logging-step2.svg"
20 changes: 20 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-logging-step3.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
Set DisableCursor true
Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 70
Set Rows 20
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.Logging.LoggingComplete.Demo.RunAsync(System.String[])"

Exec "./example myfile.txt"
Wait
Sleep 1s
Exec "./example myfile.txt --logLevel Debug"
Wait
Sleep 1s
Exec "./example myfile.txt --logLevel Warning"
Wait
Sleep 1s
Screenshot "Spectre.Docs/Content/assets/cli-logging-step3.svg"
21 changes: 21 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-multi-command-step1.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
Output "Spectre.Docs/Content/assets/cli-multi-command-step1.svg"

Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 70
Set Rows 12
Set EndBuffer 5s
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.MultiCommand.Step1.Demo.RunAsync(System.String[])"

Type "./example add Newtonsoft.Json"
Sleep 400ms
Enter
Sleep 1s

Type "./example list"
Sleep 400ms
Enter
Sleep 3s
26 changes: 26 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-multi-command-step2.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
Output "Spectre.Docs/Content/assets/cli-multi-command-step2.svg"

Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 70
Set Rows 16
Set EndBuffer 5s
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.MultiCommand.Step2.Demo.RunAsync(System.String[])"

Type "./example add package Newtonsoft.Json"
Sleep 400ms
Enter
Sleep 1s

Type "./example add reference ../MyLib/MyLib.csproj"
Sleep 400ms
Enter
Sleep 1s

Type "./example add --help"
Sleep 400ms
Enter
Sleep 5s
21 changes: 21 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-multi-command-step3.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
Output "Spectre.Docs/Content/assets/cli-multi-command-step3.svg"

Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 70
Set Rows 18
Set EndBuffer 5s
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.MultiCommand.Finished.Demo.RunAsync(System.String[])"

Type "./example add package Serilog --version 3.0.0 --verbose"
Sleep 400ms
Enter
Sleep 1s

Type "./example list --verbose"
Sleep 400ms
Enter
Sleep 3s
14 changes: 14 additions & 0 deletions Spectre.Docs.Cli.Examples/VCR/cli-required-options-help.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
Set DisableCursor true
Set Shell "pwsh"
Set FontSize 22
Set Theme "one dark"
Set TransparentBackground "true"
Set Cols 80
Set Rows 20
Set WorkingDirectory "Spectre.Docs.Cli.Examples/bin/Debug/net10.0"
Env SPECTRE_APP "M:Spectre.Docs.Cli.Examples.DemoApps.MakingOptionsRequired.Demo.RunAsync(System.String[])"

Exec "./example --help"
Wait
Sleep 1s
Screenshot "Spectre.Docs/Content/assets/cli-required-options-help.svg"
2 changes: 0 additions & 2 deletions Spectre.Docs.Examples/VCR/creating-custom-renderables-tutorial.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
Output "anim.svg"

Set DisableCursor true
Set FontSize 22
Set Theme "one dark"
Expand Down
1 change: 0 additions & 1 deletion Spectre.Docs.Examples/VCR/rule.tape
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
Output "Spectre.Docs/Content/assets/rule.svg"
Output "Spectre.Docs/Content/assets/rule.gif"
Set DisableCursor true
Set FontSize 22
Set Theme "one dark"
Expand Down
86 changes: 73 additions & 13 deletions Spectre.Docs/Components/Shared/Screenshot.razor
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,16 @@
? $"width: 100%; aspect-ratio: {_aspectRatio};"
: "width: 100%;";
}
<img fetchpriority="high" src="@Src" alt="@Alt" style="@imgStyle" />
@if (_svgContent != null)
{
<div style="@imgStyle" role="img" aria-label="@Alt">
@((MarkupString)_svgContent)
</div>
}
else
{
<img fetchpriority="high" src="@Src" alt="@Alt" style="@imgStyle" />
}
</div>
</div>
</div>
Expand All @@ -26,22 +35,36 @@
[Parameter]
public string Alt { get; set; } = "Screenshot";

[Parameter]
public bool Embed { get; set; }

private string? _aspectRatio;
private string? _svgContent;

protected override void OnParametersSet()
{
_aspectRatio = null;
_svgContent = null;

// Only process SVG files from /assets/
if (!string.IsNullOrEmpty(Src) &&
Src.StartsWith("/assets/", StringComparison.OrdinalIgnoreCase) &&
Src.EndsWith(".svg", StringComparison.OrdinalIgnoreCase))
{
_aspectRatio = TryGetAspectRatio(Src);
var contentPath = ResolvePath(Src);
if (contentPath != null && File.Exists(contentPath))
{
if (Embed)
{
_svgContent = TryReadAndPrepareSvg(contentPath);
}

_aspectRatio = TryParseAspectRatio(_svgContent, contentPath);
}
}
}

private string? TryGetAspectRatio(string srcUrl)
private string? ResolvePath(string srcUrl)
{
try
{
Expand All @@ -54,19 +77,56 @@
relativePath = relativePath.Replace('/', Path.DirectorySeparatorChar);
}

var contentPath = Path.Combine(Environment.ContentRootPath, "Content", relativePath);
return Path.Combine(Environment.ContentRootPath, "Content", relativePath);
}
catch
{
return null;
}
}

if (!File.Exists(contentPath))
private static string? TryReadAndPrepareSvg(string contentPath)
{
try
{
var svg = File.ReadAllText(contentPath);

// Inject width="100%" so inline SVG scales to fill container.
// viewBox handles aspect ratio preservation automatically.
svg = System.Text.RegularExpressions.Regex.Replace(
svg,
@"<svg\b",
@"<svg width=""100%"" ",
System.Text.RegularExpressions.RegexOptions.None,
TimeSpan.FromSeconds(1));

return svg;
}
catch
{
return null;
}
}

private string? TryParseAspectRatio(string? fullContent, string contentPath)
{
try
{
string content;
if (fullContent != null)
{
return null;
// Reuse already-read content from embed mode
content = fullContent.Length > 1024 ? fullContent[..1024] : fullContent;
}
else
{
// Read only first 1KB - viewBox should be in opening <svg> tag
using var stream = new FileStream(contentPath, FileMode.Open, FileAccess.Read, FileShare.Read);
using var reader = new StreamReader(stream);
var buffer = new char[1024];
var charsRead = reader.Read(buffer, 0, buffer.Length);
content = new string(buffer, 0, charsRead);
}

// Read only first 1KB - viewBox should be in opening <svg> tag
using var stream = new FileStream(contentPath, FileMode.Open, FileAccess.Read, FileShare.Read);
using var reader = new StreamReader(stream);
var buffer = new char[1024];
var charsRead = reader.Read(buffer, 0, buffer.Length);
var content = new string(buffer, 0, charsRead);

// Parse viewBox="minX minY width height" - captures the last two numbers (width and height)
var match = System.Text.RegularExpressions.Regex.Match(
Expand Down
1 change: 1 addition & 0 deletions Spectre.Docs/Content/assets/cli-customizing-help-usage.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions Spectre.Docs/Content/assets/cli-defining-arguments-help.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions Spectre.Docs/Content/assets/cli-di-step1.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
1 change: 1 addition & 0 deletions Spectre.Docs/Content/assets/cli-di-step2.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading