book: generate command pages (#835)

.github/codecov.yml

@@ -12,7 +12,7 @@ coverage:
 ignore:
   - "tests"
   - "hls"
-  - "book-lints"
+  - "book-gen"
 
 # Make comments less noisy
 comment:

Cargo.toml

@@ -2,7 +2,7 @@
 members = [
     "bin",
 
-    "book-lints",
+    "book-gen",
 
     "hls",
 

bin/src/commands/build.rs

@@ -9,9 +9,27 @@ use crate::{
 use super::global_modules;
 
 #[derive(clap::Parser)]
+#[command(verbatim_doc_comment)]
 /// Build the project for final testing
 ///
-/// Build your project in release mode for testing, without signing for full release.
+/// `hemtt build` will build your mod into `.hemttout/build`.
+/// It will binarize all applicable files, and will not
+/// create folder links like [`hemtt dev`](./dev.md).
+///
+/// It is intended to be used for testing your mod locally before release.
+///
+/// ## Configuration
+///
+/// **.hemtt/project.toml**
+///
+/// ```toml
+/// [hemtt.build]
+/// optional_mod_folders = false # Default: true
+/// ```
+///
+/// ### `optional_mod_folders`
+///
+/// By default, `hemtt build` will create separate mods for each optional mod folder.
 pub struct Command {
     #[clap(flatten)]
     build: BuildArgs,
@@ -28,9 +46,15 @@ pub struct Command {
 pub struct BuildArgs {
     #[arg(long, action = clap::ArgAction::SetTrue)]
     /// Do not binarize the project
+    ///
+    /// They will be copied directly into the PBO. `config.cpp`, `*.rvmat`, `*.ext` will still be rapified.
+    /// This can be configured per addon in [`addon.toml`](../configuration/addon#binarize).
     no_bin: bool,
     #[arg(long, action = clap::ArgAction::SetTrue)]
     /// Do not rapify (cpp, rvmat)
+    ///
+    /// They will be copied directly into the PBO.
+    /// This can be configured per addon in [`addon.toml`](../configuration/addon#rapify).
     no_rap: bool,
 }
 

bin/src/commands/check.rs

@@ -8,7 +8,11 @@ use crate::{
 };
 
 #[derive(clap::Parser)]
-/// Check the project for errors
+/// Checks the project for errors
+///
+/// `hemtt check` is the quickest way to check your project for errors.
+/// All the same checks are run as [`hemtt dev`](./dev.md), but it will not
+/// write files to disk, saving time and resources.
 pub struct Command {
     #[clap(flatten)]
     global: crate::GlobalArgs,

bin/src/commands/dev.rs

@@ -12,10 +12,27 @@ use crate::{
 use super::JustArgs;
 
 #[derive(clap::Parser)]
+#[command(verbatim_doc_comment)]
 /// Build the project for development
 ///
-/// Build your project for local development and testing.
-/// It is built without binarization of .p3d and .rtm files.
+/// `hemtt dev` is designed to help your development workflows.
+/// It will build your mod into `.hemttout/dev`, with links back
+/// to the original addon folders. This allows you to use
+/// file-patching with optional mods for easy development.
+///
+/// ## Configuration
+///
+/// **.hemtt/project.toml**
+///
+/// ```toml
+/// [hemtt.dev]
+/// exclude = ["addons/unused"]
+/// ```
+///
+/// ### exclude
+///
+/// A list of addons to exclude from the development build.
+/// Includes from excluded addons can be used, but they will not be built or linked.
 pub struct Command {
     #[clap(flatten)]
     dev: DevArgs,
@@ -30,17 +47,28 @@ pub struct Command {
 #[derive(clap::Args)]
 #[allow(clippy::module_name_repetitions)]
 pub struct DevArgs {
-    #[arg(long, short, action = clap::ArgAction::SetTrue)]
+    #[arg(long, short, action = clap::ArgAction::SetTrue, verbatim_doc_comment)]
     /// Use BI's binarize on supported files
+    ///
+    /// By default, `hemtt dev` will not binarize any files, but rather pack them as-is.
+    /// Binarization is often not needed for development.
     binarize: bool,
-    #[arg(long = "optional", short, action = clap::ArgAction::Append)]
+    #[arg(long, short, action = clap::ArgAction::Append, verbatim_doc_comment)]
     /// Include an optional addon folder
-    optionals: Vec<String>,
-    #[arg(long, short = 'O', action = clap::ArgAction::SetTrue)]
+    ///
+    /// This can be used multiple times to include multiple optional addons.
+    ///
+    /// ```bash
+    /// hemtt dev -o caramel -o chocolate
+    /// ```
+    optional: Vec<String>,
+    #[arg(long, short = 'O', action = clap::ArgAction::SetTrue, conflicts_with = "optional", verbatim_doc_comment)]
     /// Include all optional addon folders
     all_optionals: bool,
-    #[arg(long, action = clap::ArgAction::SetTrue)]
+    #[arg(long, action = clap::ArgAction::SetTrue, verbatim_doc_comment)]
     /// Do not rapify (cpp, rvmat)
+    ///
+    /// They will be copied directly into the PBO, not .bin version is created.
     no_rap: bool,
 }
 
@@ -66,7 +94,7 @@ pub fn context(
 ) -> Result<Executor, Error> {
     let all_optionals = dev.all_optionals;
     let optionals = dev
-        .optionals
+        .optional
         .iter()
         .map(std::string::String::as_str)
         .collect::<Vec<_>>();

bin/src/commands/launch/mod.rs

@@ -24,10 +24,156 @@ use crate::{
 };
 
 #[derive(clap::Parser)]
+#[command(verbatim_doc_comment)]
 /// Test your project
 ///
-/// Builds your project in dev mode and launches Arma 3 with
-/// file patching enabled, loading your mod and any workshop mods.
+/// `hemtt launch` is used to build and launch a dev version of your mod.
+/// It will run the [`hemtt dev`](dev.md) command internally after a
+/// few checks, options are passed to the `dev` command.
+///
+/// You can chain multiple configurations together, and they will be
+/// overlayed from left to right. Any arrays will be concatenated,
+/// and any duplicate keys will be overridden. With the below configuration,
+/// `hemtt launch default vn ace` would launch with all three configurations.
+/// Note that `default` must be specified when specifying additional
+/// configurations, `default` is only implied when no configurations are specified.
+///
+/// ## Configuration
+///
+/// `hemtt launch` requires the [`mainprefix`](../configuration/index.md#main-prefix) option to be set.
+///
+/// Launch configurations can be stored in either `.hemtt/project.toml` under `hemtt.launch`,
+/// or in a separate file under `.hemtt/launch.toml`. The latter is useful for keeping
+/// your main configuration file clean. When using `launch.toml`,
+/// the `hemtt.launch` key is not required.
+///
+/// **.hemtt/project.toml**
+///
+/// ```toml
+/// mainprefix = "z"
+///
+/// # Launched with `hemtt launch`
+/// [hemtt.launch.default]
+/// workshop = [
+///     "450814997", # CBA_A3's Workshop ID
+/// ]
+/// presets = [
+///     "main", # .html presets from .hemtt/presets/
+/// ]
+/// dlc = [
+///     "Western Sahara",
+/// ]
+/// optionals = [
+///     "caramel",
+/// ]
+/// mission = "test.VR" # Mission to launch directly into the editor with
+/// parameters = [
+///     "-skipIntro",           # These parameters are passed to the Arma 3 executable
+///     "-noSplash",            # They do not need to be added to your list
+///     "-showScriptErrors",    # You can add additional parameters here
+///     "-debug",
+///     "-filePatching",
+/// ]
+/// executable = "arma3" # Default: "arma3_x64"
+/// file_patching = false # Default: true
+/// binarize = true # Default: false
+/// rapify = false # Default: true
+///
+/// # Launched with `hemtt launch vn`
+/// [hemtt.launch.vn]
+/// extends = "default"
+/// dlc = [
+///     "S.O.G. Prairie Fire",
+/// ]
+///
+/// # Launched with `hemtt launch ace`
+/// [hemtt.launch.ace]
+/// extends = "default"
+/// workshop = [
+///     "463939057", # ACE3's Workshop ID
+/// ]
+/// ```
+///
+/// **.hemtt/launch.toml**
+///
+/// ```toml
+/// [default]
+/// workshop = [
+///     "450814997", # CBA_A3's Workshop ID
+/// ]
+///
+/// [vn]
+/// extends = "default"
+/// dlc = [
+///     "S.O.G. Prairie Fire",
+/// ]
+/// ```
+///
+/// ### extends
+///
+/// The name of another configuration to extend. This will merge all
+/// arrays with the base configuration, and override any duplicate keys.
+///
+/// ### workshop
+///
+/// A list of workshop IDs to launch with your mod. These are not
+/// subscribed to, and will need to be manually subscribed to in Steam.
+///
+/// ### presets
+///
+/// A list of `.html` presets to launch with your mod.
+/// Exported from the Arma 3 Launcher, and kept in `.hemtt/presets/`.
+///
+/// ### dlc
+///
+/// A list of DLCs to launch with your mod. The fullname or short-code can be used.
+///
+/// Currently supported DLCs:
+///
+/// | Full Name           | Short Code |
+/// | ------------------- | ---------- |
+/// | Contact             | contact    |
+/// | Global Mobilization | gm         |
+/// | S.O.G. Prairie Fire | vn         |
+/// | CSLA Iron Curtain   | csla       |
+/// | Western Sahara      | ws         |
+/// | Spearhead 1944      | spe        |
+/// | Reaction Forces     | rf         |
+///
+/// ### optionals
+///
+/// A list of optional addon folders to launch with your mod.
+///
+/// ### mission
+///
+/// The mission to launch directly into the editor with. This can be specified
+/// as either the name of a folder in `.hemtt/missions/`
+/// (e.g., `test.VR` would launch `.hemtt/missions/test.VR/mission.sqm`)
+/// or the relative (to the project root) path to a `mission.sqm`
+/// file or a folder containing it.
+///
+/// ### parameters
+///
+/// A list of [Startup Parameters](https://community.bistudio.com/wiki/Arma_3:_Startup_Parameters) to pass to the Arma 3 executable.
+///
+/// ### executable
+///
+/// The name of the Arma 3 executable to launch.
+/// This is usually `arma3` or `arma3_x64`.
+/// Do not include the `.exe` extension, it will be added automatically on Windows.
+/// Only paths relative to the Arma 3 directory are supported.
+///
+/// ### `file_patching`
+///
+/// Whether to launch Arma 3 with `-filePatching`. Equivalent to `--no-filepatching` or `-F`.
+///
+/// ### binarize
+///
+/// Whether to use BI's binarize on supported files. Equivalent to `--binarize`.
+///
+/// ### rapify
+///
+/// Provides the ability to disable rapify for the launch command. Equivalent to `--no-rap`.
 pub struct Command {
     #[clap(flatten)]
     launch: LaunchArgs,
@@ -46,19 +192,43 @@ pub struct Command {
 #[allow(clippy::module_name_repetitions)]
 pub struct LaunchArgs {
     #[arg(action = clap::ArgAction::Append)]
-    /// Launches with the specified `[hemtt.launch.<config>]` configurations
+    /// Launches with the specified configurations
+    ///
+    /// Configured in either:
+    /// - `.hemtt/project.toml` under `hemtt.launch`
+    /// - `.hemtt/launch.toml`
     config: Option<Vec<String>>,
-    #[arg(long, short)]
+    #[arg(long, short, verbatim_doc_comment)]
     /// Executable to launch, defaults to `arma3_x64.exe`
+    ///
+    /// Overrides the `executable` option in the configuration file.
+    ///
+    /// Can be either a relative path to the Arma 3 directory, or an absolute path.
+    ///
+    /// ```bash
+    /// -e arma3profiling_x64 # Relative to the Arma 3 directory
+    /// -e "C:\Program Files\Steam\steamapps\common\Arma 3\arma3_x64.exe" # Absolute path
+    /// ```
     executable: Option<String>,
-    #[arg(raw = true)]
+    #[arg(raw = true, verbatim_doc_comment)]
     /// Passthrough additional arguments to Arma 3
+    ///
+    /// Any options after `--` will be passed to the Arma 3 executable.
+    /// This is useful for passing additional [Startup Parameters](https://community.bistudio.com/wiki/Arma_3:_Startup_Parameters).
+    ///
+    /// ```bash
+    /// hemtt launch -- -world=empty -window
+    /// ```
     passthrough: Option<Vec<String>>,
     #[arg(long, short)]
     /// Launches multiple instances of the game
+    ///
+    /// If unspecified, it will default to 1.
     instances: Option<u8>,
     #[arg(long = "quick", short = 'Q')]
     /// Skips the build step, launching the last built version
+    ///
+    /// Will throw an error if no build has been made, or no symlink exists.
     no_build: bool,
     #[arg(long = "no-filepatching", short = 'F')]
     /// Disables file patching