docs: automatically create the readme for the packages

dev/readme/template.md

@@ -0,0 +1,61 @@
+<h1 align="center"><%= projectName %></h1>
+<p>
+<% if (isProjectOnNpm) { -%>
+  <a href="https://www.npmjs.com/package/<%= projectName %>" target="_blank">
+    <img alt="Version" src="https://img.shields.io/npm/v/<%= projectName %>.svg">
+  </a>
+<% } -%>
+<% if (projectVersion && !isProjectOnNpm) { -%>
+  <img alt="Version" src="https://img.shields.io/badge/version-<%= projectVersion %>-blue.svg?cacheSeconds=2592000" />
+<% } -%>
+<% if (projectPrerequisites) { -%>
+<% projectPrerequisites.map(({ name, value }) => { -%>
+  <img src="https://img.shields.io/badge/<%= name %>-<%= encodeURIComponent(value) %>-blue.svg" />
+<% }) -%>
+<% } -%>
+<% if (projectDocumentationUrl) { -%>
+  <a href="<%= projectDocumentationUrl %>" target="_blank">
+    <img alt="Documentation" src="https://img.shields.io/badge/documentation-yes-brightgreen.svg" />
+  </a>
+<% } -%>
+<% if (isGithubRepos) { -%>
+  <a href="<%= repositoryUrl %>/graphs/commit-activity" target="_blank">
+    <img alt="Maintenance" src="https://img.shields.io/badge/Maintained%3F-yes-green.svg" />
+  </a>
+<% } -%>
+<% if (licenseName) { -%>
+  <a href="<%= licenseUrl ? licenseUrl : '#' %>" target="_blank">
+    <img alt="License: <%= licenseName %>" src="https://img.shields.io/<%= isGithubRepos ? `github/license/${authorGithubUsername}/${projectName}` : `badge/License-${licenseName}-yellow.svg` %>" />
+  </a>
+<% } -%>
+<% if (authorTwitterUsername) { -%>
+  <a href="https://twitter.com/<%= authorTwitterUsername %>" target="_blank">
+    <img alt="Twitter: <%= authorTwitterUsername %>" src="https://img.shields.io/twitter/follow/<%= authorTwitterUsername %>.svg?style=social" />
+  </a>
+<% } -%>
+</p>
+<% if (projectDescription) { -%>
+
+> <%= projectDescription %>
+> <% } -%>
+
+## Install
+
+```sh
+npm install --save <%= projectName %>
+```
+
+## Usage
+
+<!-- INSERT GENERATED DOCS START -->
+
+<!-- INSERT GENERATED DOCS END -->
+
+## 🤝 Contributing
+
+You can sponsor my work here:
+
+https://github.com/sponsors/aminya
+
+Pull requests, issues and feature requests are welcome.
+See the [Contributing guide](https://github.com/aminya/setup-cpp/blob/master/CONTRIBUTING.md).

package.json

@@ -27,6 +27,7 @@
     "clean": "shx rm -rf .parcel-cache dist exe",
     "copy.matchers": "shx cp ./src/gcc/gcc_matcher.json ./dist/ && shx cp ./src/msvc/msvc_matcher.json ./dist && shx cp ./src/python/python_matcher.json ./dist/ && shx cp ./src/llvm/llvm_matcher.json ./dist/ ",
     "dev": "cross-env NODE_ENV=development parcel watch",
+    "docs": "shx rm -rf packages/*/README.md && pnpm -r exec readme --path ../../dev/readme/template.md -y && pnpm -r exec ts-readme",
     "format": "run-s lint.prettier",
     "lint": "run-p --aggregate-output --continue-on-error lint.cspell lint.eslint lint.prettier lint.tsc",
     "lint.cspell": "cspell lint --no-progress --show-suggestions",
@@ -60,9 +61,9 @@
     "mri": "^1.2.0",
     "msvc-dev-cmd": "github:aminya/msvc-dev-cmd#9f672c1",
     "numerous": "1.0.3",
+    "root-tools": "workspace:*",
     "semver": "7.3.7",
     "setup-python": "github:actions/setup-python#c474c82340438924daab9282d07300bfe7e3692d",
-    "root-tools": "workspace:*",
     "time-delta": "github:aminya/time-delta#69d91a41cef28e569be9a2991129f5f7d1f0d00e",
     "ubuntu-version": "^2.0.0",
     "untildify": "^4.0.0",
@@ -81,6 +82,7 @@
     "cspell": "^6.5.0",
     "eslint": "^8.21.0",
     "eslint-config-atomic": "^1.18.1",
+    "gen-readme": "^1.6.0",
     "jest": "^28.1.3",
     "loose-ts-check": "^1.2.0",
     "npm-check-updates": "^16.0.5",
@@ -88,9 +90,11 @@
     "parcel": "2.6.2",
     "prettier": "2.7.1",
     "prettier-config-atomic": "^3.0.10",
+    "readme-md-generator": "^1.0.0",
     "shx": "0.3.4",
     "terser-config-atomic": "^0.1.1",
     "ts-jest": "^28.0.7",
+    "ts-readme": "^1.1.3",
     "typescript": "^4.7.4"
   },
   "engines": {

packages/exec-powershell/README.md

@@ -0,0 +1,60 @@
+<h1 align="center">exec-powershell</h1>
+<p>
+  <img alt="Version" src="https://img.shields.io/badge/version-1.0.0-blue.svg?cacheSeconds=2592000" />
+  <a href="#" target="_blank">
+    <img alt="License: Apache--2.0" src="https://img.shields.io/badge/License-Apache--2.0-yellow.svg" />
+  </a>
+</p>
+
+> Run a powershell command.
+
+## Install
+
+```sh
+npm install --save exec-powershell
+```
+
+## Usage
+
+<!-- INSERT GENERATED DOCS START -->
+
+### `execPowershell` (function)
+
+Asynchronously execute a powershell command.
+
+**Parameters:**
+
+- command (`string`) - The powershell command to execute
+- startupFlags (`string[]`) - The optional startup flags to be passed to powershell. Defaults to `["-NoProfile", "-NoLogo", "-NonInteractive"]`. This means that the Powershell profile is not sourced first.
+- execOptions (`execa.Options`) - The options passed to `execa`. Defaults to `{ stdio: "inherit" }`
+
+**returns:** execa.ExecaChildProcess<string>
+
+### `execPowershellSync` (function)
+
+Execute a powershell command.
+
+**Parameters:**
+
+- command (`string`) - The powershell command to execute
+- startupFlags (`string[]`) - The optional startup flags to be passed to powershell. Defaults to `["-NoProfile", "-NoLogo", "-NonInteractive"]`. This means that the Powershell profile is not sourced first.
+- execOptions (`execa.SyncOptions`) - The options passed to `execa`. Defaults to `{ stdio: "inherit" }`
+
+**returns:** execa.ExecaSyncReturnValue<string>
+
+### `getPowerShell` (function)
+
+Get the path to the powershell executable.
+
+**returns:** string
+
+<!-- INSERT GENERATED DOCS END -->
+
+## 🤝 Contributing
+
+You can sponsor my work here:
+
+https://github.com/sponsors/aminya
+
+Pull requests, issues and feature requests are welcome.
+See the [Contributing guide](https://github.com/aminya/setup-cpp/blob/master/CONTRIBUTING.md).

packages/exec-powershell/src/index.ts

@@ -8,19 +8,17 @@ let powershell: string | undefined
  * Asynchronously execute a powershell command.
  *
  * @param command The powershell command to execute
- * @param startupFlags The optional startup flags to be passed to powershell.
- *
- *   Defaults to `["-NoProfile", "-NoLogo", "-NonInteractive"]`. This means that the Powershell profile is not sourced first.
- * @param execOptions The options passed to `execa`.
- *
- *   Defaults to `{ stdio: "inherit" }`
+ * @param startupFlags The optional startup flags to be passed to powershell. Defaults to `["-NoProfile", "-NoLogo",
+ *   "-NonInteractive"]`. This means that the Powershell profile is not sourced first.
+ * @param execOptions The options passed to `execa`. Defaults to `{ stdio: "inherit" }`
+ * @returns A promise to the execution result
  * @note It prefers `pwsh` over `powershell`
  */
 export function execPowershell(
   command: string,
   startupFlags: string[] = ["-NoProfile", "-NoLogo", "-NonInteractive"],
   execOptions: execa.Options = { stdio: "inherit" }
-) {
+): execa.ExecaChildProcess<string> {
   return execa(getPowerShell(), [...startupFlags, "-c", command], execOptions)
 }
 
@@ -28,19 +26,17 @@ export function execPowershell(
  * Execute a powershell command.
  *
  * @param command The powershell command to execute
- * @param startupFlags The optional startup flags to be passed to powershell.
- *
- *   Defaults to `["-NoProfile", "-NoLogo", "-NonInteractive"]`. This means that the Powershell profile is not sourced first.
- * @param execOptions The options passed to `execa`.
- *
- *   Defaults to `{ stdio: "inherit" }`
+ * @param startupFlags The optional startup flags to be passed to powershell. Defaults to `["-NoProfile", "-NoLogo",
+ *   "-NonInteractive"]`. This means that the Powershell profile is not sourced first.
+ * @param execOptions The options passed to `execa`. Defaults to `{ stdio: "inherit" }`
+ * @returns The execution result
  * @note It prefers `pwsh` over `powershell`
  */
 export function execPowershellSync(
   command: string,
   startupFlags: string[] = ["-NoProfile", "-NoLogo", "-NonInteractive"],
   execOptions: execa.SyncOptions = { stdio: "inherit" }
-) {
+): execa.ExecaSyncReturnValue<string> {
   return execa.sync(getPowerShell(), [...startupFlags, "-c", command], execOptions)
 }
 

packages/sudo-tools/README.md

@@ -0,0 +1,76 @@
+<h1 align="center">root-tools</h1>
+<p>
+  <img alt="Version" src="https://img.shields.io/badge/version-1.0.0-blue.svg?cacheSeconds=2592000" />
+  <a href="#" target="_blank">
+    <img alt="License: Apache--2.0" src="https://img.shields.io/badge/License-Apache--2.0-yellow.svg" />
+  </a>
+</p>
+
+> Tools for working with root and sudo such as executing command as root, detecting root, etc.
+
+## Install
+
+```sh
+npm install --save root-tools
+```
+
+## Usage
+
+<!-- INSERT GENERATED DOCS START -->
+
+### `isSudo` (function)
+
+Detect if sudo is available and the user has root privileges
+
+**returns:** boolean
+
+### `isRoot` (function)
+
+Detect if the process has root privileges
+
+**returns:** boolean
+
+### `prependSudo` (function)
+
+Prepend `sudo` to the command if sudo is available
+
+**Parameters:**
+
+- command (`string`)
+
+**returns:** string
+
+### `execRootSync` (function)
+
+Execute a command as root if sudo is available. Otherwise executes the command normally without sudo.
+
+**Parameters:**
+
+- program (`string`) - The program to spawn
+- args (`string[]`) - The command arguments
+- execOptions (`execa.SyncOptions`) - The options passed to `execa`. Defaults to `{ stdio: "inherit" }`
+
+**returns:** execa.ExecaSyncReturnValue<string>
+
+### `execRoot` (function)
+
+Asynchronously execute a command as root if sudo is available. Otherwise executes the command normally without sudo.
+
+**Parameters:**
+
+- program (`string`) - The program to spawn
+- args (`string[]`) - The command arguments
+- execOptions (`execa.Options`) - The options passed to `execa`. Defaults to `{ stdio: "inherit" }`
+
+**returns:** execa.ExecaChildProcess<string>
+
+<!-- INSERT GENERATED DOCS END -->
+
+## 🤝 Contributing
+
+You can sponsor my work here:
+
+https://github.com/sponsors/aminya
+
+Pull requests, issues and feature requests are welcome.
+See the [Contributing guide](https://github.com/aminya/setup-cpp/blob/master/CONTRIBUTING.md).

packages/sudo-tools/src/index.ts

@@ -24,15 +24,14 @@ export function prependSudo(command: string) {
  *
  * @param program The program to spawn
  * @param args The command arguments
- * @param execOptions The options passed to `execa`.
- *
- *   Defaults to `{ stdio: "inherit" }`
+ * @param execOptions The options passed to `execa`. Defaults to `{ stdio: "inherit" }`
+ * @returns The execution result
  */
 export function execRootSync(
   program: string,
   args: string[] = [],
   execOptions: execa.SyncOptions = { stdio: "inherit" }
-) {
+): execa.ExecaSyncReturnValue<string> {
   if (isSudo()) {
     return execa.commandSync(`sudo ${[program, ...args].map((arg) => `'${arg}'`).join(" ")}`, execOptions)
   } else {
@@ -45,11 +44,14 @@ export function execRootSync(
  *
  * @param program The program to spawn
  * @param args The command arguments
- * @param execOptions The options passed to `execa`.
- *
- *   Defaults to `{ stdio: "inherit" }`
+ * @param execOptions The options passed to `execa`. Defaults to `{ stdio: "inherit" }`
+ * @returns A promise to the execution result
  */
-export function execRoot(program: string, args: string[] = [], execOptions: execa.Options = { stdio: "inherit" }) {
+export function execRoot(
+  program: string,
+  args: string[] = [],
+  execOptions: execa.Options = { stdio: "inherit" }
+): execa.ExecaChildProcess<string> {
   if (isSudo()) {
     return execa.command(`sudo ${[program, ...args].map((arg) => `'${arg}'`).join(" ")}`, execOptions)
   } else {