Skip to content

Commit 1eef26f

Browse files
natemcmasterclaude
natemcmaster
and
claude
committed
docs: upgrade docfx to 2.78.4 with modern template
- Upgrade docfx from 2.56.6 to 2.78.4 as a local .NET tool - Switch to modern template with dark mode support - Update generate.ps1 to use dotnet tool instead of manual NuGet download - Migrate index.md from Bootstrap 3 panels to Bootstrap 5 cards - Update api/index.md with current version (5.0) and .NET 8.0 target - Add theme/public/main.js with icon links and Google Analytics - Remove old theme partials (now handled by modern template) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent ced643d commit 1eef26f

12 files changed

Lines changed: 177 additions & 107 deletions

File tree

‎.config/dotnet-tools.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,12 @@
77
"commands": [
88
"dotnet-format"
99
]
10+
},
11+
"docfx": {
12+
"version": "2.78.4",
13+
"commands": [
14+
"docfx"
15+
]
1016
}
1117
}
1218
}

‎.github/workflows/ci.yml‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,12 @@ jobs:
3535
steps:
3636
- uses: actions/checkout@v6
3737
- name: Setup .NET
38-
uses: actions/setup-dotnet@v4
38+
uses: actions/setup-dotnet@v5
3939
with:
4040
dotnet-version: |
41-
8.0.x
42-
9.0.x
41+
8.x
42+
9.x
43+
10.x
4344
- name: Run build script
4445
id: build_script
4546
run: ./build.ps1 -ci

‎.github/workflows/docs.yml‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,16 +17,17 @@ on:
1717

1818
jobs:
1919
generate_docs:
20-
runs-on: windows-latest
20+
runs-on: ubuntu-latest
2121

2222
steps:
2323
- uses: actions/checkout@v6
2424
- name: Setup .NET
25-
uses: actions/setup-dotnet@v3
25+
uses: actions/setup-dotnet@v5
2626
with:
2727
dotnet-version: |
28-
6.0.x
29-
8.0.x
28+
8.x
29+
9.x
30+
10.x
3031
- name: Run docs generation
3132
run: ./docs/generate.ps1
3233

‎docs/api/index.md‎

Lines changed: 20 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4,28 +4,32 @@ uid: latest_api_ref
44
API Reference
55
=============
66

7-
**Version 3.0**
7+
**Version 5.0** (Current)
88

9-
McMaster.Extensions.CommandLineUtils supports two target frameworks.
9+
## Target Framework
1010

11-
- .NET Standard 2.0
12-
- .NET Framework 4.5
11+
McMaster.Extensions.CommandLineUtils targets **.NET 8.0**.
1312

14-
The API is almost identical between all of the frameworks.
13+
For older framework support, use previous versions:
14+
- Version 4.x: .NET 6.0+
15+
- Version 3.x: .NET Standard 2.0, .NET Framework 4.5
16+
17+
## Key Types
1518

1619
The main entry point for most command line applications is [CommandLineApplication](xref:McMaster.Extensions.CommandLineUtils.CommandLineApplication).
1720

18-
For apps built using attributes, these are the most common attributes used:
21+
For apps built using the attribute API, these are the most common attributes:
1922

20-
- [OptionAttribute](xref:McMaster.Extensions.CommandLineUtils.OptionAttribute)
21-
- [ArgumentAttribute](xref:McMaster.Extensions.CommandLineUtils.ArgumentAttribute)
22-
- [CommandAttribute](xref:McMaster.Extensions.CommandLineUtils.CommandAttribute)
23-
- [SubcommandAttribute](xref:McMaster.Extensions.CommandLineUtils.SubcommandAttribute)
24-
- [HelpOptionAttribute](xref:McMaster.Extensions.CommandLineUtils.HelpOptionAttribute)
23+
- [CommandAttribute](xref:McMaster.Extensions.CommandLineUtils.CommandAttribute) - Marks a class as a command
24+
- [OptionAttribute](xref:McMaster.Extensions.CommandLineUtils.OptionAttribute) - Defines command-line options
25+
- [ArgumentAttribute](xref:McMaster.Extensions.CommandLineUtils.ArgumentAttribute) - Defines positional arguments
26+
- [SubcommandAttribute](xref:McMaster.Extensions.CommandLineUtils.SubcommandAttribute) - Defines subcommands
27+
- [HelpOptionAttribute](xref:McMaster.Extensions.CommandLineUtils.HelpOptionAttribute) - Adds --help option
28+
- [VersionOptionAttribute](xref:McMaster.Extensions.CommandLineUtils.VersionOptionAttribute) - Adds --version option
2529

26-
Other commonly used types include
30+
## Utilities
2731

28-
- [DotNetExe](xref:McMaster.Extensions.CommandLineUtils.DotNetExe)
29-
- [Prompt](xref:McMaster.Extensions.CommandLineUtils.Prompt)
30-
- [ArgumentEscaper](xref:McMaster.Extensions.CommandLineUtils.ArgumentEscaper)
31-
- [IConsole](xref:McMaster.Extensions.CommandLineUtils.IConsole)
32+
- [Prompt](xref:McMaster.Extensions.CommandLineUtils.Prompt) - Interactive prompts for user input
33+
- [DotNetExe](xref:McMaster.Extensions.CommandLineUtils.DotNetExe) - Locate the dotnet executable
34+
- [ArgumentEscaper](xref:McMaster.Extensions.CommandLineUtils.ArgumentEscaper) - Escape arguments for shell execution
35+
- [IConsole](xref:McMaster.Extensions.CommandLineUtils.IConsole) - Abstraction for console I/O (useful for testing)

‎docs/docfx.json‎

Lines changed: 73 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -17,19 +17,80 @@
1717
"dest": "obj/unstable/api/",
1818
"filter": "filterConfig.yml",
1919
"properties": {
20-
"TargetFramework": "netstandard2.0"
20+
"TargetFramework": "net8.0"
2121
}
2222
}
2323
],
2424
"build": {
2525
"content": [
26-
{ "version": "unstable", "files": ["**/*.yml", "**/*.md"], "src": "obj/unstable", "dest": "unstable" },
27-
{ "version": "v3.0", "files": ["**/*.yml", "**/*.md"], "exclude": [ "v2.*/", "obj/", "**.meta", "README.md", "filterConfig.yml" ] },
28-
{ "version": "v2.6", "files": ["**/*.yml", "**/*.md"], "src": "v2.6", "dest": "v2.6" },
29-
{ "version": "v2.5", "files": ["**/*.yml", "**/*.md"], "src": "v2.5", "dest": "v2.5" },
30-
{ "version": "v2.4", "files": ["**/*.yml", "**/*.md"], "src": "v2.4", "dest": "v2.4" },
31-
{ "version": "v2.3", "files": ["**/*.yml", "**/*.md"], "src": "v2.3", "dest": "v2.3" },
32-
{ "version": "v2.2", "files": ["**/*.yml", "**/*.md"], "src": "v2.2", "dest": "v2.2" }
26+
{
27+
"version": "unstable",
28+
"files": [
29+
"**/*.yml",
30+
"**/*.md"
31+
],
32+
"src": "obj/unstable",
33+
"dest": "unstable"
34+
},
35+
{
36+
"version": "v3.0",
37+
"files": [
38+
"**/*.yml",
39+
"**/*.md"
40+
],
41+
"exclude": [
42+
"v2.*/",
43+
"obj/",
44+
"**.meta",
45+
"README.md",
46+
"filterConfig.yml"
47+
]
48+
},
49+
{
50+
"version": "v2.6",
51+
"files": [
52+
"**/*.yml",
53+
"**/*.md"
54+
],
55+
"src": "v2.6",
56+
"dest": "v2.6"
57+
},
58+
{
59+
"version": "v2.5",
60+
"files": [
61+
"**/*.yml",
62+
"**/*.md"
63+
],
64+
"src": "v2.5",
65+
"dest": "v2.5"
66+
},
67+
{
68+
"version": "v2.4",
69+
"files": [
70+
"**/*.yml",
71+
"**/*.md"
72+
],
73+
"src": "v2.4",
74+
"dest": "v2.4"
75+
},
76+
{
77+
"version": "v2.3",
78+
"files": [
79+
"**/*.yml",
80+
"**/*.md"
81+
],
82+
"src": "v2.3",
83+
"dest": "v2.3"
84+
},
85+
{
86+
"version": "v2.2",
87+
"files": [
88+
"**/*.yml",
89+
"**/*.md"
90+
],
91+
"src": "v2.2",
92+
"dest": "v2.2"
93+
}
3394
],
3495
"resource": [
3596
{
@@ -49,6 +110,7 @@
49110
"dest": "../.build/docs/gh-pages",
50111
"template": [
51112
"default",
113+
"modern",
52114
"./theme"
53115
],
54116
"postProcessors": [
@@ -59,8 +121,10 @@
59121
"cleanupCacheHistory": false,
60122
"disableGitFeatures": false,
61123
"globalMetadata": {
124+
"_appName": "CommandLineUtils",
62125
"_appFooter": " ",
63-
"_appLogoPath": "logo.png"
126+
"_appLogoPath": "logo.png",
127+
"_enableSearch": true
64128
}
65129
}
66130
}

‎docs/generate.ps1‎

Lines changed: 3 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,11 @@
11
#!/usr/bin/env pwsh
22
param(
33
[switch]$Serve,
4-
[switch]$Install,
54
[switch]$NoBuild
65
)
76
$ErrorActionPreference = 'Stop'
87
Set-StrictMode -Version 2
98

10-
if (-not (Test-Path variable:\IsCoreCLR)) {
11-
$IsWindows = $true
12-
}
13-
149
Import-Module -Force -Scope Local "$PSScriptRoot/../src/common.psm1"
1510

1611
Push-Location "$PSScriptRoot/../"
@@ -31,19 +26,8 @@ try {
3126
exec git worktree add $targetDir gh-pages 2>&1 | out-null
3227
}
3328

34-
$docfxVersion = '2.56.6'
35-
$docfxRoot = "$buildRoot/packages/docfx.console/$docfxVersion"
36-
$docfx = "$docfxRoot/tools/docfx.exe"
37-
if (-not (Test-Path $docfx)) {
38-
mkdir -p $docfxRoot -ErrorAction Ignore | Out-Null
39-
$temp = (New-TemporaryFile).FullName + ".zip"
40-
Invoke-WebRequest "https://www.nuget.org/api/v2/package/docfx.console/$docfxVersion" -OutFile $temp
41-
Expand-Archive $temp -DestinationPath $docfxRoot
42-
Remove-Item $temp
43-
if ($Install) {
44-
exit 1
45-
}
46-
}
29+
# Restore docfx as a local .NET tool
30+
exec dotnet tool restore
4731

4832
Push-Location $targetDir
4933
exec git reset --hard
@@ -60,12 +44,7 @@ try {
6044
$arguments += '--serve'
6145
}
6246

63-
if ($IsWindows) {
64-
exec $docfx docs/docfx.json @arguments
65-
}
66-
else {
67-
exec mono $docfx docs/docfx.json @arguments
68-
}
47+
exec dotnet tool run docfx docs/docfx.json @arguments
6948
}
7049
finally {
7150
Push-Location $targetDir

‎docs/index.md‎

Lines changed: 34 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -5,57 +5,60 @@ CommandLineUtils
55
The primary goal of the library is to assist with parsing command line arguments and executing the correct
66
commands related to those arguments. The library also provides various other utilities such as input helpers.
77

8-
<div class="row">
9-
<div class="col-md-4">
10-
<div class="panel panel-default" style="min-height: 140px">
11-
<div class="panel-body">
12-
<p><strong><a href="docs/intro.md">Documentation</a></strong></p>
13-
<p>Tutorials to create your first .NET command line application, and docs on how to use the library.</p>
8+
<div class="row row-cols-1 row-cols-md-2 row-cols-lg-3 g-4">
9+
<div class="col">
10+
<div class="card h-100">
11+
<div class="card-body">
12+
<h5 class="card-title"><a href="docs/intro.md">Documentation</a></h5>
13+
<p class="card-text">Tutorials to create your first .NET command line application, and docs on how to use the library.</p>
1414
</div>
1515
</div>
1616
</div>
17-
<div class="col-md-4">
18-
<div class="panel panel-default" style="min-height: 140px">
19-
<div class="panel-body">
20-
<p><strong> [API Reference](xref:latest_api_ref) </strong></p>
21-
<p>Read the API documentation for this library.</p>
17+
<div class="col">
18+
<div class="card h-100">
19+
<div class="card-body">
20+
<h5 class="card-title"><a href="api/index.md">API Reference</a></h5>
21+
<p class="card-text">Read the API documentation for this library.</p>
2222
</div>
2323
</div>
2424
</div>
25-
<div class="col-md-4">
26-
<div class="panel panel-default" style="min-height: 140px">
27-
<div class="panel-body">
28-
<p><strong><a href="https://github.com/natemcmaster/CommandLineUtils/tree/main/docs/samples/">Samples</a></strong></p>
29-
<p>View sample projects which use CommandLineUtils.</p>
25+
<div class="col">
26+
<div class="card h-100">
27+
<div class="card-body">
28+
<h5 class="card-title"><a href="https://github.com/natemcmaster/CommandLineUtils/tree/main/docs/samples/">Samples</a></h5>
29+
<p class="card-text">View sample projects which use CommandLineUtils.</p>
3030
</div>
3131
</div>
3232
</div>
33-
<div class="col-md-4">
34-
<div class="panel panel-default" style="min-height: 140px">
35-
<div class="panel-body">
36-
<p><strong><a href="https://github.com/natemcmaster/CommandLineUtils">Source Code and Issue Tracker</a></strong></p>
37-
<p>The project is open-source on GitHub.</p>
33+
<div class="col">
34+
<div class="card h-100">
35+
<div class="card-body">
36+
<h5 class="card-title"><a href="https://github.com/natemcmaster/CommandLineUtils">Source Code</a></h5>
37+
<p class="card-text">The project is open-source on GitHub.</p>
3838
</div>
3939
</div>
4040
</div>
41-
<div class="col-md-4">
42-
<div class="panel panel-default" style="min-height: 140px">
43-
<div class="panel-body">
44-
<p><strong><a href="https://nuget.org/packages/McMaster.Extensions.CommandLineUtils">NuGet</a></strong></p>
45-
<p>See the latest releases of this library as a NuGet package.</p>
41+
<div class="col">
42+
<div class="card h-100">
43+
<div class="card-body">
44+
<h5 class="card-title"><a href="https://nuget.org/packages/McMaster.Extensions.CommandLineUtils">NuGet</a></h5>
45+
<p class="card-text">See the latest releases of this library as a NuGet package.</p>
4646
</div>
4747
</div>
4848
</div>
49-
<div class="col-md-4">
50-
<div class="panel panel-default" style="min-height: 140px">
51-
<div class="panel-body">
52-
<p><strong><a href="https://github.com/natemcmaster/CommandLineUtils/tree/main/CHANGELOG.md">Version history</a></strong></p>
53-
<p>Read notes about fixes and enhancements per release.</p>
49+
<div class="col">
50+
<div class="card h-100">
51+
<div class="card-body">
52+
<h5 class="card-title"><a href="https://github.com/natemcmaster/CommandLineUtils/blob/main/CHANGELOG.md">Changelog</a></h5>
53+
<p class="card-text">Read notes about fixes and enhancements per release.</p>
5454
</div>
5555
</div>
5656
</div>
5757
</div>
5858

59+
---
60+
61+
## Quick Example
5962

6063
Using this library, you can write a command line application without doing the heavy lifting to support automated help text generation,
6164
masking input for passwords, parsing argument syntax, validation, etc.

‎docs/theme/partials/logo.tmpl.partial‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎docs/theme/partials/scripts.tmpl.partial‎

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎docs/theme/public/main.css‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
/* Custom styles for CommandLineUtils documentation */
2+
3+
/* Adjust logo size in navbar */
4+
.navbar-brand img {
5+
height: 40px;
6+
}

0 commit comments

Comments
 (0)