Revive and rework tooling around exported API (#2367)

cucumber · Jan 7, 2024 · 920ee17 · 920ee17
1 parent 0fbe487
commit 920ee17
Show file tree

Hide file tree

Showing 125 changed files with 1,527 additions and 1,340 deletions.
diff --git a/.github/workflows/site.yaml b/.github/workflows/site.yaml
@@ -0,0 +1,35 @@
+name: Site
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  upload-artifact:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20.x
+      - run: npm install
+      - run: npm run exports-generate-docs
+      - run: |
+          chmod -c -R +rX "_site/" | while read line; do
+          echo "::warning title=Invalid file permissions automatically fixed::$line"
+          done
+      - uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    needs: upload-artifact
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -2,6 +2,7 @@
 .nyc_output_feature/
 .nyc_output_unit/
 .nyc_output/
+_site/
 @rerun.txt
 coverage/
 lib/

diff --git a/.prettierignore b/.prettierignore
@@ -1,5 +1,6 @@
 bin
 docs
+exports
 lib
 node_modules
 reports

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 Please see [CONTRIBUTING.md](./CONTRIBUTING.md) on how to contribute to Cucumber.
 
 ## [Unreleased]
+### Changed
+- Improve API documentation and TypeScript types ([#2367](https://github.com/cucumber/cucumber-js/pull/2367))
 
 ## [10.1.0] - 2023-12-21
 ### Added

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -41,9 +41,9 @@ Type `npm run` or see the `package.json` scripts section for how to run each cat
 * feature tests - `npm run feature-test`
   * cucumber-js tests itself
 
-## API Documentation
+## Exports
 
-The functionality exposed under the `@cucumber/cucumber/api` entry point is analysed and has documentation generated by [API Extractor](https://api-extractor.com/). If you make a change that affects the public API surface, you'll need to run `npm run docs:local` to run the analysis and regenerate the docs, and commit the changes. If you forget to do this locally, the CI build will fail and remind you. 
+The functionality exposed under both the `@cucumber/cucumber` and `@cucumber/cucumber/api` entry points is analysed and has a report generated by [API Extractor](https://api-extractor.com/). If you make a change that affects the exported API surface, you'll need to run `npm run exports-update` to run the analysis and regenerate the file, and commit the changes. If you forget to do this locally, the CI build will fail and remind you. 
 
 ## Internals
 

diff --git a/dependency-lint.yml b/dependency-lint.yml
@@ -5,8 +5,9 @@ executedModules:
   npmScripts:
     dev:
       - build
-      - docs:ci
-      - docs:local
+      - exports-generate-docs
+      - exports-test
+      - exports-update
       - lint
       - publish
       - test
@@ -37,6 +38,7 @@ ignoreErrors:
     - prettier # peer dependency of eslint-plugin-prettier
     - ts-node # .mocharc.yml / cucumber.js
     - type-fest # utility types
+    - typedoc-plugin-extras
 
 requiredModules:
   files:

diff --git a/docs/api/cucumber.iloadconfigurationoptions.file.md b/docs/api/cucumber.iloadconfigurationoptions.file.md
diff --git a/docs/api/cucumber.iloadconfigurationoptions.md b/docs/api/cucumber.iloadconfigurationoptions.md
diff --git a/docs/api/cucumber.iloadconfigurationoptions.profiles.md b/docs/api/cucumber.iloadconfigurationoptions.profiles.md
diff --git a/docs/api/cucumber.iloadconfigurationoptions.provided.md b/docs/api/cucumber.iloadconfigurationoptions.provided.md
diff --git a/docs/api/cucumber.iloadsourcesresult.errors.md b/docs/api/cucumber.iloadsourcesresult.errors.md
diff --git a/docs/api/cucumber.iloadsourcesresult.md b/docs/api/cucumber.iloadsourcesresult.md
diff --git a/docs/api/cucumber.iloadsourcesresult.plan.md b/docs/api/cucumber.iloadsourcesresult.plan.md
diff --git a/docs/api/cucumber.iloadsupportoptions.md b/docs/api/cucumber.iloadsupportoptions.md
diff --git a/docs/api/cucumber.iloadsupportoptions.sources.md b/docs/api/cucumber.iloadsupportoptions.sources.md
diff --git a/docs/api/cucumber.iloadsupportoptions.support.md b/docs/api/cucumber.iloadsupportoptions.support.md
diff --git a/docs/api/cucumber.iplannedpickle.location.md b/docs/api/cucumber.iplannedpickle.location.md
diff --git a/docs/api/cucumber.iplannedpickle.md b/docs/api/cucumber.iplannedpickle.md
diff --git a/docs/api/cucumber.iplannedpickle.name.md b/docs/api/cucumber.iplannedpickle.name.md
diff --git a/docs/api/cucumber.iplannedpickle.uri.md b/docs/api/cucumber.iplannedpickle.uri.md
diff --git a/docs/api/cucumber.iresolvedconfiguration.md b/docs/api/cucumber.iresolvedconfiguration.md
diff --git a/docs/api/cucumber.iresolvedconfiguration.runconfiguration.md b/docs/api/cucumber.iresolvedconfiguration.runconfiguration.md
diff --git a/docs/api/cucumber.iresolvedconfiguration.useconfiguration.md b/docs/api/cucumber.iresolvedconfiguration.useconfiguration.md
diff --git a/docs/api/cucumber.irunconfiguration.formats.md b/docs/api/cucumber.irunconfiguration.formats.md
diff --git a/docs/api/cucumber.irunconfiguration.md b/docs/api/cucumber.irunconfiguration.md
-Original file line number
+Diff line change
@@ -1,5 +1,6 @@
     bin
     docs
+    exports
     lib
     node_modules
     reports
@@ Expand Down @@