fix: README

Author: DenisGorbachev

README.md

@@ -21,7 +21,7 @@ let valid = url!("https://www.rust-lang.org/");
 let invalid = url!("foo");
 ```
 
-   [__cargo_doc2readme_dependencies_info]: ggGkYW0BYXSEGyMws-dKI-LpG9swkVXG-rikGwSuJGhB0NVbG974QPrPJF6XYXKEG4AA8JRKwJB9G9olxhSTKUcIG1sf0boPKowfG1HA4Nxt7NpkYWSBg2l1cmwtbWFjcm9mMC4xLjExaXVybF9tYWNybw
+   [__cargo_doc2readme_dependencies_info]: ggGkYW0BYXSEGyMws-dKI-LpG9swkVXG-rikGwSuJGhB0NVbG974QPrPJF6XYXKEG4AA8JRKwJB9G9olxhSTKUcIG1sf0boPKowfG1HA4Nxt7NpkYWSBg2l1cmwtbWFjcm9mMC4xLjEyaXVybF9tYWNybw
  [__link0]: https://docs.rs/url-macro/latest/url_macro/?search=url
 
 ## Installation

README.ts

@@ -3,53 +3,76 @@
 import * as zx from "npm:zx"
 import { z, ZodSchema, ZodTypeDef } from "https://deno.land/x/[email protected]/mod.ts"
 import { assert, assertEquals } from "jsr:@std/[email protected]"
+import { toSnakeCase } from "jsr:@std/[email protected]"
 
 const CargoTomlSchema = z.object({
-  package: z.object({
-    name: z.string().min(1),
-    description: z.string().min(1),
-    repository: z.string().url().min(1),
-    metadata: z.object({
-      details: z.object({
-        title: z.string().min(1).optional(),
-        tagline: z.string().optional(),
-        summary: z.string().optional(),
-        peers: z.array(z.string()).default([]).describe("Packages that should be installed alongside this package")
-      }).default({}),
-    }).default({}),
-  }),
+    package: z.object({
+        name: z.string().min(1),
+        description: z.string().min(1),
+        repository: z.string().url().min(1),
+        metadata: z.object({
+            details: z.object({
+                title: z.string().min(1).optional(),
+                tagline: z.string().optional(),
+                summary: z.string().optional(),
+                peers: z.array(z.string()).default([]).describe("Packages that should be installed alongside this package"),
+            }).default({}),
+        }).default({}),
+    }),
 })
 
 type CargoToml = z.infer<typeof CargoTomlSchema>
 
 const CargoMetadataSchema = z.object({
-  packages: z.array(z.object({
-    name: z.string(),
-    targets: z.array(z.object({
-      name: z.string(),
+    packages: z.array(z.object({
+        name: z.string(),
+        source: z.string().nullable(),
+        targets: z.array(z.object({
+            name: z.string(),
+            kind: z.array(z.string()),
+        })),
     })),
-  })),
 })
 
 type CargoMetadata = z.infer<typeof CargoMetadataSchema>
 
 const RepoSchema = z.object({
-  url: z.string().url(),
+    url: z.string().url(),
 })
 
 type Repo = z.infer<typeof RepoSchema>
 
 const BadgeSchema = z.object({
-  name: z.string().min(1),
-  image: z.string().url(),
-  url: z.string().url(),
+    name: z.string().min(1),
+    image: z.string().url(),
+    url: z.string().url(),
 })
 
 type Badge = z.infer<typeof BadgeSchema>
 
-const badge = (name: string, image: string, url: string): Badge => BadgeSchema.parse({name, url, image})
+const badge = (name: string, image: string, url: string): Badge => BadgeSchema.parse({ name, url, image })
+
+const SectionSchema = z.object({
+    title: z.string().min(1),
+    body: z.string(),
+})
+
+type Section = z.infer<typeof SectionSchema>
+
+const section = (title: string, body: string): Section => SectionSchema.parse({ title, body })
+
+const pushSection = (sections: Section[], title: string, body: string) => sections.push(section(title, body))
+
+// Nested sections not supported
+const renderSection = ({ title, body }: Section) => `## ${title}\n\n${body}`
 
-const dirname = import.meta.dirname;
+const renderNonEmptySections = (sections: Section[]) => sections.filter((s) => s.body).map(renderSection).join("\n\n")
+
+const stub = <T>(message = "Implement me"): T => {
+    throw new Error(message)
+}
+
+const dirname = import.meta.dirname
 if (!dirname) throw new Error("Cannot determine the current script dirname")
 
 const $ = zx.$({ cwd: dirname })
@@ -58,23 +81,30 @@ const $ = zx.$({ cwd: dirname })
 const parse = <Output = any, Def extends ZodTypeDef = ZodTypeDef, Input = Output>(schema: ZodSchema<Output, Def, Input>, input: zx.ProcessOutput) => schema.parse(JSON.parse(input.stdout))
 
 const theCargoToml: CargoToml = parse(CargoTomlSchema, await $`yj -t < Cargo.toml`)
-const { package: { name, description, metadata: { details } } }= theCargoToml
+const { package: { name, description, metadata: { details } } } = theCargoToml
 const title = details.title || description
 const peers = details.peers
+const _libTargetName = toSnakeCase(name)
 const theCargoMetadata: CargoMetadata = parse(CargoMetadataSchema, await $`cargo metadata --format-version 1`)
 const thePackageMetadata = theCargoMetadata.packages.find((p) => p.name == name)
 assert(thePackageMetadata, "Could not find package metadata")
-const target = thePackageMetadata.targets[0]
-assert(target, "Could not find package first target")
+const primaryTarget = thePackageMetadata.targets[0]
+assert(primaryTarget, "Could not find package primary target")
+const primaryBinTarget = thePackageMetadata.targets.find((t) => t.name == name && t.kind.includes("bin"))
+// NOTE: primaryTarget may be equal to primaryBinTarget
+const primaryTargets = [primaryTarget, primaryBinTarget]
+const secondaryTargets = thePackageMetadata.targets.filter((t) => !primaryTargets.includes(t))
+const secondaryBinTargets = secondaryTargets.filter((t) => t.kind.includes("bin"))
 const docsUrl = `https://docs.rs/${name}`
 
 // launch multiple promises in parallel
-const doc2ReadmePromise = $`cargo doc2readme --template README.jl --target-name ${target.name} --out -`
+const doc2ReadmePromise = $`cargo doc2readme --template README.jl --target-name ${primaryTarget.name} --out -`
 const ghRepoPromise = $`gh repo view --json url`
-const docsUrlPromise = fetch(docsUrl, {method:"HEAD"})
+const docsUrlPromise = fetch(docsUrl, { method: "HEAD" })
+const helpPromise = primaryBinTarget ? $`cargo run --quiet --bin ${primaryBinTarget.name} -- --help` : undefined
 
 const doc = await doc2ReadmePromise
-const docStr = doc.stdout.trim();
+const docStr = doc.stdout.trim()
 
 const repo: Repo = parse(RepoSchema, await ghRepoPromise)
 assertEquals(repo.url, theCargoToml.package.repository)
@@ -83,46 +113,65 @@ const docsUrlHead = await docsUrlPromise
 const docsUrlIs200 = docsUrlHead.status === 200
 
 const badges: Badge[] = [
-  badge("Build",  `${repo.url}/actions/workflows/ci.yml/badge.svg`, repo.url)
+    badge("Build", `${repo.url}/actions/workflows/ci.yml/badge.svg`, repo.url),
 ]
 if (docsUrlIs200) {
-  badges.push(badge("Documentation",  `https://docs.rs/${name}/badge.svg`, docsUrl))
+    badges.push(badge("Documentation", `https://docs.rs/${name}/badge.svg`, docsUrl))
 }
-const badgesStr = badges.map(({name, image, url}) => `[![${name}](${image})](${url})`).join("\n");
+const badgesStr = badges.map(({ name, image, url }) => `[![${name}](${image})](${url})`).join("\n")
+
+const renderMarkdownList = (items: string[]) => items.map((bin) => `* ${bin}`).join("\n")
+const renderShellCode = (code: string) => `\`\`\`shell\n${code}\n\`\`\``
 
-const titleSection = [
+const titleSectionBodyParts = [
     badgesStr,
-    docStr
-].filter(s => s.length)
+    docStr,
+].filter((s) => s.length)
+const titleSectionBody = titleSectionBodyParts.join("\n\n")
+
+const sections: Section[] = []
+// NOTE: We need to use the package name (not the target name) in cargo commands
+const installationSectionBodyParts = []
+const installationSectionUseExpandedFormat = primaryBinTarget && primaryTarget !== primaryBinTarget
+if (primaryBinTarget) {
+    const cmd = renderShellCode(`cargo install --locked ${name}`)
+    const text = installationSectionUseExpandedFormat ? `Install as executable:\n\n${cmd}` : cmd
+    installationSectionBodyParts.push(text)
+}
+if (primaryTarget !== primaryBinTarget) {
+    const cmd = renderShellCode(`cargo add ${[name, ...peers].join(" ")}`)
+    const text = installationSectionUseExpandedFormat ? `Install as library dependency in your package:\n\n${cmd}` : cmd
+    installationSectionBodyParts.push(text)
+}
+pushSection(sections, "Installation", installationSectionBodyParts.join("\n\n"))
+if (helpPromise) {
+    const help = await helpPromise
+    pushSection(sections, "Usage", renderShellCode(help.stdout.trim()))
+}
+if (secondaryBinTargets.length) {
+    const secondaryBinTargetsNames = secondaryBinTargets.map((t) => t.name)
+    pushSection(sections, "Additional binaries", renderMarkdownList(secondaryBinTargetsNames.map((bin) => `\`${bin}\``)))
+}
+pushSection(sections, "Gratitude", `Like the project? [⭐ Star this repo](${repo.url}) on GitHub!`)
+pushSection(
+    sections,
+    "License",
+    `
+[Apache License 2.0](LICENSE-APACHE) or [MIT License](LICENSE-MIT) at your option.
+
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+`.trim(),
+)
 
-const cargoAddPackages = [name, ...peers];
+const body = renderNonEmptySections(sections)
 
-const autogenerated = `
+console.info(`
 <!-- DO NOT EDIT -->
 <!-- This file is automatically generated by README.ts. -->
 <!-- Edit README.ts if you want to make changes. -->
-`.trim()
-
-console.info(`
-${autogenerated}
 
 # ${title}
 
-${titleSection.join("\n\n")}
-
-## Installation
+${titleSectionBody}
 
-\`\`\`shell
-cargo add ${cargoAddPackages.join(" ")}
-\`\`\`
-
-## Gratitude
-
-Like the project? [⭐ Star this repo](${repo.url}) on GitHub!
-
-## License
-
-[Apache License 2.0](LICENSE-APACHE) or [MIT License](LICENSE-MIT) at your option.
-
-Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
-`.trim())
+${body}`.trim())