Skip to content

Commit 49f9f69

Browse files
ChameppChamepp
committed
fix: handling section titles in the GenerateDocc extension
1 parent 806544c commit 49f9f69

File tree

7 files changed

+82
-105
lines changed

7 files changed

+82
-105
lines changed

‎Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,6 @@ color --fav=<fav> [--second=<second>] [--help]
2727
This is optional.
2828

2929

30-
## Subcommands
31-
3230
## color.help
3331

3432
Show subcommand help information.
@@ -37,6 +35,6 @@ Show subcommand help information.
3735
color help [<subcommands>...]
3836
```
3937

40-
## General
38+
## Arguments
4139

4240
**`subcommands`**

‎Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,6 @@ count-lines [<input-file>] [--prefix=<prefix>] [--verbose] [--help]
3232
*Only count lines with this prefix.*
3333

3434

35-
## Subcommands
36-
3735
## count-lines.help
3836

3937
Show subcommand help information.
@@ -42,6 +40,6 @@ Show subcommand help information.
4240
count-lines help [<subcommands>...]
4341
```
4442

45-
## General
43+
## Arguments
4644

4745
**`subcommands`**

‎Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md

Lines changed: 56 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,6 @@ math [--version] [--help]
2020
*Show help information.*
2121

2222

23-
## Subcommands
24-
2523
## math.add
2624

2725
Print the sum of the values.
@@ -30,16 +28,18 @@ Print the sum of the values.
3028
math add [--hex-output] [<values>...] [--version] [--help]
3129
```
3230

33-
## General
31+
## Arguments
3432

35-
**`--hex-output`**
33+
**`values`**
3634

37-
*Use hexadecimal notation for the result.*
35+
*A group of integers to operate on.*
3836

3937

40-
**`values`**
38+
## Flags
4139

42-
*A group of integers to operate on.*
40+
**`--hex-output`**
41+
42+
*Use hexadecimal notation for the result.*
4343

4444

4545
**`--version`**
@@ -49,24 +49,28 @@ math add [--hex-output] [<values>...] [--version] [--help]
4949

5050
**`--help`**
5151

52-
*Show help information.*## math.multiply
52+
*Show help information.*
53+
54+
## math.multiply
5355

5456
Print the product of the values.
5557

5658
```
5759
math multiply [--hex-output] [<values>...] [--version] [--help]
5860
```
5961

60-
## General
62+
## Arguments
6163

62-
**`--hex-output`**
64+
**`values`**
6365

64-
*Use hexadecimal notation for the result.*
66+
*A group of integers to operate on.*
6567

6668

67-
**`values`**
69+
## Flags
6870

69-
*A group of integers to operate on.*
71+
**`--hex-output`**
72+
73+
*Use hexadecimal notation for the result.*
7074

7175

7276
**`--version`**
@@ -76,15 +80,17 @@ math multiply [--hex-output] [<values>...] [--version] [--help]
7680

7781
**`--help`**
7882

79-
*Show help information.*## math.stats
83+
*Show help information.*
84+
85+
## math.stats
8086

8187
Calculate descriptive statistics.
8288

8389
```
8490
math stats [--version] [--help]
8591
```
8692

87-
## General
93+
## Flags
8894

8995
**`--version`**
9096

@@ -96,8 +102,6 @@ math stats [--version] [--help]
96102
*Show help information.*
97103

98104

99-
## Subcommands
100-
101105
### math.stats.average
102106

103107
Print the average of the values.
@@ -106,56 +110,66 @@ Print the average of the values.
106110
math stats average [--kind=<kind>] [<values>...] [--version] [--help]
107111
```
108112

109-
## General
110-
111-
**`--kind=\<kind\>`**
112-
113-
*The kind of average to provide.*
114-
113+
## Arguments
115114

116115
**`values`**
117116

118117
*A group of floating-point values to operate on.*
119118

120119

120+
## Flags
121+
121122
**`--version`**
122123

123124
*Show the version.*
124125

125126

126127
**`--help`**
127128

128-
*Show help information.*### math.stats.stdev
129+
*Show help information.*
130+
131+
132+
## Options
133+
134+
**`--kind=\<kind\>`**
135+
136+
*The kind of average to provide.*
137+
138+
### math.stats.stdev
129139

130140
Print the standard deviation of the values.
131141

132142
```
133143
math stats stdev [<values>...] [--version] [--help]
134144
```
135145

136-
## General
146+
## Arguments
137147

138148
**`values`**
139149

140150
*A group of floating-point values to operate on.*
141151

142152

153+
## Flags
154+
143155
**`--version`**
144156

145157
*Show the version.*
146158

147159

148160
**`--help`**
149161

150-
*Show help information.*### math.stats.quantiles
162+
*Show help information.*
163+
164+
### math.stats.quantiles
151165

152166
Print the quantiles of the values (TBD).
153167

154168
```
155169
math stats quantiles [<one-of-four>] [<custom-arg>] [<values>...] [--file=<file>] [--directory=<directory>] [--shell=<shell>] [--custom=<custom>] [--version] [--help]
156170
```
157171

158-
## General
172+
## Arguments
159173

160174
**`one-of-four`**
161175

@@ -168,33 +182,39 @@ math stats quantiles [<one-of-four>] [<custom-arg>] [<values>...] [--file=<f
168182
*A group of floating-point values to operate on.*
169183

170184

171-
**`--file=\<file\>`**
185+
## Flags
186+
187+
**`--version`**
188+
189+
*Show the version.*
172190

173191

174-
**`--directory=\<directory\>`**
192+
**`--help`**
175193

194+
*Show help information.*
176195

177-
**`--shell=\<shell\>`**
178196

197+
## Options
179198

180-
**`--custom=\<custom\>`**
199+
**`--file=\<file\>`**
181200

182201

183-
**`--version`**
202+
**`--directory=\<directory\>`**
184203

185-
*Show the version.*
186204

205+
**`--shell=\<shell\>`**
187206

188-
**`--help`**
189207

190-
*Show help information.*## math.help
208+
**`--custom=\<custom\>`**
209+
210+
## math.help
191211

192212
Show subcommand help information.
193213

194214
```
195215
math help [<subcommands>...]
196216
```
197217

198-
## General
218+
## Arguments
199219

200220
**`subcommands`**

‎Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRepeatDoccReference().md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,6 @@ repeat [--count=<count>] [--include-counter] <phrase> [--help]
3232
*The number of times to repeat 'phrase'.*
3333

3434

35-
## Subcommands
36-
3735
## repeat.help
3836

3937
Show subcommand help information.
@@ -42,6 +40,6 @@ Show subcommand help information.
4240
repeat help [<subcommands>...]
4341
```
4442

45-
## General
43+
## Arguments
4644

4745
**`subcommands`**

‎Tests/ArgumentParserGenerateDoccReferenceTests/Snapshots/testRollDoccReference().md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,6 @@ Use this option to override the default value of a six-sided die.
3737
*A seed to use for repeatable random generation.*
3838

3939

40-
## Subcommands
41-
4240
## roll.help
4341

4442
Show subcommand help information.
@@ -47,6 +45,6 @@ Show subcommand help information.
4745
roll help [<subcommands>...]
4846
```
4947

50-
## General
48+
## Arguments
5149

5250
**`subcommands`**

‎Tools/generate-docc-reference/Extensions/ArgumentParser+Markdown.swift

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ extension CommandInfoV0 {
6565
grouping: args.filter {
6666
$0.shouldDisplay
6767
}
68-
) { $0.sectionTitle ?? "General" }
68+
) { self.assignSectionTitle(to: $0) }
6969

7070
// Iterate through the grouped arguments, sorted by section title
7171
// Sorting ensures that the sections appear in a clear, predictable order in the final documentation.
@@ -105,18 +105,8 @@ extension CommandInfoV0 {
105105
}
106106
}
107107

108-
if let subcommands = self.subcommands, !subcommands.isEmpty {
109-
// Add a separate section for subcommands.
110-
// Subcommands are treated differently from regular arguments, so they deserve their own section in the documentation.
111-
// This helps to visually distinguish subcommands from regular arguments, enhancing readability.
112-
result += "## Subcommands\n\n"
113-
114-
// Iterate through each subcommand and convert it to Markdown format
115-
// Each subcommand is processed and added to the documentation under the "Subcommands" section.
116-
// This ensures that users can easily identify and understand the subcommands available for the command.
117-
for subcommand in subcommands {
118-
result += subcommand.toMarkdown(path + [self.commandName])
119-
}
108+
for subcommand in self.subcommands ?? [] {
109+
result += subcommand.toMarkdown(path + [self.commandName]) + "\n\n"
120110
}
121111

122112
// Trim any unnecessary trailing newline that could have been added inadvertently
@@ -134,8 +124,25 @@ extension CommandInfoV0 {
134124

135125
return args.map { $0.usage() }.joined(separator: " ")
136126
}
127+
128+
// Assign a default section title based on the arguments types
129+
func assignSectionTitle(to argument: ArgumentInfoV0) -> String {
130+
if let sectionTitle = argument.sectionTitle {
131+
return sectionTitle
132+
} else {
133+
switch argument.kind {
134+
case .positional:
135+
return "Arguments"
136+
case .option:
137+
return "Options"
138+
case .flag:
139+
return "Flags"
140+
}
141+
}
142+
}
137143
}
138144

145+
139146
extension ArgumentInfoV0 {
140147
public func usage() -> String {
141148
guard self.shouldDisplay else {

0 commit comments

Comments
 (0)