Minor changes, update CONTRIBUTING.md

Author: flevi29

.github/workflows/tests.yml

@@ -75,13 +75,8 @@ jobs:
           cache: 'yarn'
       - name: Install dependencies
         run: yarn --dev
-      - name: Generate code sample files
-        run: yarn generate-code-sample-files
       - name: Run code style check
         run: yarn style
-      # https://github.com/prettier/prettier/issues/15438
-      - name: Check formatting of code samples
-        run: yarn prettier --ignore-path=.prettierignore -c generated-code-samples
       - name: Run yaml style check
         uses: ibiqlik/action-yamllint@v3
         with:
@@ -98,8 +93,6 @@ jobs:
           cache: 'yarn'
       - name: Install dependencies
         run: yarn --dev
-      - name: Generate code sample files
-        run: yarn generate-code-sample-files
       - name: Build project
         run: yarn build
       - name: Run types check

CONTRIBUTING.md

@@ -70,6 +70,20 @@ yarn style:fix
 yarn build
 ```
 
+### Code samples
+
+In this repository code samples are linted and type checked. To achieve this we generate
+TypeScript files from `.code-samples.meilisearch.yaml`, and vice-versa.
+
+```bash
+# Generate files
+yarn generate-code-sample-files
+# Generate YAML file
+yarn generate-code-samples-yaml
+# For maintainers to generate new code samples
+yarn generate-code-sample-files new_sample_one new_sample_two
+```
+
 ## Git Guidelines
 
 ### Git Branches

package.json

@@ -44,7 +44,7 @@
     "build": "vite build && tsc -p tsconfig.build.json && vite --mode production-umd build",
     "postbuild": "node scripts/build.js",
     "test": "vitest run --coverage",
-    "types": "tsc -p tsconfig.json --noEmit",
+    "types": "yarn generate-code-sample-files && tsc -p tsconfig.json --noEmit",
     "types:watch": "yarn types --watch",
     "test:env:browser": "yarn build && node scripts/copy-umd-file.js --to ./tests/env/express/public && yarn --cwd tests/env/express && yarn --cwd tests/env/express test",
     "test:watch": "vitest watch",
@@ -61,8 +61,8 @@
     "fmt:fix": "prettier -w ./**/*.{js,ts}",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
-    "style": "yarn fmt && yarn lint",
-    "style:fix": "yarn fmt:fix && yarn lint:fix",
+    "style": "yarn generate-code-sample-files && prettier --ignore-path=.prettierignore -c generated-code-samples && yarn fmt && yarn lint",
+    "style:fix": "yarn generate-code-sample-files && prettier --ignore-path=.prettierignore -c generated-code-samples && yarn fmt:fix && yarn lint:fix",
     "prepare": "husky"
   },
   "files": [

scripts/code-samples/from-yaml.js

@@ -11,6 +11,7 @@ const headerClientDeclaration =
   'const _client = new MeiliSearch({ host: "http://127.0.0.1:7700" });\n';
 const headerComment =
   "// Code below this line will be written to code samples YAML file\n" +
+  '// For more information consult CONTRIBUTING.md "Tests and Linter" section\n' +
   delimiter +
   "\n";
 
@@ -32,6 +33,8 @@ for (const jsonFileToGenerate of jsonFilesToGenerate) {
   );
 }
 
+let generatedFileTally = 0;
+
 for (const { sampleName, code } of iterateCodeSamples()) {
   let header = "";
 
@@ -51,6 +54,8 @@ for (const { sampleName, code } of iterateCodeSamples()) {
     new URL(sampleName + ".ts", generatedCodeSamplesDir),
     header + code + "\n",
   );
+
+  generatedFileTally += 1;
 }
 
 // generate additional files from arguments passed
@@ -59,4 +64,8 @@ for (const sampleName of argv.slice(3)) {
     new URL(sampleName + ".ts", generatedCodeSamplesDir),
     headerImport + headerClientDeclaration + headerComment,
   );
+
+  generatedFileTally += 1;
 }
+
+console.log(`generated ${generatedFileTally} code sample file(s)`);

scripts/code-samples/to-yaml.js

@@ -86,10 +86,13 @@ const serializedCodeSamples = manipulatedCodeSamples
   .join("\n");
 
 const header =
-  "# This code-samples file is used by the Meilisearch documentation\n" +
+  "# This code-samples file is used by the Meilisearch documentation.\n" +
   "# Every example written here will be automatically fetched by\n" +
-  "# the documentation on build\n" +
+  "# the documentation on build.\n" +
   "# You can read more at https://github.com/meilisearch/documentation\n" +
+  '# This file is generated, read more in CONTRIBUTING.md "Tests and Linter" section.' +
   "---\n";
 
 writeFileSync(codeSamplesPath, header + serializedCodeSamples + "\n");
+
+console.log(`generated ${manipulatedCodeSamples.length} code sample(s)`);