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 5 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
5 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
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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should not be part of ToolInfo. Instead the consumer of tool info can choose how to interpret the missing title. (the consumers of toolinfo are/will be: generate–docc-reference, generate-manual, generate-shell-completion, help-generation, usage-generation)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your feedback dear Rauhul. I handled the logic in the generate-docc command.

// 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