Merge pull request #76 from guardian/jsh/update-docs

Update typedoc and rebuild documentation

build/README.md

@@ -1,4 +1,5 @@
-# prosemirror-typerighter ![](https://travis-ci.org/guardian/prosemirror-typerighter.svg?branch=master) [![Coverage Status](https://coveralls.io/repos/github/guardian/prosemirror-typerighter/badge.svg?branch=master)](https://coveralls.io/github/guardian/prosemirror-typerighter?branch=master)
+![](https://travis-ci.org/guardian/prosemirror-typerighter.svg?branch=master) [![Coverage Status](https://coveralls.io/repos/github/guardian/prosemirror-typerighter/badge.svg?branch=master)](https://coveralls.io/github/guardian/prosemirror-typerighter?branch=master)
+
 This Prosemirror plugin adds the ability to validate a document by sending it, or some parts of it, to an external service for validation. Once instantiated, it provides a store object that allows consumer code to subscribe to state updates for UI updates etc.
 
 It's still in its early stages! [There's a demo here.](https://guardian.github.io/prosemirror-typerighter/) See the 'pages' directory for an example implementation.
@@ -19,6 +20,10 @@ To test this plugin in applications that use it before publishing a release, use
 - Run `npm link` in the root of this project
 - Run `npm link @guardian/prosemirror-typerighter` in the root of the project that's consuming this package.
 
+## Updating documentation
+
+To update the project readme, edit the README.md in ./build and run `build:doc`. This runs Typedoc and appends the generated type information to the readme file, which is then published to the ./docs folder.
+
 ## Publishing new versions
 
 To publish, you'll need to have an account on [NPM](https://www.npmjs.com/) and be a member of the [Guardian organisation](https://www.npmjs.com/org/guardian).

build/typedoc.js

@@ -1,10 +1,11 @@
 module.exports = {
 	excludePrivate: true,
 	excludeProtected: true,
-	excludeExternals: true,
+	excludeExternals: false,
 	hideGenerator: true,
-	out: 'docs',
+  out: 'docs',
+  mode: 'library',
 	theme: 'markdown',
-	ignoreCompilerErrors: true,
-	readme: 'build/README.md'
-};
+	ignoreCompilerErrors: false,
+  readme: 'build/README.md'
+};

docs/README.md

@@ -1,21 +1,37 @@
+[@guardian/prosemirror-typerighter](README.md) › [Globals](globals.md)
 
-prosemirror-typerighter ![](https://travis-ci.org/guardian/prosemirror-typerighter.svg?branch=master) [![Coverage Status](https://coveralls.io/repos/github/guardian/prosemirror-typerighter/badge.svg?branch=master)](https://coveralls.io/github/guardian/prosemirror-typerighter?branch=master)
-==================================================================================================================================================================================================================================================================================================
+# @guardian/prosemirror-typerighter
+
+![](https://travis-ci.org/guardian/prosemirror-typerighter.svg?branch=master) [![Coverage Status](https://coveralls.io/repos/github/guardian/prosemirror-typerighter/badge.svg?branch=master)](https://coveralls.io/github/guardian/prosemirror-typerighter?branch=master)
 
 This Prosemirror plugin adds the ability to validate a document by sending it, or some parts of it, to an external service for validation. Once instantiated, it provides a store object that allows consumer code to subscribe to state updates for UI updates etc.
 
 It's still in its early stages! [There's a demo here.](https://guardian.github.io/prosemirror-typerighter/) See the 'pages' directory for an example implementation.
 
-Short-term roadmap:
+## Installation
+
+Install dependencies with `./scripts/setup.sh`.
+
+## Development
+
+`npm run watch` builds the project locally, watches for file changes, and serves the project locally at https://typerighter-client.local.dev-gutools.co.uk/ – or http://localhost:5000, if your Typerighter service doesn't require [pan-domain authentication](https://github.com/guardian/pan-domain-authentication).
+
+If your Typerighter service does require pan-domain authentication, you will need to run and visit another .local.dev-gutools application alongside this service to supply an authenticated cookie for that domain.
+
+The plugin must be pointed to the address of a running Typerighter service to submit a document and receive matches. To modify this address, change the address passed to the `TyperighterAdapter` in `pages/index.ts`.
+
+To test this plugin in applications that use it before publishing a release, use [`npm link`](https://docs.npmjs.com/cli/link) –
+- Run `npm link` in the root of this project
+- Run `npm link @guardian/prosemirror-typerighter` in the root of the project that's consuming this package.
 
-*   \[Plugin\] -- Toggling realtime validation.
-*   \[UI\] -- Grouping validations and applying grouped validations simultaneously.
+## Updating documentation
 
-## Index
+To update the project readme, edit the README.md in ./build and run `build:doc`. This runs Typedoc and appends the generated type information to the readme file, which is then published to the ./docs folder.
 
-### External modules
+## Publishing new versions
 
-* ["createValidationPlugin"](modules/_createvalidationplugin_.md)
+To publish, you'll need to have an account on [NPM](https://www.npmjs.com/) and be a member of the [Guardian organisation](https://www.npmjs.com/org/guardian).
 
----
+Before publishing, ensure your feature branch has been tagged with the [correct new version number](https://semver.org/) and merged to master. One easy way to achieve this is with npm via `npm version major | minor | patch`.
 
+Once you're ready to publish a new release, running `npm publish` will build the application, generate its type declarations, and publish.

docs/classes/matcherservice.md

@@ -0,0 +1,134 @@
+[@guardian/prosemirror-typerighter](../README.md) › [Globals](../globals.md) › [MatcherService](matcherservice.md)
+
+# Class: MatcherService ‹**TMatch**›
+
+A matcher service to manage the interaction between the prosemirror-typerighter plugin
+and the remote matching service.
+
+## Type parameters
+
+▪ **TMatch**: *IMatch*
+
+## Hierarchy
+
+* **MatcherService**
+
+## Index
+
+### Constructors
+
+* [constructor](matcherservice.md#constructor)
+
+### Methods
+
+* [addCategory](matcherservice.md#addcategory)
+* [fetchCategories](matcherservice.md#fetchcategories)
+* [fetchMatches](matcherservice.md#fetchmatches)
+* [getCurrentCategories](matcherservice.md#getcurrentcategories)
+* [removeCategory](matcherservice.md#removecategory)
+* [requestFetchMatches](matcherservice.md#requestfetchmatches)
+
+## Constructors
+
+###  constructor
+
+\+ **new MatcherService**(`store`: Store‹TMatch›, `commands`: Commands, `adapter`: IMatcherAdapter‹TMatch›, `initialThrottle`: number): *[MatcherService](matcherservice.md)*
+
+*Defined in [services/MatcherService.ts:20](https://github.com/guardian/prosemirror-typerighter/blob/a7df8ef/src/ts/services/MatcherService.ts#L20)*
+
+**Parameters:**
+
+Name | Type | Default |
+------ | ------ | ------ |
+`store` | Store‹TMatch› | - |
+`commands` | Commands | - |
+`adapter` | IMatcherAdapter‹TMatch› | - |
+`initialThrottle` | number | 2000 |
+
+**Returns:** *[MatcherService](matcherservice.md)*
+
+## Methods
+
+###  addCategory
+
+▸ **addCategory**(`categoryId`: string): *void*
+
+*Defined in [services/MatcherService.ts:47](https://github.com/guardian/prosemirror-typerighter/blob/a7df8ef/src/ts/services/MatcherService.ts#L47)*
+
+**Parameters:**
+
+Name | Type |
+------ | ------ |
+`categoryId` | string |
+
+**Returns:** *void*
+
+___
+
+###  fetchCategories
+
+▸ **fetchCategories**(): *Promise‹ICategory[]›*
+
+*Defined in [services/MatcherService.ts:40](https://github.com/guardian/prosemirror-typerighter/blob/a7df8ef/src/ts/services/MatcherService.ts#L40)*
+
+Get all of the available categories from the matcher service.
+
+**Returns:** *Promise‹ICategory[]›*
+
+___
+
+###  fetchMatches
+
+▸ **fetchMatches**(`requestId`: string, `blocks`: IBlock[]): *Promise‹void›*
+
+*Defined in [services/MatcherService.ts:64](https://github.com/guardian/prosemirror-typerighter/blob/a7df8ef/src/ts/services/MatcherService.ts#L64)*
+
+Fetch matches for a set of blocks.
+
+**Parameters:**
+
+Name | Type |
+------ | ------ |
+`requestId` | string |
+`blocks` | IBlock[] |
+
+**Returns:** *Promise‹void›*
+
+___
+
+###  getCurrentCategories
+
+▸ **getCurrentCategories**(): *ICategory[]*
+
+*Defined in [services/MatcherService.ts:45](https://github.com/guardian/prosemirror-typerighter/blob/a7df8ef/src/ts/services/MatcherService.ts#L45)*
+
+**Returns:** *ICategory[]*
+
+___
+
+###  removeCategory
+
+▸ **removeCategory**(`categoryId`: string): *void*
+
+*Defined in [services/MatcherService.ts:55](https://github.com/guardian/prosemirror-typerighter/blob/a7df8ef/src/ts/services/MatcherService.ts#L55)*
+
+**Parameters:**
+
+Name | Type |
+------ | ------ |
+`categoryId` | string |
+
+**Returns:** *void*
+
+___
+
+###  requestFetchMatches
+
+▸ **requestFetchMatches**(): *unknown*
+
+*Defined in [services/MatcherService.ts:79](https://github.com/guardian/prosemirror-typerighter/blob/a7df8ef/src/ts/services/MatcherService.ts#L79)*
+
+Request a fetch for matches. If we already have a request in flight,
+defer it until the next throttle window.
+
+**Returns:** *unknown*

docs/classes/typerighteradapter.md

@@ -0,0 +1,72 @@
+[@guardian/prosemirror-typerighter](../README.md) › [Globals](../globals.md) › [TyperighterAdapter](typerighteradapter.md)
+
+# Class: TyperighterAdapter
+
+A MatcherAdapter for the Typerighter remote service.
+
+## Hierarchy
+
+* **TyperighterAdapter**
+
+## Implements
+
+* IMatcherAdapter
+
+## Index
+
+### Constructors
+
+* [constructor](typerighteradapter.md#constructor)
+
+### Methods
+
+* [fetchCategories](typerighteradapter.md#fetchcategories)
+* [fetchMatches](typerighteradapter.md#fetchmatches)
+
+## Constructors
+
+###  constructor
+
+\+ **new TyperighterAdapter**(`url`: string, `responseThrottleMs`: number): *[TyperighterAdapter](typerighteradapter.md)*
+
+*Defined in [services/adapters/TyperighterAdapter.ts:41](https://github.com/guardian/prosemirror-typerighter/blob/a7df8ef/src/ts/services/adapters/TyperighterAdapter.ts#L41)*
+
+**Parameters:**
+
+Name | Type | Default |
+------ | ------ | ------ |
+`url` | string | - |
+`responseThrottleMs` | number | 250 |
+
+**Returns:** *[TyperighterAdapter](typerighteradapter.md)*
+
+## Methods
+
+###  fetchCategories
+
+▸ **fetchCategories**(): *Promise‹any›*
+
+*Defined in [services/adapters/TyperighterAdapter.ts:86](https://github.com/guardian/prosemirror-typerighter/blob/a7df8ef/src/ts/services/adapters/TyperighterAdapter.ts#L86)*
+
+**Returns:** *Promise‹any›*
+
+___
+
+###  fetchMatches
+
+▸ **fetchMatches**(`requestId`: string, `inputs`: IBlock[], `categoryIds`: string[], `onMatchesReceived`: TMatchesReceivedCallback, `onRequestError`: TRequestErrorCallback, `_`: TRequestCompleteCallback): *Promise‹void›*
+
+*Defined in [services/adapters/TyperighterAdapter.ts:46](https://github.com/guardian/prosemirror-typerighter/blob/a7df8ef/src/ts/services/adapters/TyperighterAdapter.ts#L46)*
+
+**Parameters:**
+
+Name | Type |
+------ | ------ |
+`requestId` | string |
+`inputs` | IBlock[] |
+`categoryIds` | string[] |
+`onMatchesReceived` | TMatchesReceivedCallback |
+`onRequestError` | TRequestErrorCallback |
+`_` | TRequestCompleteCallback |
+
+**Returns:** *Promise‹void›*