From 4b1c8bc45b84aa6f635aee070c349cc5db944c1c Mon Sep 17 00:00:00 2001 From: Siddharth VP Date: Thu, 2 Sep 2021 23:08:06 +0530 Subject: [PATCH] lint markdown files using markdownlint --- .markdownlint-cli2.jsonc | 14 ++ CHANGELOG.md | 15 +- package-lock.json | 199 +++++++++++++++++- package.json | 7 +- website/docs/1-getting-started.md | 5 - website/docs/10-bulk-processing.md | 6 +- .../docs/11-integration-with-other-apis.md | 18 +- website/docs/12-logging.md | 2 +- website/docs/14-developing.md | 13 +- website/docs/3-other-basic-operations.md | 2 - website/docs/4-handling-query-continuation.md | 10 +- website/docs/5-direct-api-calls.md | 2 +- website/docs/9-working-with-wikitext.md | 10 +- 13 files changed, 261 insertions(+), 42 deletions(-) create mode 100644 .markdownlint-cli2.jsonc diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000..57191a5 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,14 @@ +{ + "config": { + "line-length": false, + "header-increment": false, + "first-line-heading": false, + "no-inline-html": false, + "ol-prefix": false, + "no-hard-tabs": false + }, + "globs": [ + "*.md", + "website/docs/*.md" + ] +} diff --git a/CHANGELOG.md b/CHANGELOG.md index 46b61dc..d7c9449 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,24 +1,25 @@ Only breaking changes, deprecations and the like are documented in this change log. #### 0.11.0 + - mwn#queryAuthors() now requires `getSiteInfo()` to have run first. Also, it is deprecated in favour of using the `queryAuthors()` method on a page object. #### 0.10.0 -- `loginGetToken()` is now deprecated in favour of `login()` which will now fetch tokens as well. -- TypeScript source files are dropped from the npm package, per the standard practice followed in TypeScript libraries. This should not actually break anything. +- `loginGetToken()` is now deprecated in favour of `login()` which will now fetch tokens as well. +- TypeScript source files are dropped from the npm package, per the standard practice followed in TypeScript libraries. This should not actually break anything. #### 0.9.0 BREAKING CHANGES: -- [mwn#rawRequest](https://tools-static.wmflabs.org/mwn/docs/classes/_bot_.mwn.html#rawrequest) now returns the `AxiosResponse` object directly, rather than the `data` part of `AxiosResponse`. -- In cases of error, the shape of the error thrown by [mwn#request](https://tools-static.wmflabs.org/mwn/docs/classes/_bot_.mwn.html#request) is different. - - Earlier: `error.response` was the API response data along with response and request objects, the former making it a cyclic object. - - Now: `error.response` is an object with fields {data, headers, status, statusText} +- [mwn#rawRequest](https://tools-static.wmflabs.org/mwn/docs/classes/_bot_.mwn.html#rawrequest) now returns the `AxiosResponse` object directly, rather than the `data` part of `AxiosResponse`. +- In cases of error, the shape of the error thrown by [mwn#request](https://tools-static.wmflabs.org/mwn/docs/classes/_bot_.mwn.html#request) is different. + - Earlier: `error.response` was the API response data along with response and request objects, the former making it a cyclic object. + - Now: `error.response` is an object with fields {data, headers, status, statusText} #### 0.8.0 BREAKING CHANGES: -- For imports in JavaScript, use `const {mwn} = require('mwn');` instead of `const mwn = require('mwn');` +- For imports in JavaScript, use `const {mwn} = require('mwn');` instead of `const mwn = require('mwn');` diff --git a/package-lock.json b/package-lock.json index fa1a920..ad381b2 100644 --- a/package-lock.json +++ b/package-lock.json @@ -37,6 +37,7 @@ "eslint-plugin-chai-expect": "^2.2.0", "husky": "^4.3.8", "lint-staged": "^11.0.0", + "markdownlint-cli2": "^0.3.0", "mocha": "^8.2.1", "mocha-chai-jest-snapshot": "^1.1.2", "nock": "^13.1.0", @@ -2234,6 +2235,15 @@ "node": ">=8.6" } }, + "node_modules/entities": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-2.1.0.tgz", + "integrity": "sha512-hCx1oky9PFrJ611mf0ifBLBRW8lUUVRlFolb5gWRfIELabBlbp9xZvrqZLZAs+NxFnbfQoeGd8wDkygjg7U85w==", + "dev": true, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, "node_modules/error-ex": { "version": "1.3.2", "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz", @@ -3391,9 +3401,9 @@ } }, "node_modules/globby": { - "version": "11.0.2", - "resolved": "https://registry.npmjs.org/globby/-/globby-11.0.2.tgz", - "integrity": "sha512-2ZThXDvvV8fYFRVIxnrMQBipZQDr7MxKAmQK1vujaj9/7eF0efG7BPUKJ7jP7G5SLF37xKDXvO4S/KKLj/Z0og==", + "version": "11.0.4", + "resolved": "https://registry.npmjs.org/globby/-/globby-11.0.4.tgz", + "integrity": "sha512-9O4MVG9ioZJ08ffbcyVYyLOJLk5JQ688pJ4eMGLpdWLHq/Wr1D9BlriLQyL0E+jbkuePVZXYFj47QM/v093wHg==", "dev": true, "dependencies": { "array-union": "^2.1.0", @@ -4998,6 +5008,15 @@ "integrity": "sha1-HADHQ7QzzQpOgHWPe2SldEDZ/wA=", "dev": true }, + "node_modules/linkify-it": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-3.0.2.tgz", + "integrity": "sha512-gDBO4aHNZS6coiZCKVhSNh43F9ioIL4JwRjLZPkoLIY4yZFwg264Y5lu2x6rb1Js42Gh6Yqm2f6L2AJcnkzinQ==", + "dev": true, + "dependencies": { + "uc.micro": "^1.0.1" + } + }, "node_modules/lint-staged": { "version": "11.0.0", "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-11.0.0.tgz", @@ -5535,6 +5554,77 @@ "node": ">=0.10.0" } }, + "node_modules/markdownlint-cli2": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.3.0.tgz", + "integrity": "sha512-0nmB8MMqxwTolfkOaGW9RLqkBVG6DW6oBTyDKd3SP+7e8FPhihg6KBqpz1puj37C2Wd3POS98xiE1GljEVNyHw==", + "dev": true, + "dependencies": { + "globby": "~11.0.4", + "markdownlint": "~0.24.0", + "markdownlint-cli2-formatter-default": "^0.0.2", + "markdownlint-rule-helpers": "~0.15.0", + "micromatch": "~4.0.4", + "strip-json-comments": "~3.1.1", + "yaml": "~1.10.2" + }, + "bin": { + "markdownlint-cli2": "markdownlint-cli2.js", + "markdownlint-cli2-fix": "markdownlint-cli2-fix.js" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/markdownlint-cli2-formatter-default": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/markdownlint-cli2-formatter-default/-/markdownlint-cli2-formatter-default-0.0.2.tgz", + "integrity": "sha512-jIz1X3SIC8sX4NDFqQFUXL+JEtfnDoN4i+xocEu+etcxGX455pHb6sx86f/yVk4mKJ2o7aNe2ydSx9an22BfBg==", + "dev": true, + "peerDependencies": { + "markdownlint-cli2": ">=0.0.4" + } + }, + "node_modules/markdownlint-cli2/node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "node_modules/markdownlint-cli2/node_modules/markdown-it": { + "version": "12.2.0", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-12.2.0.tgz", + "integrity": "sha512-Wjws+uCrVQRqOoJvze4HCqkKl1AsSh95iFAeQDwnyfxM09divCBSXlDR1uTvyUP3Grzpn4Ru8GeCxYPM8vkCQg==", + "dev": true, + "dependencies": { + "argparse": "^2.0.1", + "entities": "~2.1.0", + "linkify-it": "^3.0.1", + "mdurl": "^1.0.1", + "uc.micro": "^1.0.5" + }, + "bin": { + "markdown-it": "bin/markdown-it.js" + } + }, + "node_modules/markdownlint-cli2/node_modules/markdownlint": { + "version": "0.24.0", + "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.24.0.tgz", + "integrity": "sha512-OJIGsGFV/rC9irI5E1FMy6v9hdACSwaa+EN3224Y5KG8zj2EYzdHOw0pOJovIYmjNfEZ9BtxUY4P7uYHTSNnbQ==", + "dev": true, + "dependencies": { + "markdown-it": "12.2.0" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/markdownlint-cli2/node_modules/markdownlint-rule-helpers": { + "version": "0.15.0", + "resolved": "https://registry.npmjs.org/markdownlint-rule-helpers/-/markdownlint-rule-helpers-0.15.0.tgz", + "integrity": "sha512-A+9mswc3m/kkqpJCqntmte/1VKhDJ+tjZsERLz5L4h/Qr7ht2/BkGkgY5E7/wsxIhcpl+ctIfz+oS3PQrMOB2w==", + "dev": true + }, "node_modules/marked": { "version": "2.0.7", "resolved": "https://registry.npmjs.org/marked/-/marked-2.0.7.tgz", @@ -5547,6 +5637,12 @@ "node": ">= 8.16.2" } }, + "node_modules/mdurl": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz", + "integrity": "sha1-/oWy7HWlkDfyrf7BAP1sYBdhFS4=", + "dev": true + }, "node_modules/merge-stream": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz", @@ -8749,6 +8845,12 @@ "node": ">=4.2.0" } }, + "node_modules/uc.micro": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-1.0.6.tgz", + "integrity": "sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==", + "dev": true + }, "node_modules/uglify-js": { "version": "3.13.8", "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.13.8.tgz", @@ -11062,6 +11164,12 @@ "ansi-colors": "^4.1.1" } }, + "entities": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-2.1.0.tgz", + "integrity": "sha512-hCx1oky9PFrJ611mf0ifBLBRW8lUUVRlFolb5gWRfIELabBlbp9xZvrqZLZAs+NxFnbfQoeGd8wDkygjg7U85w==", + "dev": true + }, "error-ex": { "version": "1.3.2", "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz", @@ -11952,9 +12060,9 @@ } }, "globby": { - "version": "11.0.2", - "resolved": "https://registry.npmjs.org/globby/-/globby-11.0.2.tgz", - "integrity": "sha512-2ZThXDvvV8fYFRVIxnrMQBipZQDr7MxKAmQK1vujaj9/7eF0efG7BPUKJ7jP7G5SLF37xKDXvO4S/KKLj/Z0og==", + "version": "11.0.4", + "resolved": "https://registry.npmjs.org/globby/-/globby-11.0.4.tgz", + "integrity": "sha512-9O4MVG9ioZJ08ffbcyVYyLOJLk5JQ688pJ4eMGLpdWLHq/Wr1D9BlriLQyL0E+jbkuePVZXYFj47QM/v093wHg==", "dev": true, "requires": { "array-union": "^2.1.0", @@ -13164,6 +13272,15 @@ "integrity": "sha1-HADHQ7QzzQpOgHWPe2SldEDZ/wA=", "dev": true }, + "linkify-it": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-3.0.2.tgz", + "integrity": "sha512-gDBO4aHNZS6coiZCKVhSNh43F9ioIL4JwRjLZPkoLIY4yZFwg264Y5lu2x6rb1Js42Gh6Yqm2f6L2AJcnkzinQ==", + "dev": true, + "requires": { + "uc.micro": "^1.0.1" + } + }, "lint-staged": { "version": "11.0.0", "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-11.0.0.tgz", @@ -13568,12 +13685,76 @@ "object-visit": "^1.0.0" } }, + "markdownlint-cli2": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.3.0.tgz", + "integrity": "sha512-0nmB8MMqxwTolfkOaGW9RLqkBVG6DW6oBTyDKd3SP+7e8FPhihg6KBqpz1puj37C2Wd3POS98xiE1GljEVNyHw==", + "dev": true, + "requires": { + "globby": "~11.0.4", + "markdownlint": "~0.24.0", + "markdownlint-cli2-formatter-default": "^0.0.2", + "markdownlint-rule-helpers": "~0.15.0", + "micromatch": "~4.0.4", + "strip-json-comments": "~3.1.1", + "yaml": "~1.10.2" + }, + "dependencies": { + "argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true + }, + "markdown-it": { + "version": "12.2.0", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-12.2.0.tgz", + "integrity": "sha512-Wjws+uCrVQRqOoJvze4HCqkKl1AsSh95iFAeQDwnyfxM09divCBSXlDR1uTvyUP3Grzpn4Ru8GeCxYPM8vkCQg==", + "dev": true, + "requires": { + "argparse": "^2.0.1", + "entities": "~2.1.0", + "linkify-it": "^3.0.1", + "mdurl": "^1.0.1", + "uc.micro": "^1.0.5" + } + }, + "markdownlint": { + "version": "0.24.0", + "resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.24.0.tgz", + "integrity": "sha512-OJIGsGFV/rC9irI5E1FMy6v9hdACSwaa+EN3224Y5KG8zj2EYzdHOw0pOJovIYmjNfEZ9BtxUY4P7uYHTSNnbQ==", + "dev": true, + "requires": { + "markdown-it": "12.2.0" + } + }, + "markdownlint-rule-helpers": { + "version": "0.15.0", + "resolved": "https://registry.npmjs.org/markdownlint-rule-helpers/-/markdownlint-rule-helpers-0.15.0.tgz", + "integrity": "sha512-A+9mswc3m/kkqpJCqntmte/1VKhDJ+tjZsERLz5L4h/Qr7ht2/BkGkgY5E7/wsxIhcpl+ctIfz+oS3PQrMOB2w==", + "dev": true + } + } + }, + "markdownlint-cli2-formatter-default": { + "version": "0.0.2", + "resolved": "https://registry.npmjs.org/markdownlint-cli2-formatter-default/-/markdownlint-cli2-formatter-default-0.0.2.tgz", + "integrity": "sha512-jIz1X3SIC8sX4NDFqQFUXL+JEtfnDoN4i+xocEu+etcxGX455pHb6sx86f/yVk4mKJ2o7aNe2ydSx9an22BfBg==", + "dev": true, + "requires": {} + }, "marked": { "version": "2.0.7", "resolved": "https://registry.npmjs.org/marked/-/marked-2.0.7.tgz", "integrity": "sha512-BJXxkuIfJchcXOJWTT2DOL+yFWifFv2yGYOUzvXg8Qz610QKw+sHCvTMYwA+qWGhlA2uivBezChZ/pBy1tWdkQ==", "dev": true }, + "mdurl": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-1.0.1.tgz", + "integrity": "sha1-/oWy7HWlkDfyrf7BAP1sYBdhFS4=", + "dev": true + }, "merge-stream": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz", @@ -16082,6 +16263,12 @@ "integrity": "sha512-B3ZIOf1IKeH2ixgHhj6la6xdwR9QrLC5d1VKeCSY4tvkqhF2eqd9O7txNlS0PO3GrBAFIdr3L1ndNwteUbZLYg==", "dev": true }, + "uc.micro": { + "version": "1.0.6", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-1.0.6.tgz", + "integrity": "sha512-8Y75pvTYkLJW2hWQHXxoqRgV7qb9B+9vFEtidML+7koHUFapnVJAZ6cKs+Qjz5Aw3aZWHMC6u0wJE3At+nSGwA==", + "dev": true + }, "uglify-js": { "version": "3.13.8", "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.13.8.tgz", diff --git a/package.json b/package.json index 56af0cf..ef5ad4b 100644 --- a/package.json +++ b/package.json @@ -9,7 +9,8 @@ "format": "prettier --write .", "build": "tsc || echo", "quickbuild": "babel src --extensions \".ts\" --out-dir build", - "lint": "eslint src tests", + "lint": "eslint src tests && markdownlint-cli2", + "lint:fix": "eslint --fix src tests && markdownlint-cli2-fix", "test:testwiki": "cd tests && mocha bot.test.js category.test.js file.test.js login.bot.test.js oauth.test.js page.test.js suppl.bot.test.js user.test.js wikitext.test.js", "setuplocalwiki": "cd tests/docker && bash main.sh", "test:localwiki": "cd tests && mocha edit.bot.test.js user.edit.test.js errors.test.js shutoff.test.js core.test.js", @@ -66,6 +67,7 @@ "eslint-plugin-chai-expect": "^2.2.0", "husky": "^4.3.8", "lint-staged": "^11.0.0", + "markdownlint-cli2": "^0.3.0", "mocha": "^8.2.1", "mocha-chai-jest-snapshot": "^1.1.2", "nock": "^13.1.0", @@ -83,6 +85,7 @@ } }, "lint-staged": { - "*.ts(x)?": "prettier --write" + "*.ts(x)?": "prettier --write", + "*.md": "markdownlint-cli2-fix" } } diff --git a/website/docs/1-getting-started.md b/website/docs/1-getting-started.md index 38f995f..e7db017 100644 --- a/website/docs/1-getting-started.md +++ b/website/docs/1-getting-started.md @@ -1,12 +1,7 @@ ---- -sidebar_position: 1 ---- - # Getting started Installation: `npm install mwn` - Importing mwn: In JavaScript: diff --git a/website/docs/10-bulk-processing.md b/website/docs/10-bulk-processing.md index d03c134..89b5167 100644 --- a/website/docs/10-bulk-processing.md +++ b/website/docs/10-bulk-processing.md @@ -1,6 +1,7 @@ # Bulk processing ### continuedQuery / continuedQueryGen + See [Handling query continuation](/docs/handling-query-continuation) for more details. continuedQuery returns a promised resolved with the array of all individual API response. @@ -8,6 +9,7 @@ continuedQuery returns a promised resolved with the array of all individual API Use of `continuedQueryGen` is recommended since continuedQuery will fetch the results of all the API calls before it begins to do anything with the results. `continuedQueryGen` gets the result of each API call and processes them one at a time. ### massQuery / massQueryGen + MediaWiki sets a limit of 500 (50 for non-bots) on the number of pages that can be queried in a single API call. To query more than that, `massQuery` or `massQueryGen` can be used. This splits the page list into batches of 500 and sends individual queries and returns a promise resolved with the array of all individual API call responses. Example: get the protection status of a large number of pages: @@ -33,7 +35,7 @@ massQueryGen is the generator equivalent that yields each API response as when t Perform asynchronous tasks (involving API usage) over a number of pages (or other arbitrary items). `batchOperation` uses a default concurrency of 5. Customise this according to how expensive the API operation is. Higher concurrency limits could lead to more frequent API errors. -- `batchOperation(pageList, workerFunction, concurrency, maxRetries)`: The `workerFunction` must return a promise. +- `batchOperation(pageList, workerFunction, concurrency, maxRetries)`: The `workerFunction` must return a promise. ```js bot.batchOperation( @@ -48,7 +50,7 @@ bot.batchOperation( ); ``` -- `bot.seriesBatchOperation(pageList, workerFunction, sleepDuration, retries)` can be used for serial operations, with a sleep duration between each task (default 5 seconds). +- `bot.seriesBatchOperation(pageList, workerFunction, sleepDuration, retries)` can be used for serial operations, with a sleep duration between each task (default 5 seconds). ```js bot.seriesBatchOperation( diff --git a/website/docs/11-integration-with-other-apis.md b/website/docs/11-integration-with-other-apis.md index be91f68..312ad91 100644 --- a/website/docs/11-integration-with-other-apis.md +++ b/website/docs/11-integration-with-other-apis.md @@ -3,8 +3,10 @@ Apart from the [MediaWiki API](https://www.mediawiki.org/wiki/API:Main_page), Mwn integrates with a few other APIs: ### ORES -See https://ores.wikimedia.org/ for details. + +See for details. Get ORES scores for revisions: + ```js await bot.oresQueryRevisions( 'https://ores.wikimedia.org/', // ORES endpoint URL @@ -13,9 +15,10 @@ await bot.oresQueryRevisions( ); ``` - ### EventStreams -See https://wikitech.wikimedia.org/wiki/Event_Platform/EventStreams + +See + ```js const stream = bot.stream(['recentchange']); stream.addListener( @@ -32,17 +35,21 @@ stream.addListener( ``` ### PageViews -See https://wikitech.wikimedia.org/wiki/Analytics/AQS/Pageviews + +See + ```js const page = new bot.page('Deaths in 2020'); const pageViewData = await page.pageViews({ // See https://mwn.toolforge.org/docs/api/interfaces/pageviewoptions.html for available options }); ``` + The [PageViewOptions](https://mwn.toolforge.org/docs/api/interfaces/pageviewoptions.html) argument is optional. Return type is Promise<PageViewData[]>. ### WikiWho -See https://wikiwho.wmflabs.org/ + +See Fetch the list of top contributors to an article. Available for limited number of Wikipedias. @@ -50,4 +57,5 @@ Fetch the list of top contributors to an article. Available for limited number o const page = new bot.page('Lorem ipsum'); const contributorData = await page.queryAuthors(); ``` + Return type is Promise<AuthorshipData>. diff --git a/website/docs/12-logging.md b/website/docs/12-logging.md index 2c64784..3ddc7ba 100644 --- a/website/docs/12-logging.md +++ b/website/docs/12-logging.md @@ -11,4 +11,4 @@ log('[W] Warning message'); log('[E] Error message'); ``` -Based on the character within `[]`, colouration happens automatically. +Based on the character within `[]`, colouration happens automatically. diff --git a/website/docs/14-developing.md b/website/docs/14-developing.md index 4afe697..ed77750 100644 --- a/website/docs/14-developing.md +++ b/website/docs/14-developing.md @@ -13,6 +13,7 @@ Build: run `npm run build`. This generates the JS files in `build` from the Type ### Tests Mwn has a comprehensive test suite that uses [mocha](https://www.npmjs.com/package/mocha) runner and [chai](https://www.npmjs.com/package/chai) for expectations. Tests should be added for all bug fixes and feature changes. There are three types of tests: + 1. Tests that don't require a wiki: `npm run test:nowiki` 2. Tests that are based on [testwiki](https://test.wikipedia.org/): `npm run test:testwiki` @@ -24,17 +25,19 @@ You need to setup botpassword login credentials for testwiki to run these tests. "password": "" } ``` -No edits (or any other type of write action) will be done on testwiki. The credentials are only for reading content. + +No edits (or any other type of write action) will be done on testwiki. The credentials are only for reading content. 3. Tests that require a local wiki: `npm run test:localwiki` For these, you need to spin up a local MediaWiki installation: - - Ensure that you have docker and docker-compose installed. If you're using Windows, you need to use WSL 2 and follow the steps at https://docs.docker.com/desktop/windows/wsl/ to link Docker Desktop to WSL. - - Run `npm run setuplocalwiki` + +- Ensure that you have docker and docker-compose installed. If you're using Windows, you need to use WSL 2 and follow the steps at to link Docker Desktop to WSL. +- Run `npm run setuplocalwiki` If all goes well, you should now have a wiki up and running at [http://localhost:8080](http://localhost:8080). Sign in with username `Wikiuser` and password `wikipassword` (See [the setup.sh script](https://github.com/siddharthvp/mwn/blob/master/tests/docker/setup.sh) for other setup details.) -**Troubleshooting**: If your local MW install fails with an error that a db table doesn't exist, try changing the sleep duration in https://github.com/siddharthvp/mwn/blob/master/tests/docker/main.sh#L2 to a higher value. The MariaDB database doesn't start accepting connections until it has initialised (time needed for that could be more on certain systems). +**Troubleshooting**: If your local MW install fails with an error that a db table doesn't exist, try changing the sleep duration in to a higher value. The MariaDB database doesn't start accepting connections until it has initialised (time needed for that could be more on certain systems). All tests except the ones that depend on testwiki will also be run automatically via GitHub Actions when you create a PR, so no worries if you're having trouble with local MW installation. @@ -42,4 +45,4 @@ All tests except the ones that depend on testwiki will also be run automatically When adding new features, please also update the corresponding documentation in `website/docs`. Documentation can be previewed by running `npm run docs` which starts a server at [http://localhost:3000](http://localhost:3000) that updates the rendered docs live as they are edited. -The docs are hosted on https://mwn.toolforge.org and generated via [Docusaurus](https://docusaurus.io/). Build and deployment take place via GitHub Actions whenever they're updated in the master branch. +The docs are hosted on and generated via [Docusaurus](https://docusaurus.io/). Build and deployment take place via GitHub Actions whenever they're updated in the master branch. diff --git a/website/docs/3-other-basic-operations.md b/website/docs/3-other-basic-operations.md index f8f526b..e9b8277 100644 --- a/website/docs/3-other-basic-operations.md +++ b/website/docs/3-other-basic-operations.md @@ -70,5 +70,3 @@ let page = new bot.page('Main Page'); See [list of methods available on page object](https://mwn.toolforge.org/docs/api/interfaces/mwnpage.html). [Files](https://mwn.toolforge.org/docs/api/interfaces/mwnfile.html) and [categories](https://mwn.toolforge.org/docs/api/interfaces/mwncategory.html) have their own subclasses that add a few additional methods. - - diff --git a/website/docs/4-handling-query-continuation.md b/website/docs/4-handling-query-continuation.md index 57272c4..0bb0908 100644 --- a/website/docs/4-handling-query-continuation.md +++ b/website/docs/4-handling-query-continuation.md @@ -21,10 +21,10 @@ for await (let json of bot.continuedQueryGen({ Specialised derivatives exist to fulfill common needs: -- `new bot.page('Page name').historyGen()` - fetch page history -- `new bot.page('Page name').logsGen()` - fetch page logs -- `new bot.category('Page name').membersGen()` - fetch category members -- `new bot.user('User name').contribsGen()` - fetch user contributions -- `new bot.user('User name').logsGen()` - fetch user logs +- `new bot.page('Page name').historyGen()` - fetch page history +- `new bot.page('Page name').logsGen()` - fetch page logs +- `new bot.category('Page name').membersGen()` - fetch category members +- `new bot.user('User name').contribsGen()` - fetch user contributions +- `new bot.user('User name').logsGen()` - fetch user logs Every method with a name that ends in `Gen` is an async generator. diff --git a/website/docs/5-direct-api-calls.md b/website/docs/5-direct-api-calls.md index 0744003..a25842a 100644 --- a/website/docs/5-direct-api-calls.md +++ b/website/docs/5-direct-api-calls.md @@ -1,6 +1,6 @@ # Direct API calls -The `request` method is for directly querying the API. See [mw:API](https://www.mediawiki.org/wiki/API:Main_page) for options. +The `request` method is for directly querying the API. See [mw:API](https://www.mediawiki.org/wiki/API:Main_page) for options. You can create and test your queries in [Special:ApiSandbox](https://www.mediawiki.org/wiki/Special:ApiSandbox). However, note that ApiSandbox uses json formatversion=1 by default whereas Mwn defaults to formatversion=2. So you should set formatversion: 2 in the format=json options, otherwise the output can be formatted differently for certain API endpoints. Use of the legacy formatversion is not recommended. diff --git a/website/docs/9-working-with-wikitext.md b/website/docs/9-working-with-wikitext.md index 66eeb6b..28e2245 100644 --- a/website/docs/9-working-with-wikitext.md +++ b/website/docs/9-working-with-wikitext.md @@ -2,11 +2,14 @@ Mwn can be used for common wikitext parsing needs, though there is no AST-based parsing. -Create object for further operations: +Create object for further operations: + ```js let wkt = new bot.wikitext('This is some wikitext with [[links]] and {{templates|with=params}}.'); ``` + Parse links: + ```js // This requires the bot object to have the namespace data of the wiki available. // Either the bot should be logged in, or run bot.getSiteInfo() @@ -18,17 +21,21 @@ wkt.files // => [] ``` Parse templates: + ```js wkt.parseTemplates() // -> [Template {wikitext: '{{templates|with=params}}', parameters: [ Parameter {name: 'with', value: 'params', wikitext: '|with=params'}] ], name: 'Templates' }] ``` + `parseTemplates` can optionally take a [TemplateConfig](https://mwn.toolforge.org/docs/api/interfaces/templateconfig.html) object as argument. It can also be used without constructing a bot.wikitext object, as: + ```js bot.wikitext.parseTemplates() ``` Parse simple tables: + ```js const parsedTable = bot.wikitext.parseTable(` {| class="wikitable sortable" @@ -41,4 +48,5 @@ const parsedTable = bot.wikitext.parseTable(` |} `); ``` + The result is an array of plain JS objects, each having the table headers as keys.