docs: automatically create the readme for the packages

2022-08-07 18:18:26 -07:00 · 2022-08-07 18:18:26 -07:00 · 758bb59065
parent b77e674a50
commit 758bb59065
7 changed files with 1210 additions and 25 deletions
--- a/dev/readme/template.md
+++ b/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).
--- a/package.json
+++ b/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": {
--- a/packages/exec-powershell/README.md
+++ b/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).
--- a/packages/exec-powershell/src/index.ts
+++ b/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)
 }

--- a/packages/sudo-tools/README.md
+++ b/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).
--- a/packages/sudo-tools/src/index.ts
+++ b/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 {
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml