Skip to content

[GenerateDocCReference] Improve filtering and categorization of arguments in documentation with sectionTitle #753

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
wants to merge 21 commits into
base: main
Choose a base branch
from
Open

[GenerateDocCReference] Improve filtering and categorization of arguments in documentation with sectionTitle #753

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
fcc8f21
[GenerateDocCReference] Improve filtering and categorization of argum…
Chamepp Apr 3, 2025
806544c
fix: handle the assignment of the default sectionTitle value in the g…
Chamepp Apr 3, 2025
49f9f69
fix: handling section titles in the GenerateDocc extension
Chamepp Apr 12, 2025
fa6f077
refactor: update markdown headers to align with DocC formatting
Chamepp Apr 20, 2025
fc96cbe
chore: resolve merge conflicts with upstream/main
Chamepp May 8, 2025
ad95073
fix: solve merge conflict
Chamepp Jun 24, 2025
7659317
fix: update argument categorization logic to match ArgumentParser sta…
Chamepp Jul 1, 2025
2748c0d
fix: update snapshots and solve merge conflict
Chamepp Aug 20, 2025
2d5dcbc
Merge branch 'main' into dev
Chamepp Sep 13, 2025
e8a3720
fix: use monospaced code style for arguments, options, and flags in D…
Chamepp Sep 30, 2025
347fbd6
fix: move colon outside of formatted elements in term lists
Chamepp Sep 30, 2025
2bc6684
fix: remove unnecessary italics from argument abstracts
Chamepp Sep 30, 2025
4679e8a
fix: refine argument rendering by removing unnecessary newlines
Chamepp Sep 30, 2025
3ae506e
refactor: use `let` instead of `var` to signal immutability
Chamepp Sep 30, 2025
2be475e
refactor: rename assignSectionTitle(to:) to sectionTitle(for:) for cl…
Chamepp Sep 30, 2025
71d5903
refactor: make sectionTitle(for:) a fileprivate computed property on …
Chamepp Sep 30, 2025
0b84e4c
fix: align default subcommands abstract with CLI --help output
Chamepp Sep 30, 2025
fe07123
test: add custom section titles to math.quantiles for testing documen…
Chamepp Oct 4, 2025
2bc964f
fix: align argument section sorting in documentation generation with …
Chamepp Oct 4, 2025
4580ced
docs: update documentation generation comments for the refined solution
Chamepp Oct 4, 2025
d1890ed
Merge branch 'main' into dev
Chamepp Oct 4, 2025
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
18 changes: 17 additions & 1 deletion Sources/ArgumentParserToolInfo/ToolInfo.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,7 +218,23 @@ public struct ArgumentInfoV0: Codable, Hashable {
self.kind = kind

self.shouldDisplay = shouldDisplay
self.sectionTitle = sectionTitle

// The section title helps categorize arguments
// for better organization in documentation.

// The switch statement checks the kind of argument
// and assigns a default section title related to the argument type
// if the provided one is nil.
switch kind {
case .positional:
self.sectionTitle = sectionTitle ?? "Arguments"

case .option:
self.sectionTitle = sectionTitle ?? "Optionals"

case .flag:
self.sectionTitle = sectionTitle ?? "Flags"
}

self.isOptional = isOptional
self.isRepeating = isRepeating
Expand Down
25 changes: 14 additions & 11 deletions .../ArgumentParserGenerateDoccReferenceTests/Snapshots/testColorDoccReference().md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,22 +6,28 @@
color --fav=<fav> [--second=<second>] [--help]
```

**--fav=\<fav\>:**
## Flags

**`--help`**

*Show help information.*


## Optionals

**`--fav=\<fav\>`**

*Your favorite color.*


**--second=\<second\>:**
**`--second=\<second\>`**

*Your second favorite color.*

This is optional.


**--help:**

*Show help information.*

## Subcommands

## color.help

Expand All @@ -31,9 +37,6 @@ Show subcommand help information.
color help [<subcommands>...]
```

**subcommands:**




## Arguments

**`subcommands`**
29 changes: 17 additions & 12 deletions ...mentParserGenerateDoccReferenceTests/Snapshots/testCountLinesDoccReference().md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,26 +6,34 @@
count-lines [<input-file>] [--prefix=<prefix>] [--verbose] [--help]
```

**input-file:**

*A file to count lines in. If omitted, counts the lines of stdin.*
## Arguments

**`input-file`**

**--prefix=\<prefix\>:**
*A file to count lines in. If omitted, counts the lines of stdin.*

*Only count lines with this prefix.*

## Flags

**--verbose:**
**`--verbose`**

*Include extra information in the output.*


**--help:**
**`--help`**

*Show help information.*


## Optionals

**`--prefix=\<prefix\>`**

*Only count lines with this prefix.*


## Subcommands

## count-lines.help

Show subcommand help information.
Expand All @@ -34,9 +42,6 @@ Show subcommand help information.
count-lines help [<subcommands>...]
```

**subcommands:**




## Arguments

**`subcommands`**
126 changes: 64 additions & 62 deletions ...s/ArgumentParserGenerateDoccReferenceTests/Snapshots/testMathDoccReference().md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,20 @@ A utility for performing maths.
math [--version] [--help]
```

**--version:**
## Flags

**`--version`**

*Show the version.*


**--help:**
**`--help`**

*Show help information.*


## Subcommands

## math.add

Print the sum of the values.
Expand All @@ -26,76 +30,78 @@ Print the sum of the values.
math add [--hex-output] [<values>...] [--version] [--help]
```

**--hex-output:**

*Use hexadecimal notation for the result.*

## Arguments

**values:**
**`values`**

*A group of integers to operate on.*


**--version:**
## Flags

*Show the version.*
**`--hex-output`**

*Use hexadecimal notation for the result.*

**--help:**

*Show help information.*
**`--version`**

*Show the version.*


**`--help`**

## math.multiply
*Show help information.*## math.multiply

Print the product of the values.

```
math multiply [--hex-output] [<values>...] [--version] [--help]
```

**--hex-output:**

*Use hexadecimal notation for the result.*
## Arguments


**values:**
**`values`**

*A group of integers to operate on.*


**--version:**
## Flags

*Show the version.*
**`--hex-output`**

*Use hexadecimal notation for the result.*

**--help:**

*Show help information.*
**`--version`**

*Show the version.*


**`--help`**

## math.stats
*Show help information.*## math.stats

Calculate descriptive statistics.

```
math stats [--version] [--help]
```

**--version:**
## Flags

**`--version`**

*Show the version.*


**--help:**
**`--help`**

*Show help information.*


## Subcommands

### math.stats.average

Print the average of the values.
Expand All @@ -104,109 +110,105 @@ Print the average of the values.
math stats average [--kind=<kind>] [<values>...] [--version] [--help]
```

**--kind=\<kind\>:**

*The kind of average to provide.*
## Arguments


**values:**
**`values`**

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


**--version:**
## Flags

**`--version`**

*Show the version.*


**--help:**
**`--help`**

*Show help information.*


## Optionals

**`--kind=\<kind\>`**

### math.stats.stdev
*The kind of average to provide.*### math.stats.stdev

Print the standard deviation of the values.

```
math stats stdev [<values>...] [--version] [--help]
```

**values:**
## Arguments

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


**--version:**
**`values`**

*Show the version.*
*A group of floating-point values to operate on.*


**--help:**
## Flags

*Show help information.*
**`--version`**

*Show the version.*


**`--help`**

### math.stats.quantiles
*Show help information.*### math.stats.quantiles

Print the quantiles of the values (TBD).

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

**one-of-four:**


**custom-arg:**

## Arguments

**values:**
**`one-of-four`**

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

**`custom-arg`**

**--file=\<file\>:**

**`values`**

**--directory=\<directory\>:**
*A group of floating-point values to operate on.*


**--shell=\<shell\>:**
## Flags

**`--version`**

**--custom=\<custom\>:**
*Show the version.*


**--version:**
**`--help`**

*Show the version.*
*Show help information.*


**--help:**
## Optionals

*Show help information.*
**`--file=\<file\>`**


**`--directory=\<directory\>`**


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


## math.help
**`--custom=\<custom\>`**## math.help

Show subcommand help information.

```
math help [<subcommands>...]
```

**subcommands:**




## Arguments

**`subcommands`**
Loading