From c8587797a11f366ff9abc031b2f79af66c167e67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Belin?= Date: Sun, 16 Jun 2024 02:14:50 +0200 Subject: [PATCH] Move the documentation to the GitHub wiki --- .github/workflows/ci.yaml | 24 ------------ .gitignore | 3 +- README.md | 5 +-- docs/favicon.ico | Bin 19937 -> 0 bytes docs/favicon.svg | 1 - docs/index.md | 25 ------------ docs/installation.md | 28 -------------- docs/styles.css | 4 -- docs/testing.md | 74 ------------------------------------ docs/usage/check_comment.md | 72 ----------------------------------- docs/usage/submit_ham.md | 57 --------------------------- docs/usage/submit_spam.md | 59 ---------------------------- docs/usage/verify_key.md | 46 ---------------------- etc/mkdocs.yaml | 66 -------------------------------- etc/requirements.txt | 1 - etc/typedoc.js | 10 ----- gulpfile.js | 14 +------ package.json | 2 +- 18 files changed, 5 insertions(+), 486 deletions(-) delete mode 100644 docs/favicon.ico delete mode 100644 docs/favicon.svg delete mode 100644 docs/index.md delete mode 100644 docs/installation.md delete mode 100644 docs/styles.css delete mode 100644 docs/testing.md delete mode 100644 docs/usage/check_comment.md delete mode 100644 docs/usage/submit_ham.md delete mode 100644 docs/usage/submit_spam.md delete mode 100644 docs/usage/verify_key.md delete mode 100644 etc/mkdocs.yaml delete mode 100644 etc/requirements.txt delete mode 100644 etc/typedoc.js diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 891c3501..4625a313 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -19,27 +19,3 @@ jobs: env: AKISMET_API_KEY: ${{secrets.AKISMET_API_KEY}} NODE_ENV: test - deploy: - needs: test - runs-on: ubuntu-latest - steps: - - name: Fetch sources - uses: actions/checkout@v4 - - name: Set up Node.js - uses: actions/setup-node@v4 - with: - cache: npm - node-version: 22 - - name: Set up Python - uses: actions/setup-python@v5 - with: - cache: pip - python-version: 3.12 - - name: Install dependencies - run: | - npm ci - pip install --requirement=etc/requirements.txt - - name: Deploy documentation - run: | - npx gulp doc - mkdocs gh-deploy --config-file=etc/mkdocs.yaml --force diff --git a/.gitignore b/.gitignore index 6f85d2be..4b8c587e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,8 @@ /**/.DS_Store /.idea/ -/docs/api/ /etc/http-client.private.env.json /lib/ /node_modules/ /npm-debug.log /var/ -/www/ +/wiki/ diff --git a/README.md b/README.md index c1aa9f0e..adc2d283 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,11 @@ Prevent comment spam using [Akismet](https://akismet.com) service, in [JavaScript](https://developer.mozilla.org/docs/Web/JavaScript). ## Documentation -- [User guide](https://docs.belin.io/akismet.js) -- [API reference](https://docs.belin.io/akismet.js/api) +- [User guide](https://github.com/cedx/akismet.js/wiki) +- [Examples](https://github.com/cedx/akismet.js/tree/main/example) ## Development - [Git repository](https://github.com/cedx/akismet.js) -- [npm package](https://www.npmjs.com/package/@cedx/akismet) - [Submit an issue](https://github.com/cedx/akismet.js/issues) ## License diff --git a/docs/favicon.ico b/docs/favicon.ico deleted file mode 100644 index 4e9b4c6bd90d0e36f6101441b3e886ce4426f166..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 19937 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 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 7ba99d3d..00000000 --- a/docs/index.md +++ /dev/null @@ -1,25 +0,0 @@ -# Akismet for JS -Used by millions of websites, [Akismet](https://akismet.com) filters out hundreds of millions of spam comments from the Web every day. -Add Akismet to your [JavaScript](https://developer.mozilla.org/docs/Web/JavaScript) applications so you don't have to worry about spam again. - -!!! warning - The Akismet service requires an API key. - If you are not already registered, [sign up for an Akismet account](https://akismet.com/developers). - -## Quick start -Install the latest version of **Akismet for JS** with [npm](https://getcomposer.org) package manager: - -```shell -npm install @cedx/akismet -``` - -For detailed instructions, see the [installation guide](installation.md). - -## Usage -There are three different types of calls to [Akismet](https://akismet.com): - -1. [Key verification](usage/verify_key.md) will verify whether a valid API key is being used. This is especially useful if you will have multiple users with their own Akismet subscriptions using your application. -2. [Comment check](usage/check_comment.md) is used to ask Akismet whether a given post, comment, profile, etc. is spam. -3. [Submit spam](usage/submit_spam.md) and [submit ham](usage/submit_ham.md) are follow-ups to let Akismet know when it got something wrong (missed spam and false positives). These are very important, and you shouldn't develop using the Akismet API without a facility to include reporting missed spam and false positives. - -Before integrating this library into your application, you should [test your API calls](testing.md) to ensure a proper usage. diff --git a/docs/installation.md b/docs/installation.md deleted file mode 100644 index 73eca838..00000000 --- a/docs/installation.md +++ /dev/null @@ -1,28 +0,0 @@ -# Installation - -## Requirements -Before installing **Akismet for JS**, you need to make sure you have [Node.js](https://nodejs.org) -and [npm](https://www.npmjs.com), the Node.js package manager, up and running. - -You can verify if you're already good to go with the following command: - -```shell -node --version -# v22.0.0 -``` - -## Installing with npm package manager - -### 1. Install it -From a command prompt, run: - -```shell -npm install @cedx/akismet -``` - -### 2. Import it -Now in your [JavaScript](https://developer.mozilla.org/docs/Web/JavaScript) code, you can use: - -```js -import * as akismet from "@cedx/akismet"; -``` diff --git a/docs/styles.css b/docs/styles.css deleted file mode 100644 index ff5dd9a4..00000000 --- a/docs/styles.css +++ /dev/null @@ -1,4 +0,0 @@ -body { - --md-code-font-family: ui-monospace, monospace; - --md-text-font-family: ui-sans-serif, sans-serif; -} diff --git a/docs/testing.md b/docs/testing.md deleted file mode 100644 index d54d30da..00000000 --- a/docs/testing.md +++ /dev/null @@ -1,74 +0,0 @@ -# Testing -When you will integrate this library with your own application, you will of course need to test it. -Often we see developers get ahead of themselves, making a few trivial API calls with minimal values -and drawing the wrong conclusions about Akismet's accuracy. - -## Simulate a positive result (spam) -Make a [comment check](usage/check_comment.md) API call with the `Author.name` set to `"viagra-test-123"` -or `Author.email` set to `"akismet-guaranteed-spam@example.com"`. Populate all other required fields with typical values. - -The Akismet API will always return a `CheckResult.spam` response to a valid request with one of those values. -If you receive anything else, something is wrong in your client, data, or communications. - -```js -import console from "node:console"; -import {Author, Blog, Client, Comment} from "@cedx/akismet"; - -const comment = new Comment({ - content: "A user comment.", - author: new Author({ - ipAddress: "127.0.0.1", - name: "viagra-test-123", - userAgent: "Mozilla/5.0" - }) -}); - -const blog = new Blog({url: "https://www.yourblog.com"}) -const result = await new Client("123YourAPIKey", blog).checkComment(comment); -console.log(`It should be "CheckResult.spam": ${result}`); -``` - -## Simulate a negative result (ham) -Make a [comment check](usage/check_comment.md) API call with the `Author.role` set to `"administrator"` -and all other required fields populated with typical values. - -The Akismet API will always return a `CheckResult.ham` response. Any other response indicates a data or communication problem. - -```js -import console from "node:console"; -import {Author, AuthorRole, Blog, Client, Comment} from "@cedx/akismet"; - -const comment = new Comment({ - content: "A user comment.", - author: new Author({ - ipAddress: "127.0.0.1", - role: AuthorRole.administrator, - userAgent: "Mozilla/5.0" - }) -}); - -const blog = new Blog({url: "https://www.yourblog.com"}) -const result = await new Client("123YourAPIKey", blog).checkComment(comment); -console.log(`It should be "CheckResult.ham": ${result}`); -``` - -## Automated testing -Enable the `Client.isTest` option in your tests. - -That will tell Akismet not to change its behaviour based on those API calls: they will have no training effect. -That means your tests will be somewhat repeatable, in the sense that one test won't influence subsequent calls. - -```js -import {Author, Blog, Client, Comment} from "@cedx/akismet"; - -const blog = new Blog({url: "https://www.yourblog.com"}); -const client = new Client("123YourAPIKey", blog, {isTest: true}); - -const comment = new Comment({ - content: "A user comment.", - author: new Author({ipAddress: "127.0.0.1", userAgent: "Mozilla/5.0"}) -}); - -// It should not influence subsequent calls. -client.checkComment(comment); -``` diff --git a/docs/usage/check_comment.md b/docs/usage/check_comment.md deleted file mode 100644 index 8d3a99a4..00000000 --- a/docs/usage/check_comment.md +++ /dev/null @@ -1,72 +0,0 @@ -# Comment check -This is the call you will make the most. It takes a number of arguments and characteristics about the submitted content -and then returns a thumbs up or thumbs down. **Performance can drop dramatically if you choose to exclude data points.** -The more data you send Akismet about each comment, the greater the accuracy. We recommend erring on the side of including too much data. - -```ts -Client.checkComment(comment: Comment): Promise -``` - -It is important to [test Akismet](../testing.md) with a significant amount of real, live data in order to draw any conclusions on accuracy. -Akismet works by comparing content to genuine spam activity happening **right now** (and this is based on more than just the content itself), -so artificially generating spam comments is not a viable approach. - -See the [Akismet API documentation](https://akismet.com/developers/detailed-docs/comment-check) for more information. - -## Parameters - -### **comment**: Comment -The `Comment` providing the user's message to be checked. - -## Return value -A `Promise` that resolves with a `CheckResult` value indicating whether the given `Comment` is ham, spam or pervasive spam. - -!!! tip - A comment classified as pervasive spam can be safely discarded. - -The promise rejects with an `Error` when an issue occurs. -The error `message` usually includes some debug information, provided by the `X-akismet-debug-help` HTTP header, -about what exactly was invalid about the call. - -It can also reject with a custom error code and message (respectively provided by the `X-akismet-alert-code` and `X-akismet-alert-msg` headers). -See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors) for more information. - -## Example - -```js -import console from "node:console"; -import {Author, Blog, CheckResult, Client, Comment, CommentType} from "@cedx/akismet"; - -try { - const author = new Author({ - email: "john.doe@domain.com", - ipAddress: "192.168.123.456", - name: "John Doe", - role: "guest", - userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36 Edg/126.0.0.0" - }); - - const comment = new Comment({ - author, - date: new Date, - content: "A user comment.", - referrer: "https://github.com/cedx/akismet.js", - type: CommentType.contactForm - }); - - const blog = new Blog({ - charset: "UTF-8", - languages: ["fr"], - url: "https://www.yourblog.com" - }); - - const result = await new Client("123YourAPIKey", blog).checkComment(comment); - console.log(result == CheckResult.ham ? "The comment is ham." : "The comment is spam."); -} -catch (error) { - const message = error instanceof Error ? error.message : String(error); - console.log(`An error occurred: ${message}`); -} -``` - -See the [API reference](../api/) for detailed information about the `Author` and `Comment` classes, and their properties. diff --git a/docs/usage/submit_ham.md b/docs/usage/submit_ham.md deleted file mode 100644 index 00c61de0..00000000 --- a/docs/usage/submit_ham.md +++ /dev/null @@ -1,57 +0,0 @@ -# Submit ham -This call is intended for the submission of false positives - items that were incorrectly classified as spam by Akismet. -It takes identical arguments as [comment check](check_comment.md) and [submit spam](submit_spam.md). - -```ts -Client.submitHam(comment: Comment): Promise -``` - -Remember that, as explained in the [submit spam](submit_spam.md) documentation, you should ensure -that any values you're passing here match up with the original and corresponding [comment check](check_comment.md) call. - -See the [Akismet API documentation](https://akismet.com/developers/detailed-docs/submit-ham-false-positives) for more information. - -## Parameters - -### **comment**: Comment -The user's `Comment` to be submitted, incorrectly classified as spam. - -!!! note - Ideally, it should be the same object as the one passed to the original [comment check](check_comment.md) API call. - -## Return value -A `Promise` that resolves when the given `Comment` has been submitted. - -The promise rejects with an `Error` when an issue occurs. -The error `message` usually includes some debug information, provided by the `X-akismet-debug-help` HTTP header, -about what exactly was invalid about the call. - -It can also reject with a custom error code and message (respectively provided by the `X-akismet-alert-code` and `X-akismet-alert-msg` headers). -See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors) for more information. - -## Example - -```js -import console from "node:console"; -import {Author, Blog, Client, Comment} from "@cedx/akismet"; - -try { - const blog = new Blog({url: "https://www.yourblog.com"}); - const client = new Client("123YourAPIKey", blog); - - const comment = new Comment({ - content: "I'm testing out the Service API.", - author: new Author({ - ipAddress: "192.168.123.456", - userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36 Edg/126.0.0.0" - }) - }); - - await client.submitHam(comment); - console.log("The comment was successfully submitted as ham."); -} -catch (error) { - const message = error instanceof Error ? error.message : String(error); - console.log(`An error occurred: ${message}`); -} -``` diff --git a/docs/usage/submit_spam.md b/docs/usage/submit_spam.md deleted file mode 100644 index 233badbe..00000000 --- a/docs/usage/submit_spam.md +++ /dev/null @@ -1,59 +0,0 @@ -# Submit spam -This call is for submitting comments that weren't marked as spam but should have been. - -```ts -Client.submitSpam(comment: Comment): Promise -``` - -It is very important that the values you submit with this call match those of your [comment check](check_comment.md) calls as closely as possible. -In order to learn from its mistakes, Akismet needs to match your missed spam and false positive reports -to the original [comment check](check_comment.md) API calls made when the content was first posted. While it is normal for less information -to be available for [submit spam](submit_spam.md) and [submit ham](submit_ham.md) calls (most comment systems and forums will not store all metadata), -you should ensure that the values that you do send match those of the original content. - -See the [Akismet API documentation](https://akismet.com/developers/detailed-docs/submit-spam-missed-spam) for more information. - -## Parameters - -### **comment**: Comment -The user's `Comment` to be submitted, incorrectly classified as ham. - -!!! note - Ideally, it should be the same object as the one passed to the original [comment check](check_comment.md) API call. - -## Return value -A `Promise` that resolves when the given `Comment` has been submitted. - -The promise rejects with an `Error` when an issue occurs. -The error `message` usually includes some debug information, provided by the `X-akismet-debug-help` HTTP header, -about what exactly was invalid about the call. - -It can also reject with a custom error code and message (respectively provided by the `X-akismet-alert-code` and `X-akismet-alert-msg` headers). -See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors) for more information. - -## Example - -```js -import console from "node:console"; -import {Author, Blog, Client, Comment} from "@cedx/akismet"; - -try { - const blog = new Blog({url: "https://www.yourblog.com"}); - const client = new Client("123YourAPIKey", blog); - - const comment = new Comment({ - content: "Spam!", - author: new Author({ - ipAddress: "192.168.123.456", - userAgent: "Spam Bot/6.6.6" - }) - }); - - await client.submitSpam(comment); - console.log("The comment was successfully submitted as spam."); -} -catch (error) { - const message = error instanceof Error ? error.message : String(error); - console.log(`An error occurred: ${message}`); -} -``` diff --git a/docs/usage/verify_key.md b/docs/usage/verify_key.md deleted file mode 100644 index c1f14b57..00000000 --- a/docs/usage/verify_key.md +++ /dev/null @@ -1,46 +0,0 @@ -# Key verification -Key verification authenticates your API key before calling the [comment check](check_comment.md), -[submit spam](submit_spam.md) or [submit ham](submit_ham.md) methods. - -```ts -Client.verifyKey(): Promise -``` - -This is the first call that you should make to Akismet and is especially useful -if you will have multiple users with their own Akismet subscriptions using your application. - -See the [Akismet API documentation](https://akismet.com/developers/detailed-docs/key-verification) for more information. - -## Parameters -None. - -## Return value -A `Promise` that resolves with a boolean value indicating whether the client's API key is valid. - -The promise rejects with an `Error` when an issue occurs. -The error `message` usually includes some debug information, provided by the `X-akismet-debug-help` HTTP header, -about what exactly was invalid about the call. - -It can also reject with a custom error code and message (respectively provided by the `X-akismet-alert-code` and `X-akismet-alert-msg` headers). -See [Response Error Codes](https://akismet.com/developers/detailed-docs/errors) for more information. - -## Example - -```js -import console from "node:console"; -import {Blog, Client} from "@cedx/akismet"; - -try { - const blog = new Blog({url: "https://www.yourblog.com"}); - const client = new Client("123YourAPIKey", blog); - - const isValid = await client.verifyKey(); - console.log(isValid ? "The API key is valid." : "The API key is invalid."); -} -catch (error) { - const message = error instanceof Error ? error.message : String(error); - console.log(`An error occurred: ${message}`); -} -``` - -See the [API reference](../api/) for detailed information about the `Client` and `Blog` classes, and their properties and methods. diff --git a/etc/mkdocs.yaml b/etc/mkdocs.yaml deleted file mode 100644 index d86d42ae..00000000 --- a/etc/mkdocs.yaml +++ /dev/null @@ -1,66 +0,0 @@ -site_name: Akismet for JS -site_url: https://docs.belin.io/akismet.js -site_author: Cédric Belin - cedric@belin.io -site_description: > - Prevent comment spam using the Akismet service, in JavaScript. - Add Akismet to your JavaScript applications so you don't have to worry about spam again. - -docs_dir: ../docs -site_dir: ../www -use_directory_urls: false - -edit_uri: edit/main/docs/ -repo_name: cedx/akismet.js -repo_url: https://github.com/cedx/akismet.js - -copyright: Copyright © Cédric Belin -extra: - social: - - icon: fontawesome/brands/github - link: https://github.com/cedx - name: GitHub - - icon: fontawesome/brands/linkedin - link: https://linkedin.com/in/cedxbelin - name: LinkedIn - - icon: fontawesome/brands/mastodon - link: https://mastodon.social/@cedx - name: Mastodon - -extra_css: - - styles.css - -markdown_extensions: - - admonition - - pymdownx.superfences - -nav: - - Home: index.md - - Installation: installation.md - - Usage: - - Key verification: usage/verify_key.md - - Comment check: usage/check_comment.md - - Submit spam: usage/submit_spam.md - - Submit ham: usage/submit_ham.md - - Related topics: - - API reference: api/ - - Testing: testing.md - - See also: - - Changelog: changelog.md - - License: license.md - -theme: - favicon: favicon.svg - features: - - content.code.copy - - content.tooltips - - navigation.footer - - navigation.instant - - navigation.instant.progress - - navigation.sections - - search.suggest - font: false - logo: favicon.svg - name: material - palette: - accent: yellow - primary: yellow diff --git a/etc/requirements.txt b/etc/requirements.txt deleted file mode 100644 index 4c8f017d..00000000 --- a/etc/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -mkdocs-material diff --git a/etc/typedoc.js b/etc/typedoc.js deleted file mode 100644 index 54681115..00000000 --- a/etc/typedoc.js +++ /dev/null @@ -1,10 +0,0 @@ -export default { - entryPoints: ["../src/index.js"], - excludePrivate: true, - gitRevision: "main", - hideGenerator: true, - name: "Akismet for JS", - out: "../docs/api", - readme: "none", - tsconfig: "../src/tsconfig.json" -}; diff --git a/gulpfile.js b/gulpfile.js index e0d7cfd4..a2aa8b18 100644 --- a/gulpfile.js +++ b/gulpfile.js @@ -1,4 +1,4 @@ -import {cp, readFile, writeFile} from "node:fs/promises"; +import {readFile, writeFile} from "node:fs/promises"; import {env} from "node:process"; import {deleteAsync} from "del"; import {$} from "execa"; @@ -17,12 +17,6 @@ export function clean() { return deleteAsync(["lib", "var/**/*", "www"]); } -// Builds the documentation. -export async function doc() { - for (const file of ["CHANGELOG.md", "LICENSE.md"]) await cp(file, `docs/${file.toLowerCase()}`); - return $`typedoc --options etc/typedoc.js`; -} - // Performs the static analysis of source code. export async function lint() { await $`tsc --project tsconfig.json`; @@ -35,12 +29,6 @@ export async function publish() { for (const action of [["tag"], ["push", "origin"]]) await $`git ${action} v${pkg.version}`; } -// Starts the development server. -export async function serve() { - await doc(); - return $({stdio: "inherit"})`mkdocs serve --config-file=etc/mkdocs.yaml`; -} - // Runs the test suite. export function test() { env.NODE_ENV = "test"; diff --git a/package.json b/package.json index cfc67bd3..3f722fd9 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "bugs": "https://github.com/cedx/akismet.js/issues", "description": "Prevent comment spam using the Akismet service.", - "homepage": "https://docs.belin.io/akismet.js", + "homepage": "https://github.com/cedx/akismet.js", "license": "MIT", "name": "@cedx/akismet", "repository": "cedx/akismet.js",