diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml new file mode 100644 index 00000000..0adc2d39 --- /dev/null +++ b/.github/workflows/build-docs.yml @@ -0,0 +1,41 @@ +name: build docs +on: + push: + branches: + - main +jobs: + build-api-docs: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + + - name: Setup Node.js environment + uses: actions/setup-node@v3 + with: + node-version: 'lts/*' + + - name: Install dependencies + run: npm ci + + - name: Build API docs + run: npm run docs:build + + - name: Checkout documentation repository + uses: actions/checkout@v3 + with: + token: ${{ secrets.DOCS_DEPLOY_GHP }} + repository: 'dice-roller/documentation' + path: './documentation' + + - name: Copy API docs to documentation repository + run: | + rm -rf ./documentation/docs/api + mv ./docs/api ./documentation/docs/api + + - name: Commit and push API doc changes + uses: EndBug/add-and-commit@v9 + with: + cwd: './documentation' + add: './docs/api' + message: 'Auto API update from github workflow' diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index fefa80d9..3c832842 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -21,7 +21,7 @@ jobs: node-version: 'lts/*' - name: Install dependencies - run: npm install + run: npm ci - name: Run tests run: npm run test:coverage @@ -44,7 +44,7 @@ jobs: node-version: 'lts/*' - name: Install dependencies - run: npm install + run: npm ci - name: Build Typescript run: npm run build:declaration @@ -61,7 +61,7 @@ jobs: node-version: 'lts/*' - name: Install dependencies - run: npm install + run: npm ci - name: Build API docs run: npm run docs:build diff --git a/docs/readme.md b/docs/readme.md new file mode 100644 index 00000000..b540756d --- /dev/null +++ b/docs/readme.md @@ -0,0 +1,6 @@ +# Introduction + +The technical API is for people wanting to delve a bit deeper into the classes that make up the library. + +* If you want to get set up quickly, you should start with the [guide](../guide/readme.md). +* If you just want to roll some dice, check out the [notations](../guide/notation/readme.md). diff --git a/package-lock.json b/package-lock.json index fea204b5..127f251e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -33,7 +33,7 @@ "rollup-plugin-banner": "^0.2.1", "rollup-plugin-terser": "^7.0.2", "typescript": "^4.8.4", - "vuepress-jsdoc": "^4.3.0" + "vuepress-jsdoc": "^5.0.0" }, "engines": { "node": ">=18.0" @@ -2688,9 +2688,9 @@ "dev": true }, "node_modules/@jsdoc/salty": { - "version": "0.2.5", - "resolved": "https://registry.npmjs.org/@jsdoc/salty/-/salty-0.2.5.tgz", - "integrity": "sha512-TfRP53RqunNe2HBobVBJ0VLhK1HbfvBYeTC1ahnN64PWvyYyGebmMiPkuwvD9fpw2ZbkoPb8Q7mwy0aR8Z9rvw==", + "version": "0.2.6", + "resolved": "https://registry.npmjs.org/@jsdoc/salty/-/salty-0.2.6.tgz", + "integrity": "sha512-aA+awb5yoml8TQ3CzI5Ue7sM3VMRC4l1zJJW4fgZ8OCL1wshJZhNzaf0PL85DSnOUw6QuFgeHGD/eq/xwwAF2g==", "dev": true, "dependencies": { "lodash": "^4.17.21" @@ -3299,9 +3299,9 @@ "dev": true }, "node_modules/@types/linkify-it": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/@types/linkify-it/-/linkify-it-3.0.2.tgz", - "integrity": "sha512-HZQYqbiFVWufzCwexrvh694SOim8z2d+xJl5UNamcvQFejLY/2YUtzXHYi3cHdI7PMlS8ejH2slRAOJQ32aNbA==", + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/@types/linkify-it/-/linkify-it-3.0.5.tgz", + "integrity": "sha512-yg6E+u0/+Zjva+buc3EIb+29XEg4wltq7cSmd4Uc2EE/1nUVmxyzpX6gUXD0V8jIrG0r7YeOGVIbYRkxeooCtw==", "dev": true }, "node_modules/@types/markdown-it": { @@ -3315,9 +3315,9 @@ } }, "node_modules/@types/mdurl": { - "version": "1.0.2", - "resolved": "https://registry.npmjs.org/@types/mdurl/-/mdurl-1.0.2.tgz", - "integrity": "sha512-eC4U9MlIcu2q0KQmXszyn5Akca/0jrQmwDRgpAMJai7qBWq4amIQhZyNau4VYGtCeALvW1/NtjzJJ567aZxfKA==", + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/@types/mdurl/-/mdurl-1.0.5.tgz", + "integrity": "sha512-6L6VymKTzYSrEf4Nev4Xa1LCHKrlTlYCBMTlQKFuddo1CvQcE52I0mwfOJayueUC7MJuXOeHTcIU683lzd0cUA==", "dev": true }, "node_modules/@types/node": { @@ -4446,12 +4446,12 @@ } }, "node_modules/commander": { - "version": "9.5.0", - "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz", - "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==", + "version": "11.1.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-11.1.0.tgz", + "integrity": "sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==", "dev": true, "engines": { - "node": "^12.20.0 || >=14" + "node": ">=16" } }, "node_modules/common-sequence": { @@ -5805,13 +5805,13 @@ "dev": true }, "node_modules/handlebars": { - "version": "4.7.7", - "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.7.tgz", - "integrity": "sha512-aAcXm5OAfE/8IXkcZvCepKU3VzW1/39Fb5ZuqMtgI/hT8X2YgoMvBY5dLhq/cpOvw7Lk1nK/UF71aLG/ZnVYRA==", + "version": "4.7.8", + "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.8.tgz", + "integrity": "sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ==", "dev": true, "dependencies": { "minimist": "^1.2.5", - "neo-async": "^2.6.0", + "neo-async": "^2.6.2", "source-map": "^0.6.1", "wordwrap": "^1.0.0" }, @@ -8157,9 +8157,9 @@ } }, "node_modules/jsdoc-api": { - "version": "7.2.0", - "resolved": "https://registry.npmjs.org/jsdoc-api/-/jsdoc-api-7.2.0.tgz", - "integrity": "sha512-93YDnlm/OYTlLOFeNs4qAv0RBCJ0kGj67xQaWy8wrbk97Rw1EySitoOTHsTHXPEs3uyx2IStPKGrbE7LTnZXbA==", + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/jsdoc-api/-/jsdoc-api-8.0.0.tgz", + "integrity": "sha512-Rnhor0suB1Ds1abjmFkFfKeD+kSMRN9oHMTMZoJVUrmtCGDwXty+sWMA9sa4xbe4UyxuPjhC7tavZ40mDKK6QQ==", "dev": true, "dependencies": { "array-back": "^6.2.2", @@ -8194,17 +8194,17 @@ } }, "node_modules/jsdoc-to-markdown": { - "version": "7.1.1", - "resolved": "https://registry.npmjs.org/jsdoc-to-markdown/-/jsdoc-to-markdown-7.1.1.tgz", - "integrity": "sha512-CI86d63xAVNO+ENumWwmJ034lYe5iGU5GwjtTA11EuphP9tpnoi4hrKgR/J8uME0D+o4KUpVfwX1fjZhc8dEtg==", + "version": "8.0.0", + "resolved": "https://registry.npmjs.org/jsdoc-to-markdown/-/jsdoc-to-markdown-8.0.0.tgz", + "integrity": "sha512-2FQvYkg491+FP6s15eFlgSSWs69CvQrpbABGYBtvAvGWy/lWo8IKKToarT283w59rQFrpcjHl3YdhHCa3l7gXg==", "dev": true, "dependencies": { "array-back": "^6.2.2", "command-line-tool": "^0.8.0", "config-master": "^3.1.0", - "dmd": "^6.1.0", - "jsdoc-api": "^7.1.1", - "jsdoc-parse": "^6.1.0", + "dmd": "^6.2.0", + "jsdoc-api": "^8.0.0", + "jsdoc-parse": "^6.2.0", "walk-back": "^5.1.0" }, "bin": { @@ -8223,6 +8223,18 @@ "node": ">=8" } }, + "node_modules/jsdoc/node_modules/mkdirp": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz", + "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==", + "dev": true, + "bin": { + "mkdirp": "bin/cmd.js" + }, + "engines": { + "node": ">=10" + } + }, "node_modules/jsesc": { "version": "2.5.2", "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-2.5.2.tgz", @@ -8610,15 +8622,18 @@ } }, "node_modules/mkdirp": { - "version": "1.0.4", - "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-1.0.4.tgz", - "integrity": "sha512-vVqVZQyf3WLx2Shd0qJ9xuvqgAyKPLAiqITEtqW0oIUjzo3PePDd6fW9iFz30ef7Ysp/oiWqbhszeGWW2T6Gzw==", + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/mkdirp/-/mkdirp-3.0.1.tgz", + "integrity": "sha512-+NsyUUAZDmo6YVHzL/stxSu3t9YS1iljliy3BSDrXJ/dkn1KYdmtZODGGjLcc9XLgVVpH4KshHB8XmZgMhaBXg==", "dev": true, "bin": { - "mkdirp": "bin/cmd.js" + "mkdirp": "dist/cjs/src/bin.js" }, "engines": { "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" } }, "node_modules/mkdirp2": { @@ -10788,20 +10803,20 @@ } }, "node_modules/vuepress-jsdoc": { - "version": "4.3.1", - "resolved": "https://registry.npmjs.org/vuepress-jsdoc/-/vuepress-jsdoc-4.3.1.tgz", - "integrity": "sha512-ZZgbM9dSTWx5UGXTisg1l2TNgbznuVSM7/anLfNfaNzYpu5AaKmDPdKerat7USaiMeTiNfc5TY3NXfYfEj0nRQ==", + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/vuepress-jsdoc/-/vuepress-jsdoc-5.0.0.tgz", + "integrity": "sha512-bgNWtLn8l3l26V2CsccAML2xJowzQPlNgjO7E1KN8rvNtjMDcSVD1JmMLQn8MaX4iOAqzCW5F6kW5Mkajx3wng==", "dev": true, "dependencies": { - "chalk": "^4.1.2", "chokidar": "^3.5.3", - "commander": "^9.4.1", + "commander": "^11.1.0", "del": "^6.0.0", "front-matter": "^4.0.2", - "jsdoc-to-markdown": "^7.1.1", + "jsdoc-to-markdown": "^8.0.0", + "kleur": "^4.1.5", "micromatch": "^4.0.5", - "mkdirp": "^1.0.4", - "vue-docgen-cli": "^4.51.0" + "mkdirp": "^3.0.1", + "vue-docgen-cli": "^4.67.0" }, "bin": { "vuepress-jsdoc": "bin/vuepress-jsdoc.js" @@ -10810,74 +10825,13 @@ "node": ">=14" } }, - "node_modules/vuepress-jsdoc/node_modules/ansi-styles": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz", - "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==", - "dev": true, - "dependencies": { - "color-convert": "^2.0.1" - }, - "engines": { - "node": ">=8" - }, - "funding": { - "url": "https://github.com/chalk/ansi-styles?sponsor=1" - } - }, - "node_modules/vuepress-jsdoc/node_modules/chalk": { - "version": "4.1.2", - "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz", - "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==", - "dev": true, - "dependencies": { - "ansi-styles": "^4.1.0", - "supports-color": "^7.1.0" - }, - "engines": { - "node": ">=10" - }, - "funding": { - "url": "https://github.com/chalk/chalk?sponsor=1" - } - }, - "node_modules/vuepress-jsdoc/node_modules/color-convert": { - "version": "2.0.1", - "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz", - "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==", - "dev": true, - "dependencies": { - "color-name": "~1.1.4" - }, - "engines": { - "node": ">=7.0.0" - } - }, - "node_modules/vuepress-jsdoc/node_modules/color-name": { - "version": "1.1.4", - "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz", - "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==", - "dev": true - }, - "node_modules/vuepress-jsdoc/node_modules/has-flag": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", - "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", - "dev": true, - "engines": { - "node": ">=8" - } - }, - "node_modules/vuepress-jsdoc/node_modules/supports-color": { - "version": "7.2.0", - "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz", - "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==", + "node_modules/vuepress-jsdoc/node_modules/kleur": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz", + "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==", "dev": true, - "dependencies": { - "has-flag": "^4.0.0" - }, "engines": { - "node": ">=8" + "node": ">=6" } }, "node_modules/walk-back": { diff --git a/package.json b/package.json index 2a168c8d..d510454c 100644 --- a/package.json +++ b/package.json @@ -70,7 +70,7 @@ "rollup-plugin-banner": "^0.2.1", "rollup-plugin-terser": "^7.0.2", "typescript": "^4.8.4", - "vuepress-jsdoc": "^4.3.0" + "vuepress-jsdoc": "^5.0.0" }, "dependencies": { "mathjs": "^11.2.1", @@ -86,7 +86,7 @@ "build:dev": "npm run build:prepare && rollup --c --environment BUILD:dev", "build:grammars": "peggy -c ./peggy.config.cjs ./src/parser/grammars/grammar.pegjs", "build:prod": "npm run build:prepare && rollup --c --environment BUILD:prod", - "docs:build": "vuepress-jsdoc --dist ./docs --folder api --exclude=\"index.js,**/index.js,**/parser/grammars/*\" --partials=\"./docs/partials/**/*.hbs\"", + "docs:build": "vuepress-jsdoc --dist ./docs --folder api --exclude=\"index.js,**/index.js,**/parser/grammars/*\" --partials=\"./docs/partials/**/*.hbs\" --readme=\"./docs/readme.md\"", "docs:watch": "npm run docs:build -- --watch", "watch": "npm run build:dev -- -w", "lint": "eslint src/** tests/**",