Skip to content
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.

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

refactor: Use clap-markdown to generate CommandLineHelp.md #30

Merged
merged 3 commits into from
Dec 17, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
5 changes: 3 additions & 2 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ exclude = [

[features]
default = []
cli = ["clap"]
cli = ["clap", "clap-markdown"]

#===================
# Targets
Expand All @@ -36,7 +36,8 @@ required-features = ["cli"]
#===================

[dependencies]
clap = { version = "3.0.4", features = ["derive"], optional = true }
clap = { version = "4.0.29", features = ["derive"], optional = true }
clap-markdown = { version = "0.1.0", optional = true }

[target.'cfg(target_os = "macos")'.dependencies]
core-foundation = "0.9.2"
Expand Down
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,3 +104,6 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for more information.

See [**Development.md**](./docs/Development.md) for instructions on how to
perform common development tasks when contributing to this project.

See [*Maintenance.md*](./docs/Maintenance.md) for instructions on how to
maintain this project.
103 changes: 45 additions & 58 deletions docs/CommandLineHelp.md
Original file line number Diff line number Diff line change
@@ -1,95 +1,82 @@
# `wolfram-app-discovery` help text
# Command-Line Help for `wolfram-app-discovery`

This file contains the `--help` text for the `wolfram-app-discovery` command-line
executable.
This document contains the help content for the `wolfram-app-discovery` command-line program.

*This file is regenerated periodically. See [Maintenance.md](./Maintenance.md) for details.*
**Command Overview:**

<!-- BEGIN AUTOGENERATED CONTENT -->
* [`wolfram-app-discovery`↴](#wolfram-app-discovery)
* [`wolfram-app-discovery default`↴](#wolfram-app-discovery-default)
* [`wolfram-app-discovery list`↴](#wolfram-app-discovery-list)
* [`wolfram-app-discovery inspect`↴](#wolfram-app-discovery-inspect)

### `wolfram-app-discovery --help`
## `wolfram-app-discovery`

```text
wolfram-app-discovery
Discovery local installations of the Wolfram Language and Wolfram products
Find local installations of the Wolfram Language and Wolfram apps

USAGE:
wolfram-app-discovery <SUBCOMMAND>
**Usage:** `wolfram-app-discovery <COMMAND>`

OPTIONS:
-h, --help Print help information
###### **Subcommands:**

SUBCOMMANDS:
default Print the default Wolfram app
list List all locatable Wolfram apps
inspect Print information about a specified Wolfram application
help Print this message or the help of the given subcommand(s)
* `default` — Print the default Wolfram app
* `list` — List all locatable Wolfram apps
* `inspect` — Print information about a specified Wolfram application

```

#### `wolfram-app-discovery default --help`

```text
wolfram-app-discovery-default
## `wolfram-app-discovery default`

Print the default Wolfram app.

This method uses [`WolframApp::try_default()`] to locate the default app.

USAGE:
wolfram-app-discovery default [OPTIONS]
**Usage:** `wolfram-app-discovery default [OPTIONS]`

OPTIONS:
--app-type <APP_TYPES>
Wolfram application types to include
###### **Options:**

[possible values: mathematica, engine, desktop, player, player-pro, finance-platform,
programming-lab, wolfram-alpha-notebook-edition]
* `--app-type` — Wolfram application types to include

--debug
Whether to print application information in the verbose Debug format
*Possible Values:* `mathematica`, `engine`, `desktop`, `player`, `player-pro`, `finance-platform`, `programming-lab`, `wolfram-alpha-notebook-edition`

-h, --help
Print help information
* `--debug` — Whether to print application information in the verbose Debug format

```


#### `wolfram-app-discovery list --help`
## `wolfram-app-discovery list`

```text
wolfram-app-discovery-list
List all locatable Wolfram apps

USAGE:
wolfram-app-discovery list [OPTIONS]
**Usage:** `wolfram-app-discovery list [OPTIONS]`

###### **Options:**

* `--app-type` — Wolfram application types to include

*Possible Values:* `mathematica`, `engine`, `desktop`, `player`, `player-pro`, `finance-platform`, `programming-lab`, `wolfram-alpha-notebook-edition`

OPTIONS:
--app-type <APP_TYPES> Wolfram application types to include [possible values:
mathematica, engine, desktop, player, player-pro, finance-
platform, programming-lab, wolfram-alpha-notebook-edition]
--debug Whether to print application information in the verbose Debug
format
-h, --help Print help information
* `--debug` — Whether to print application information in the verbose Debug format

```


#### `wolfram-app-discovery inspect --help`
## `wolfram-app-discovery inspect`

```text
wolfram-app-discovery-inspect
Print information about a specified Wolfram application

USAGE:
wolfram-app-discovery inspect [OPTIONS] <APP_DIR>
**Usage:** `wolfram-app-discovery inspect [OPTIONS] <APP_DIR>`

###### **Arguments:**

* `<APP_DIR>`

###### **Options:**

* `--debug` — Whether to print application information in the verbose Debug format

ARGS:
<APP_DIR>

OPTIONS:
--debug Whether to print application information in the verbose Debug format
-h, --help Print help information

```
<hr/>

<small><i>
This document was generated automatically by
<a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
</i></small>

2 changes: 1 addition & 1 deletion docs/Development.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ beyond checking only one or the other.

```shell
$ cargo build --target x86_64-apple-darwin
$ cargo build --target -apple-darwin
$ cargo build --target aarch64-apple-darwin
```

**Build for Windows:**
Expand Down
26 changes: 8 additions & 18 deletions docs/Maintenance.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,24 +12,14 @@ The [`CommandLineHelp.md`](./CommandLineHelp.md) file contains the `--help` text
markdown file makes the functionality of `wolfram-app-discovery` more discoverable, and
serves as an informal "cheet sheet" / reference material. Creation of the contents of
`CommandLineHelp.md` is partially automated by the undocumented `print-all-help`
subcommand:
subcommand.

```shell
$ wolfram-app-discovery print-all-help`
```

To update `CommandLineHelp.md`, perform the following steps:

1. Begin by deleting everything in `CommandLineHelp.md` after the line:

<!-- BEGIN AUTOGENERATED CONTENT -->
To update [`CommandLineHelp.md`](./CommandLineHelp.md), execute the following
command:

2. Run `cargo build --features cli` to ensure `wolfram-app-discovery` is up to date.

3. Run `./target/debug/wolfram-app-discovery print-all-help --markdown | pbcopy` to print
the help text formatted into readable markdown sections. On macOS, the `| pbcopy` will
automatically copy this content to the clipboard.

4. Paste the markdown help text at the end of `CommandLineHelp.md`
```
$ cargo run --features=cli -- print-all-help --markdown > docs/CommandLineHelp.md
```

5. Commit the updates with a commit message like: `chore: regenerate CommandLineHelp.md`
If the content has changed, commit it with a commit message like:
`chore: Regenerate CommandLineHelp.md`.
16 changes: 9 additions & 7 deletions src/bin/wolfram-app-discovery/main.rs
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
mod print_all_help;

use std::path::PathBuf;

use clap::Parser;
Expand Down Expand Up @@ -32,17 +30,17 @@ enum Command {
debug: Debug,
},
// For generating `docs/CommandLineHelp.md`.
#[clap(setting(clap::AppSettings::Hidden))]
#[clap(hide = true)]
PrintAllHelp {
#[clap(long)]
#[arg(long, required = true)]
markdown: bool,
},
}

#[derive(Parser, Debug)]
struct AppOpts {
/// Wolfram application types to include.
#[clap(long = "app-type", arg_enum)]
#[arg(long = "app-type", value_enum)]
app_types: Vec<WolframAppType>,

#[clap(flatten)]
Expand All @@ -52,7 +50,7 @@ struct AppOpts {
#[derive(Parser, Debug)]
struct Debug {
/// Whether to print application information in the verbose Debug format.
#[clap(long)]
#[arg(long)]
debug: bool,
}

Expand All @@ -68,7 +66,11 @@ fn main() -> Result<(), wad::Error> {
Command::List(opts) => list(opts),
Command::Inspect { app_dir, debug } => inspect(app_dir, debug.debug),
Command::PrintAllHelp { markdown } => {
print_all_help::print_all_help(markdown);
// This is a required argument for the time being.
assert!(markdown);

let () = clap_markdown::print_help_markdown::<Args>();

Ok(())
},
}
Expand Down
82 changes: 0 additions & 82 deletions src/bin/wolfram-app-discovery/print_all_help.rs

This file was deleted.

2 changes: 1 addition & 1 deletion src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ pub struct WolframApp {
/// Standalone application type distributed by Wolfram Research.
#[derive(Debug, Clone, PartialEq, Hash)]
#[non_exhaustive]
#[cfg_attr(feature = "cli", derive(clap::ArgEnum))]
#[cfg_attr(feature = "cli", derive(clap::ValueEnum))]
pub enum WolframAppType {
/// [Wolfram Mathematica](https://www.wolfram.com/mathematica/)
Mathematica,
Expand Down