readme templating (#280)

* readme templating * cleanup * fix * fix * more readme * more readme * fix
csstools · Mar 2, 2022 · a1fe846 · a1fe846
1 parent d89d8fb
commit a1fe846
Show file tree

Hide file tree

Showing 55 changed files with 2,129 additions and 1,639 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -10,6 +10,6 @@ trim_trailing_whitespace = true
 [*.md]
 trim_trailing_whitespace = false
 
-[*.{json,md,yml}]
+[*.{json,yml}]
 indent_size = 2
 indent_style = space
diff --git a/.github/bin/fail-on-changes.sh b/.github/bin/fail-on-changes.sh
@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -e
+
+if [ -n "$(git status --porcelain)" ]; then
+	git status;
+
+	echo "\n!!! Repo is not clean, check changes before continuing. !!!";
+else
+	echo "Repo is clean";
+fi
diff --git a/.github/bin/generate-docs/install-template.md b/.github/bin/generate-docs/install-template.md
@@ -20,7 +20,7 @@ const postcss = require('postcss');
 const <exportName> = require('<packageName>');
 
 postcss([
-  <exportName>(/* pluginOptions */)
+	<exportName>(/* pluginOptions */)
 ]).process(YOUR_CSS /*, processOptions */);
 ```
 
@@ -38,9 +38,9 @@ Use [<humanReadableName>] in your `postcss.config.js` configuration file:
 const <exportName> = require('<packageName>');
 
 module.exports = {
-  plugins: [
-    <exportName>(/* pluginOptions */)
-  ]
+	plugins: [
+		<exportName>(/* pluginOptions */)
+	]
 }
 ```
 
@@ -58,35 +58,35 @@ Use [<humanReadableName>] in your Webpack configuration:
 
 ```js
 module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.css$/i,
-        use: [
-          "style-loader",
-          {
-            loader: "css-loader",
-            options: { importLoaders: 1 },
-          },
-          {
-            loader: "postcss-loader",
-            options: {
-              postcssOptions: {
-                plugins: [
-                  [
-                    "<packageName>",
-                    {
-                      // Options
-                    },
-                  ],
-                ],
-              },
-            },
-          },
-        ],
-      },
-    ],
-  },
+	module: {
+		rules: [
+			{
+				test: /\.css$/i,
+				use: [
+					"style-loader",
+					{
+						loader: "css-loader",
+						options: { importLoaders: 1 },
+					},
+					{
+						loader: "postcss-loader",
+						options: {
+							postcssOptions: {
+								plugins: [
+									[
+										"<packageName>",
+										{
+											// Options
+										},
+									],
+								],
+							},
+						},
+					},
+				],
+			},
+		],
+	},
 };
 ```
 
@@ -106,9 +106,9 @@ const reactAppRewirePostcss = require('react-app-rewire-postcss');
 const <exportName> = require('<packageName>');
 
 module.exports = config => reactAppRewirePostcss(config, {
-  plugins: () => [
-    <exportName>(/* pluginOptions */)
-  ]
+	plugins: () => [
+		<exportName>(/* pluginOptions */)
+	]
 });
 ```
 
@@ -127,13 +127,13 @@ const postcss = require('gulp-postcss');
 const <exportName> = require('<packageName>');
 
 gulp.task('css', function () {
-  var plugins = [
-    <exportName>(/* pluginOptions */)
-  ];
+	var plugins = [
+		<exportName>(/* pluginOptions */)
+	];
 
-  return gulp.src('./src/*.css')
-    .pipe(postcss(plugins))
-    .pipe(gulp.dest('.'));
+	return gulp.src('./src/*.css')
+		.pipe(postcss(plugins))
+		.pipe(gulp.dest('.'));
 });
 ```
 
@@ -153,16 +153,16 @@ const <exportName> = require('<packageName>');
 grunt.loadNpmTasks('grunt-postcss');
 
 grunt.initConfig({
-  postcss: {
-    options: {
-      processors: [
-       <exportName>(/* pluginOptions */)
-      ]
-    },
-    dist: {
-      src: '*.css'
-    }
-  }
+	postcss: {
+		options: {
+			processors: [
+			<exportName>(/* pluginOptions */)
+			]
+		},
+		dist: {
+			src: '*.css'
+		}
+	}
 });
 ```
 

diff --git a/.github/bin/generate-docs/readme.mjs b/.github/bin/generate-docs/readme.mjs
@@ -0,0 +1,89 @@
+import { promises as fsp } from 'fs';
+import path from 'path';
+
+const template = await fsp.readFile(path.join('docs', './README.md'), 'utf8');
+const packageJSONInfo = JSON.parse(await fsp.readFile('./package.json', 'utf8'));
+
+const exampleFilePaths = await fsp.readdir(path.join('test', 'examples'));
+
+let installDoc = template.toString();
+
+// Cleanup docs instructions
+installDoc = installDoc.replace(`<!-- Available Variables: -->
+<!-- <humanReadableName> PostCSS Your Plugin -->
+<!-- <exportName> postcssYourPlugin -->
+<!-- <packageName> @csstools/postcss-your-plugin -->
+<!-- <packagePath> plugins/postcss-your-plugin -->
+<!-- <cssdbId> your-feature -->
+<!-- <specUrl> https://www.w3.org/TR/css-color-4/#funcdef-color -->
+<!-- <example.css> file contents for examples/example.css -->
+<!-- <header> -->
+<!-- <usage> usage instructions -->
+<!-- <env-support> -->
+<!-- <link-list> -->
+<!-- to generate : npm run docs -->
+
+`, '');
+
+// Insert "Header" section
+installDoc = installDoc.replace('<header>', `# <humanReadableName> [<img src="https://postcss.github.io/postcss/logo.svg" alt="PostCSS Logo" width="90" height="90" align="right">][postcss]
+
+[<img alt="npm version" src="https://img.shields.io/npm/v/<packageName>.svg" height="20">][npm-url]
+[<img alt="CSS Standard Status" src="https://cssdb.org/images/badges/<cssdbId>.svg" height="20">][css-url]
+[<img alt="Build Status" src="https://github.com/csstools/postcss-plugins/workflows/test/badge.svg" height="20">][cli-url]
+[<img alt="Discord" src="https://shields.io/badge/Discord-5865F2?logo=discord&logoColor=white">][discord]`);
+
+// Insert "Usage" section
+installDoc = installDoc.replace('<usage>', `## Usage
+
+Add [<humanReadableName>] to your project:
+
+\`\`\`bash
+npm install postcss <packageName> --save-dev
+\`\`\`
+
+Use it as a [PostCSS] plugin:
+
+\`\`\`js
+const postcss = require('postcss');
+const <exportName> = require('<packageName>');
+
+postcss([
+  <exportName>(/* pluginOptions */)
+]).process(YOUR_CSS /*, processOptions */);
+\`\`\``);
+
+// Insert "Env Support" section
+installDoc = installDoc.replace('<env-support>', `[<humanReadableName>] runs in all Node environments, with special
+instructions for:
+
+| [Node](INSTALL.md#node) | [PostCSS CLI](INSTALL.md#postcss-cli) | [Webpack](INSTALL.md#webpack) | [Create React App](INSTALL.md#create-react-app) | [Gulp](INSTALL.md#gulp) | [Grunt](INSTALL.md#grunt) |
+| --- | --- | --- | --- | --- | --- |`);
+
+// Insert "Link List" section
+installDoc = installDoc.replace('<link-list>', `[cli-url]: https://github.com/csstools/postcss-plugins/actions/workflows/test.yml?query=workflow/test
+[css-url]: https://cssdb.org/#<cssdbId>
+[discord]: https://discord.gg/bUadyRwkJS
+[npm-url]: https://www.npmjs.com/package/<packageName>
+
+[Gulp PostCSS]: https://github.com/postcss/gulp-postcss
+[Grunt PostCSS]: https://github.com/nDmitry/grunt-postcss
+[PostCSS]: https://github.com/postcss/postcss
+[PostCSS Loader]: https://github.com/postcss/postcss-loader
+[<humanReadableName>]: https://github.com/csstools/postcss-plugins/tree/main/<packagePath>`);
+
+installDoc = installDoc.replaceAll('<cssdbId>', packageJSONInfo.csstools.cssdbId);
+installDoc = installDoc.replaceAll('<exportName>', packageJSONInfo.csstools.exportName);
+installDoc = installDoc.replaceAll('<humanReadableName>', packageJSONInfo.csstools.humanReadableName);
+installDoc = installDoc.replaceAll('<packageName>', packageJSONInfo.name);
+installDoc = installDoc.replaceAll('<packagePath>', path.join(path.basename(path.dirname(process.cwd())), path.basename(process.cwd())));
+installDoc = installDoc.replaceAll('<specUrl>', packageJSONInfo.csstools.specUrl);
+
+for (const exampleFilePath of exampleFilePaths) {
+	installDoc = installDoc.replaceAll(
+		`<${exampleFilePath}>`,
+		(await fsp.readFile(path.join('test', 'examples', exampleFilePath), 'utf8')).toString().slice(0, -1) // trim final newline
+	);
+}
+
+await fsp.writeFile('./README.md', installDoc);
diff --git a/.github/bin/install-and-test-all-packages.sh b/.github/bin/install-and-test-all-packages.sh
@@ -1,3 +1,5 @@
+#!/usr/bin/env bash
+
 # REMOVE this file after node 20 is released and update the test.yml workflow
 
 set -e

diff --git a/.github/bin/new-plugin.mjs b/.github/bin/new-plugin.mjs
@@ -101,6 +101,7 @@ console.log('\nDone! 🎉');
 	console.log('\nYour next steps:');
 	console.log('- Run : "npm install" from the root directory');
 	console.log(`- Run : "cd plugins/${pluginSlug}"`);
+	console.log('- Run : "npm run docs" to generate documentation');
 	console.log('- Run : "npm run build" to build your plugin');
 	console.log('- Run : "npm run test" to test your plugin');
 	console.log('- Run : "npm run test:rewrite-expects" to update test expects');

diff --git a/package.json b/package.json
@@ -31,12 +31,14 @@
     "typescript": "^4.5.5"
   },
   "scripts": {
-    "get-me-going": "npm run clean && npm ci && npm run build && npm run test",
     "build": "npm run build --workspaces --if-present",
     "clean": "git clean -dfx",
+    "get-me-going": "npm run clean && npm ci && npm run build && npm run test",
+    "docs": "npm run docs --workspaces --if-present",
     "lint": "npm run lint --workspaces --if-present && npm run lint:rollup-config",
     "lint:rollup-config": "eslint ./rollup --ext .js --ext .ts --ext .mjs --no-error-on-unmatched-pattern",
     "new-plugin": "node ./.github/bin/new-plugin.mjs",
+    "prepare-repo-for-releases": "npm run clean && npm ci && npm run docs && npm run lint && npm run build && npm run test && bash ./.github/bin/fail-on-changes.sh",
     "test": "npm run test --workspaces --if-present"
   },
   "volta": {