diff --git a/documentation/how-to/contribute-to-docs.md b/documentation/how-to/contribute-to-docs.md index 43ab90c..8a6ea6a 100644 --- a/documentation/how-to/contribute-to-docs.md +++ b/documentation/how-to/contribute-to-docs.md @@ -23,29 +23,25 @@ Create your new `.md` file in one of the folders mentioned above based upon your ### Step two -Update the `typedoc.json` configuration file. The `pages` object contains all of the configuration for embedding markdown in the generated docs. +Update the `typedoc.js` configuration file. The `pluginPages` object contains all of the configuration for embedding markdown in the generated docs. -```json -"pages": { - "groups": [ +```js +pluginPages: { + source: './documentation/', + pages: [ { - "title": "How To", - "pages": [ - { "title": "Contribute to the documentation", "source": "./documentation/how-to/contribute-to-docs.md" } - ] - } + title: 'How To', + children: [ + { title: 'Contribute to these docs', source: './how-to/contribute-to-docs.md' }, + { title: 'Create a config file', source: './how-to/create-a-config-file.md' }, + { title: 'Release', source: './how-to/create-a-config-file.md' }, + ], + }, ], - "output": "pages" -} +}, ``` -A `group` is a section header that the documents belong to. In the example above you can see there is a group named `How To` and it's member pages are describe below. To add your new documentation determine which group it should belong to and add a new page. - -```json -"pages": [ - { "title": "My new docs", "source": "./documentation/how-to/my-new-docs.md" } -] -``` +Above you can see a page with just a title and no source for `How To`. This creates the How To section header and brings all the specified child documents under it. ## Updating API/Reference documentation diff --git a/documentation/how-to/release.md b/documentation/how-to/release.md index e2a6ad9..1117e78 100644 --- a/documentation/how-to/release.md +++ b/documentation/how-to/release.md @@ -1,12 +1,13 @@ # How to release a new version of Rotten Deps 1. Create a new changelog entry using semver in the title. The release version in the follow steps is pulled from the changelog version header -2. Run the release script using `bash scripts/release.sh` +2. Run the command `yarn run docs` to generate the new documentation for the GitHub page +3. Run the release script using `bash scripts/release.sh` - Since the documentation reads the version of the `package.json` this first creates a dummy NPM version without creating a commit or tag - Once the dummy version is created the docs are generated - The docs and `CHANGELOG.md` are staged in git - The real `npm version` is run creating a release commit and tag -3. Push the release using `git push origin main` -4. Push the new tag using `git push --tags` -5. Login to NPM using `npm login` -6. Publish to NPM using `npm publish --access public` +4. Push the release using `git push origin main` +5. Push the new tag using `git push --tags` +6. Login to NPM using `npm login` +7. Publish to NPM using `npm publish --access public` diff --git a/documentation/type.hbs b/documentation/type.hbs deleted file mode 100644 index 1e19959..0000000 --- a/documentation/type.hbs +++ /dev/null @@ -1,335 +0,0 @@ -{{! Each type gets its own inline helper to determine how it is rendered. }} -{{! The name of the helper is the value of the 'type' property on the type.}} - -{{! -The type helper accepts an optional needsParens parameter that is checked -if an inner type may result in invalid output without them. For example: -1 | 2[] !== (1 | 2)[] -() => 1 | 2 !== (() => 1) | 2 -}} - -{{#*inline 'array'}} - {{#with elementType}} - {{> type needsParens=true}} - [] - {{/with}} -{{/inline}} - -{{#*inline 'conditional'}} - {{#if needsParens}} - ( - {{/if}} - {{#with checkType}} - {{> type needsParens=true}} - {{/with}} - extends - {{#with extendsType}} - {{> type}} - {{/with}} - ? - {{#with trueType}} - {{> type}} - {{/with}} - : - {{#with falseType}} - {{> type}} - {{/with}} - {{#if needsParens}} - ) - {{/if}} -{{/inline}} - -{{#*inline 'indexedAccess'}} - {{#with objectType}} - {{> type}} - {{/with}} - [ - {{#with indexType}} - {{> type}} - {{/with}} - ] -{{/inline}} - -{{#*inline 'inferred'}} - infer {{name}} -{{/inline}} - -{{#*inline 'intersection'}} - {{#if needsParens}} - ( - {{/if}} - {{#each types}} - {{#unless @first}} - & - {{/unless}} - {{> type}} - {{/each}} - {{#if needsParens}} - ) - {{/if}} -{{/inline}} - -{{#*inline 'intrinsic'}} - {{name}} -{{/inline}} - -{{#*inline 'literal'}} - {{stringify value}} -{{/inline}} - -{{#*inline 'mapped'}} - { - {{#ifCond readonlyModifier '===' '+'}} - readonly - {{else}} - {{#ifCond readonlyModifier '===' '-'}} - -readonly - {{/ifCond}} - {{/ifCond}} - - [ - {{parameter}} - in - - {{#with parameterType}} - {{>type}} - {{/with}} - - {{#with nameType}} - as - {{>type}} - {{/with}} - - ] - {{#ifCond readonlyModifier '===' '+'}} - ?: - {{else}} - {{#ifCond readonlyModifier '===' '-'}} - -?: - {{else}} - : - {{/ifCond}} - {{/ifCond}} - - {{#with templateType}} - {{>type}} - {{/with}} - - } -{{/inline}} - -{{#*inline 'optional'}} - {{#with elementType}} - {{> type}} - {{/with}} - ? -{{/inline}} - -{{#*inline 'predicate'}} - {{#if asserts}} - asserts - {{/if}} - {{name}} - {{#if targetType}} - is - {{#with targetType}} - {{>type}} - {{/with}} - {{/if}} -{{/inline}} - -{{#*inline 'query'}} - typeof - {{#with queryType}} - {{> type}} - {{/with}} -{{/inline}} - -{{#*inline 'reference'}} - {{#with getReflection }} - - {{name}} - - {{else}} - {{name}} - {{/with}} - {{#if typeArguments}} - < - {{#each typeArguments}} - {{#unless @first}} - , - {{/unless}} - {{> type}} - {{/each}} - > - {{/if}} -{{/inline}} - -{{#*inline 'reflection'}} - {{#if declaration.children}} {{! object literal }} - { - {{#each declaration.children}} - {{#unless @first}} - ; - {{/unless}} - - {{#if getSignature}} - {{#if setSignature}} - {{name}} - : - {{#with getSignature.type}} - {{> type}} - {{else}} - any - {{/with}} - {{else}} - get - {{name}} - (): - {{#with getSignature.type}} - {{> type}} - {{else}} - any - {{/with}} - {{/if}} - {{else}} - {{#if setSignature}} - set - {{name}} - ( - {{! Rather hacky to use each here... but we know there is exactly one. }} - {{#each setSignature.parameters}} - {{name}} - : - {{#with type}} - {{> type}} - {{else}} - any - {{/with}} - {{/each}} - ) - {{else}} - {{name}} - {{#if flags.isOptional }} - ?: - {{else}} - : - {{/if}} - {{#with type}} - {{> type}} - {{else}} - any - {{/with}} - {{/if}} - {{/if}} - {{/each}} - } - {{else if declaration.signatures}} - {{#if (lookup declaration.signatures 1) }} {{! more than one signature}} - { - {{#each declaration.signatures}} - {{> member.signature.title hideName=true}} - {{#unless @last}} - ; - {{/unless}} - {{/each}} - } - {{else}} - {{#if needsParens}} - ( - {{/if}} - {{#with (lookup declaration.signatures '0') }} - {{> member.signature.title hideName=true arrowStyle=true}} - {{/with}} - {{#if needsParens}} - ) - {{/if}} - {{/if}} - {{else}} - {} - {{/if}} -{{/inline}} - -{{#*inline 'rest'}} - ... - {{#with elementType}} - {{> type}} - {{/with}} -{{/inline}} - -{{#*inline 'tuple'}} - [ - {{#each elements}} - {{#unless @first}} - , - {{/unless}} - {{> type}} - {{/each}} - ] -{{/inline}} - -{{#*inline 'template-literal'}} - ` - {{#if head}} - {{head}} - {{/if}} - {{#each tail}} - ${ - {{#with this.[0]}} - {{>type}} - {{/with}} - } - {{#if this.[1]}} - {{this.[1]}} - {{/if}} - {{/each}} - ` -{{/inline}} - -{{#*inline 'typeOperator'}} - {{operator}} - {{#with target}} - {{> type}} - {{/with}} -{{/inline}} - -{{#*inline 'typeParameter'}} - {{name}} -{{/inline}} - -{{#*inline 'union'}} - {{#if needsParens}} - ( - {{/if}} - {{#each types}} - {{#unless @first}} - | - {{/unless}} - {{> type needsParens=true}} - {{/each}} - {{#if needsParens}} - ) - {{/if}} -{{/inline}} - -{{#*inline 'unknown'}} - {{name}} -{{/inline}} - -{{#*inline 'named-tuple-member'}} - {{name}} - {{#if isOptional}} - ?: - {{else}} - : - {{/if}} - {{#with element}} - {{> type}} - {{/with}} -{{/inline}} - -{{#if this}} - {{> (lookup . 'type') }} -{{else}} - void -{{/if}} diff --git a/package.json b/package.json index fb362a4..e6ddca4 100644 --- a/package.json +++ b/package.json @@ -11,12 +11,8 @@ "clean": "rimraf ./lib ./bin", "pretest": "(cd test/dummies/sample-app && npm install --no-audit) && npm run build", "test": "mocha -r ts-node/register test/*", - "docs": "npm run docs:clean && npm run typedoc", - "postinstall": "cp ./documentation/type.hbs ./node_modules/typedoc-plugin-pages/dist/theme/v2/partials/type.hbs", - "docs:clean": "rimraf docs/", + "docs": "typedoc --options typedoc.js", "lint": "eslint src/**/*.ts", - "typedoc": "typedoc --options typedoc.json --plugin typedoc-plugin-pages", - "posttypedoc": "touch docs/.nojekyll", "rotten": "node ./bin/rotten-deps.js --default-expiration 10" }, "author": { @@ -32,6 +28,7 @@ ], "license": "MIT", "devDependencies": { + "@knodes/typedoc-plugin-pages": "^0.22.4", "@types/chai": "~4.3.0", "@types/cli-progress": "^3.9.2", "@types/cli-table": "^0.3.0", @@ -45,12 +42,12 @@ "eslint": "~8.13.0", "eslint-config-airbnb-base": "~15.0.0", "eslint-plugin-import": "~2.26.0", + "lodash": "^4.17.21", "mocha": "~9.2.2", "rimraf": "~3.0.2", "sinon": "~13.0.1", "ts-node": "~10.7.0", "typedoc": "~0.22.14", - "typedoc-plugin-pages": "^1.0.1", "typescript": "~4.6.3" }, "dependencies": { diff --git a/typedoc.js b/typedoc.js new file mode 100644 index 0000000..171dca7 --- /dev/null +++ b/typedoc.js @@ -0,0 +1,22 @@ +module.exports = { + entryPoints: ['src/lib/', 'src/bin/'], + entryPointStrategy: 'expand', + exclude: ['src/.eslintrc'], + out: 'docs/', + includeVersion: true, + githubPages: true, + cleanOutputDir: true, + pluginPages: { + source: './documentation/', + pages: [ + { + title: 'How To', + children: [ + { title: 'Contribute to these docs', source: './how-to/contribute-to-docs.md' }, + { title: 'Create a config file', source: './how-to/create-a-config-file.md' }, + { title: 'Release', source: './how-to/create-a-config-file.md' }, + ], + }, + ], + }, +}; diff --git a/typedoc.json b/typedoc.json deleted file mode 100644 index 0c4da77..0000000 --- a/typedoc.json +++ /dev/null @@ -1,25 +0,0 @@ -{ - "entryPoints": [ - "src/lib/", - "src/bin/" - ], - "exclude": [ - "src/.eslintrc" - ], - "out": "docs/", - "includeVersion": true, - "theme": "pages-plugin", - "pages": { - "groups": [ - { - "title": "How To", - "pages": [ - { "title": "Contibute to the documentation", "source": "./documentation/how-to/contribute-to-docs.md" }, - { "title": "Create and use a configuration file", "source": "./documentation/how-to/create-a-config-file.md" }, - { "title": "Release a new version of Rotten Deps", "source": "./documentation/how-to/release.md" } - ] - } - ], - "output": "pages" - } -} diff --git a/yarn.lock b/yarn.lock index ef908f0..4064fe3 100644 --- a/yarn.lock +++ b/yarn.lock @@ -43,6 +43,21 @@ resolved "https://registry.yarnpkg.com/@humanwhocodes/object-schema/-/object-schema-1.2.1.tgz#b520529ec21d8e5945a1851dfd1c32e94e39ff45" integrity sha512-ZnQMnLV4e7hDlUvw8H+U8ASL02SS2Gn6+9Ac3wGGLIe7+je2AeAOxPY+izIPJDfFDb7eDjev0Us8MO1iFRN8hA== +"@knodes/typedoc-plugin-pages@^0.22.4": + version "0.22.4" + resolved "https://registry.yarnpkg.com/@knodes/typedoc-plugin-pages/-/typedoc-plugin-pages-0.22.4.tgz#addf306556100b20926acf17d998fe6f7bd14f48" + integrity sha512-JxXMJrF+npGCH/0ug4UG+jWIHkHTQfkJDXpSor2GMWzd5MMTOw5sn/hdKESeWoPLt9GqG4a1dKkD7ZC5HH4v0A== + dependencies: + "@knodes/typedoc-pluginutils" "~0.22.4" + +"@knodes/typedoc-pluginutils@~0.22.4": + version "0.22.4" + resolved "https://registry.yarnpkg.com/@knodes/typedoc-pluginutils/-/typedoc-pluginutils-0.22.4.tgz#899b9ff54851056b963dd1f1ef3552b96e199253" + integrity sha512-qLkwf14IIoTXKnlNjZPnEz5IupFDfAaa+ggPjQE1ZaiElA0o4PGgq58z0dW8U8WVTVNvD4nSN7jFLqB599jt7Q== + dependencies: + pkg-up "^3.1.0" + semver "^7.3.5" + "@nodelib/fs.scandir@2.1.4": version "2.1.4" resolved "https://registry.yarnpkg.com/@nodelib/fs.scandir/-/fs.scandir-2.1.4.tgz#d4b3549a5db5de2683e0c1071ab4f140904bbf69" @@ -520,11 +535,6 @@ colors@1.0.3: resolved "https://registry.yarnpkg.com/colors/-/colors-1.0.3.tgz#0433f44d809680fdeb60ed260f1b0c262e82a40b" integrity sha1-BDP0TYCWgP3rYO0mDxsMJi6CpAs= -compare-versions@^3.6.0: - version "3.6.0" - resolved "https://registry.yarnpkg.com/compare-versions/-/compare-versions-3.6.0.tgz#1a5689913685e5a87637b8d3ffca75514ec41d62" - integrity sha512-W6Af2Iw1z4CB7q4uU4hv646dW9GQuBM+YpC0UvUCWSD8w90SJjp+ujJuXaEMtAXBtSqGfMPuFOVn4/+FlaqfBA== - concat-map@0.0.1: version "0.0.1" resolved "https://registry.yarnpkg.com/concat-map/-/concat-map-0.0.1.tgz#d8a96bd77fd68df7793a73036a3ba0d5405d477b" @@ -913,6 +923,13 @@ find-up@^2.1.0: dependencies: locate-path "^2.0.0" +find-up@^3.0.0: + version "3.0.0" + resolved "https://registry.yarnpkg.com/find-up/-/find-up-3.0.0.tgz#49169f1d7993430646da61ecc5ae355c21c97b73" + integrity sha512-1yD6RmLI1XBfxugvORwlck6f75tYL+iR0jqwsOrOxMZyGYqUuDhJ0l4AXdO1iX/FTs9cBAMEk1gWSEx1kSbylg== + dependencies: + locate-path "^3.0.0" + flat-cache@^3.0.4: version "3.0.4" resolved "https://registry.yarnpkg.com/flat-cache/-/flat-cache-3.0.4.tgz#61b0338302b2fe9f957dcc32fc2a87f1c3048b11" @@ -1324,6 +1341,14 @@ locate-path@^2.0.0: p-locate "^2.0.0" path-exists "^3.0.0" +locate-path@^3.0.0: + version "3.0.0" + resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-3.0.0.tgz#dbec3b3ab759758071b58fe59fc41871af21400e" + integrity sha512-7AO748wWnIhNqAuaty2ZWHkQHRSNfPVIsPIfwEOWO22AmaoVrWavlOcMR5nzTLNYvp36X220/maaRsrec1G65A== + dependencies: + p-locate "^3.0.0" + path-exists "^3.0.0" + locate-path@^6.0.0: version "6.0.0" resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-6.0.0.tgz#55321eb309febbc59c4801d931a72452a681d286" @@ -1341,6 +1366,11 @@ lodash.merge@^4.6.2: resolved "https://registry.yarnpkg.com/lodash.merge/-/lodash.merge-4.6.2.tgz#558aa53b43b661e1925a0afdfa36a9a1085fe57a" integrity sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ== +lodash@^4.17.21: + version "4.17.21" + resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz#679591c564c3bffaae8454cf0b3df370c3d6911c" + integrity sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg== + log-symbols@4.1.0: version "4.1.0" resolved "https://registry.yarnpkg.com/log-symbols/-/log-symbols-4.1.0.tgz#3fbdbb95b4683ac9fc785111e792e558d4abd503" @@ -1363,7 +1393,7 @@ lru-cache@^6.0.0: dependencies: yallist "^4.0.0" -lunr@^2.3.8, lunr@^2.3.9: +lunr@^2.3.9: version "2.3.9" resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.9.tgz#18b123142832337dd6e964df1a5a7707b25d35e1" integrity sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow== @@ -1569,6 +1599,13 @@ p-limit@^1.1.0: dependencies: p-try "^1.0.0" +p-limit@^2.0.0: + version "2.3.0" + resolved "https://registry.yarnpkg.com/p-limit/-/p-limit-2.3.0.tgz#3dd33c647a214fdfffd835933eb086da0dc21db1" + integrity sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w== + dependencies: + p-try "^2.0.0" + p-limit@^3.0.2: version "3.0.2" resolved "https://registry.yarnpkg.com/p-limit/-/p-limit-3.0.2.tgz#1664e010af3cadc681baafd3e2a437be7b0fb5fe" @@ -1583,6 +1620,13 @@ p-locate@^2.0.0: dependencies: p-limit "^1.1.0" +p-locate@^3.0.0: + version "3.0.0" + resolved "https://registry.yarnpkg.com/p-locate/-/p-locate-3.0.0.tgz#322d69a05c0264b25997d9f40cd8a891ab0064a4" + integrity sha512-x+12w/To+4GFfgJhBEpiDcLozRJGegY+Ei7/z0tSLkMmxGZNybVMSfWj9aJn8Z5Fc7dBUNJOOVgPv2H7IwulSQ== + dependencies: + p-limit "^2.0.0" + p-locate@^5.0.0: version "5.0.0" resolved "https://registry.yarnpkg.com/p-locate/-/p-locate-5.0.0.tgz#83c8315c6785005e3bd021839411c9e110e6d834" @@ -1664,6 +1708,13 @@ picomatch@^2.3.1: resolved "https://registry.yarnpkg.com/picomatch/-/picomatch-2.3.1.tgz#3ba3833733646d9d3e4995946c1365a67fb07a42" integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA== +pkg-up@^3.1.0: + version "3.1.0" + resolved "https://registry.yarnpkg.com/pkg-up/-/pkg-up-3.1.0.tgz#100ec235cc150e4fd42519412596a28512a0def5" + integrity sha512-nDywThFk1i4BQK4twPQ6TA4RT8bDY96yeuCVBWL3ePARCiEKDRSrNGbFIgUJpLp+XeIR65v8ra7WuJOFUBtkMA== + dependencies: + find-up "^3.0.0" + prelude-ls@^1.2.1: version "1.2.1" resolved "https://registry.yarnpkg.com/prelude-ls/-/prelude-ls-1.2.1.tgz#debc6489d7a6e6b0e7611888cec880337d316396" @@ -1962,21 +2013,6 @@ type-fest@^0.20.2: resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-0.20.2.tgz#1bf207f4b28f91583666cb5fbd327887301cd5f4" integrity sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ== -typedoc-default-themes@^0.10.1: - version "0.10.2" - resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.10.2.tgz#743380a80afe62c5ef92ca1bd4abe2ac596be4d2" - integrity sha512-zo09yRj+xwLFE3hyhJeVHWRSPuKEIAsFK5r2u47KL/HBKqpwdUSanoaz5L34IKiSATFrjG5ywmIu98hPVMfxZg== - dependencies: - lunr "^2.3.8" - -typedoc-plugin-pages@^1.0.1: - version "1.1.0" - resolved "https://registry.yarnpkg.com/typedoc-plugin-pages/-/typedoc-plugin-pages-1.1.0.tgz#c51367404b87b9b2e8cc440a53ff641c42b9fd7a" - integrity sha512-pmCCp3G2aCeEWb829dcVe9Pl+pI5OsaqfyrkEutcAHZi6IMVfQ5G5NdrkIkFCGhJU/DY04rGrVdynWqnaO5/jg== - dependencies: - compare-versions "^3.6.0" - typedoc-default-themes "^0.10.1" - typedoc@~0.22.14: version "0.22.14" resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.22.14.tgz#c690677c31bc1dd5618caffc001bfa8554c4c02f"