From b491ad1e076cf0922e041506f69623352dfa1463 Mon Sep 17 00:00:00 2001 From: Andrew Ferrazzutti Date: Mon, 11 Jul 2022 09:37:06 -0400 Subject: [PATCH] Fix typos in docs (#401) * Fix typos in docs * changelog --- changelog.d/401.doc | 1 + docs/advanced/widgets.md | 12 ++++++------ docs/advanced/workers.md | 2 +- docs/setup.md | 16 ++++++++-------- docs/setup/github.md | 2 +- docs/setup/gitlab.md | 2 +- docs/setup/jira.md | 6 +++--- docs/setup/sample-configuration.md | 4 ++-- docs/setup/webhooks.md | 10 +++++----- docs/usage/auth.md | 2 +- docs/usage/room_configuration.md | 6 +++--- docs/usage/room_configuration/github_repo.md | 2 +- docs/usage/room_configuration/gitlab_project.md | 2 +- src/provisioning/api.md | 4 ++-- 14 files changed, 36 insertions(+), 35 deletions(-) create mode 100644 changelog.d/401.doc diff --git a/changelog.d/401.doc b/changelog.d/401.doc new file mode 100644 index 00000000..b127138b --- /dev/null +++ b/changelog.d/401.doc @@ -0,0 +1 @@ +Correct some typos in documentation pages. diff --git a/docs/advanced/widgets.md b/docs/advanced/widgets.md index 77f8fe6b..ec3da2ff 100644 --- a/docs/advanced/widgets.md +++ b/docs/advanced/widgets.md @@ -54,10 +54,10 @@ This can be enabled by setting `roomSetupWidget` to an object. You can add the w When `addOnInvite` is true, the bridge will add a widget to rooms when the bot is invited, and the room has **no existing connections**. `disallowedIpRanges` describes which IP ranges should be disallowed when resolving homeserver IP addresses (for security reasons). -Unless you know what you are doing, it is recommended to not include this key. The default blocked IPs are listed above for your convienence. +Unless you know what you are doing, it is recommended to not include this key. The default blocked IPs are listed above for your convenience. -`publicUrl` should be set to the publically reachable address for the widget `public` content. By default, hookshot hosts this content on the -`widgets` listener under `/widgetapi/v1/static`. +`publicUrl` should be set to the publicly reachable address for the widget `public` content. By default, hookshot hosts this content on the +`widgets` listener under `/widgetapi/v1/static`. `branding` allows you to change the strings used for various bits of widget UI. At the moment you can: - Set `widgetTitle` to change the title of the widget that is created. @@ -65,8 +65,8 @@ Unless you know what you are doing, it is recommended to not include this key. T `openIdOverrides` allows you to configure the correct federation endpoints for a given set of Matrix server names. This is useful if you are testing/developing hookshot in a local dev environment. Production environments should not use this configuration (as their Matrix server name should be resolvable). The config takes a mapping of Matrix server name => base path for federation. -E.g. if your server name was `my-local-server` and you federation was readable via http://localhost/_matrix/federation, -you would put configure `my-local-server: "http://localhost`. +E.g. if your server name was `my-local-server` and your federation was readable via http://localhost/_matrix/federation, +you would put configure `my-local-server: "http://localhost"`. In addition to setting up the widgets config, you must bind a listener for the widgets resource in your `listeners` config. @@ -82,7 +82,7 @@ See the [setup page](../setup#listeners-configuration) for more information on l ### API -The API for widgets is currently in flux due to being fairly new, and it's not reccomended +The API for widgets is currently in flux due to being fairly new, and it's not recommended to develop against it at this time. At a future date this API will be merged with the existing provisioning API and the details will be published. diff --git a/docs/advanced/workers.md b/docs/advanced/workers.md index c5100540..d32b113c 100644 --- a/docs/advanced/workers.md +++ b/docs/advanced/workers.md @@ -26,7 +26,7 @@ queue: Once that is done, you can simply start the processes by name using yarn: ``` yarn start:webhooks -yarn start:matrixsender +yarn start:matrixsender yarn start:app ``` diff --git a/docs/setup.md b/docs/setup.md index 79442f5e..26d9437d 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -12,7 +12,7 @@ You **must** have administrative access to an existing homeserver in order to se Hookshot requires the homeserver to be configured with its appservice registration. -## Local installation +## Local installation This bridge requires at least Node 14 (though 16 is preferred), and Rust installed. @@ -51,7 +51,7 @@ Where `/etc/matrix-hookshot` would contain the configuration files `config.yml` ## Configuration Copy the `config.sample.yml` to a new file `config.yml`. The sample config is also hosted -[here](./setup/sample-configuration.md) for your convienence. +[here](./setup/sample-configuration.md) for your convenience. You should read and fill this in as the bridge will not start without a complete config. @@ -116,8 +116,8 @@ The `level` can be: - `admin` All permissions. This allows you to perform administrative tasks like deleting connections from all rooms. When permissions are checked, if a user matches any of the permission set and one -of those grants the right level for a service, they are allowed access. If none of the -definitions match, they are denined. +of those grants the right level for a service, they are allowed access. If none of the +definitions match, they are denied. #### Example @@ -125,7 +125,7 @@ A typical setup might be. ```yaml permissions: - # Allo all users to send commands to existing services + # Allow all users to send commands to existing services - actor: * services: - service: * @@ -184,8 +184,8 @@ At a minimum, you should bind the `webhooks` resource to a port and address. You port, or one on each. Each listener MUST listen on a unique port. You will also need to make this port accessible to the internet so services like GitHub can reach the bridge. It -is recommended to factor hookshot into your load balancer configuration, but currrently this process is left as an -excercise to the user. +is recommended to factor hookshot into your load balancer configuration, but currently this process is left as an +exercise to the user. In terms of API endpoints: @@ -196,7 +196,7 @@ In terms of API endpoints: - The `widgets` resource handles resources under `/widgetapi/v1...`. This may only be bound to **one** listener at present.
-Please note that the appservice HTTP listener is configured seperately from the rest of the bridge (in the `homeserver` section) due to lack of support +Please note that the appservice HTTP listener is configured separately from the rest of the bridge (in the `homeserver` section) due to lack of support in the upstream library. See this issue for details.
diff --git a/docs/setup/github.md b/docs/setup/github.md index a7599220..6d924d9b 100644 --- a/docs/setup/github.md +++ b/docs/setup/github.md @@ -18,7 +18,7 @@ You will need to enable the following permissions: - Contents (`read`) - Discussions (`read & write`) - Issues (`read & write`) - - Metadata + - Metadata - Projects (`read & write`) - Pull requests (`read & write`) - Organisation diff --git a/docs/setup/gitlab.md b/docs/setup/gitlab.md index 05d3c7b1..e7f2c012 100644 --- a/docs/setup/gitlab.md +++ b/docs/setup/gitlab.md @@ -30,7 +30,7 @@ for your `webhooks` listener). The GitLab hooks "test" button allows you to check that your webhooks are configured properly. The merge request, issue and release notifications lack a action field in the body of the request which means they won't show up in the room. You can check the logs to see -if the request made it through, however. +if the request made it through, however. ## Adding a repository diff --git a/docs/setup/jira.md b/docs/setup/jira.md index 06c76836..9e8c7c59 100644 --- a/docs/setup/jira.md +++ b/docs/setup/jira.md @@ -6,7 +6,7 @@ This should be done for all JIRA organisations you wish to bridge. The setup ste You need to go to the `WebHooks` configuration page under Settings > System. -Next, add a webhook that points to `/` on the public webhooks address for hookshot. You should also include a +Next, add a webhook that points to `/` on the public webhooks address for hookshot. You should also include a secret value by appending `?secret=your-webhook-secret`. The secret value can be anything, but should be reasonably secure and should also be stored in the `config.yml` file. @@ -36,7 +36,7 @@ depending on whether you are running a on-premise/enterprise instance or using A You will need a Atlassian account with the ability to use the developer tools in order to create the app. -You'll first need to head to https://developer.atlassian.com/console/myapps/create-3lo-app/ to create a +You'll first need to head to https://developer.atlassian.com/console/myapps/create-3lo-app/ to create a "OAuth 2.0 (3LO)" integration. Once named and created, you will need to: @@ -79,7 +79,7 @@ jira: secret: Ieph7iecheiThoo1othaineewieSh1koh2chainohtooyoh4waht1oetoaSoh6oh oauth: # Another secret key generated by you. - consumerKey: secret-consumer-key + consumerKey: secret-consumer-key # Path to a private key. Generate this with `openssl genrsa -out jira_privatekey.pem 4096` privateKey: jira_privatekey.pem # The path to your webhooks listener on the "/jira/oauth" path. diff --git a/docs/setup/sample-configuration.md b/docs/setup/sample-configuration.md index 817c8bab..268bd5bd 100644 --- a/docs/setup/sample-configuration.md +++ b/docs/setup/sample-configuration.md @@ -1,7 +1,7 @@ # Sample Configuration -Below is a sample bridge configuration file. The configuration file -can be tweaked to change the behaviour of your bridge. A bridge of the server is +Below is a sample bridge configuration file. The configuration file +can be tweaked to change the behaviour of your bridge. A bridge of the server is required to apply any changes made to this file. ```yaml diff --git a/docs/setup/webhooks.md b/docs/setup/webhooks.md index 4dcc62d3..2e284d2f 100644 --- a/docs/setup/webhooks.md +++ b/docs/setup/webhooks.md @@ -78,7 +78,7 @@ If the body does NOT contain a `text` field, the full JSON payload will be sent ### GET requests In previous versions of hookshot, it would also handle the `GET` HTTP method. This was disabled due to concerns that it was too easy for the webhook to be -inadvetently triggered by URL preview features in clients and servers. If you still need this functionality, you can enable it in the config. +inadvertently triggered by URL preview features in clients and servers. If you still need this functionality, you can enable it in the config. Hookshot will insert the full content of the body into a key under the Matrix event called `uk.half-shot.hookshot.webhook_data`, which may be useful if you have other integrations that would like to make use of the raw request body. @@ -99,12 +99,12 @@ in your room to prevent users from tampering with the script. This bridge supports creating small JavaScript snippets to translate an incoming webhook payload into a message for the room, giving you a very powerful ability to generate messages based on whatever input is coming in. -The input is parsed and exectuted within a seperate JavaScript Virtual Machine context, and is limited to an execution time of 2 seconds. +The input is parsed and executed within a separate JavaScript Virtual Machine context, and is limited to an execution time of 2 seconds. With that said, the feature is disabled by default and `allowJsTransformationFunctions` must be enabled in the config. The code snippets can be edited by editing the Matrix state event corresponding to this connection (with a state type of `uk.half-shot.matrix-hookshot.generic.hook`). Because this is a fairly advanced feature, this documentation won't go into how to edit state events from your client. -Please seek out documentation from your client on how to achieve this. +Please seek out documentation from your client on how to achieve this. The script string should be set within the state event under the `transformationFunction` key. @@ -114,7 +114,7 @@ Transformation scripts have a versioned API. You can check the version of the AP at runtime by checking the `HookshotApiVersion` variable. If the variable is undefined, it should be considered `v1`. The execution environment will contain a `data` variable, which will be the body of the incoming request (JSON will be parsed into an `Object`). -Scripts are executed syncronously and expect the `result` variable to be set. +Scripts are executed synchronously and expect the `result` variable to be set. If the script contains errors or is otherwise unable to work, the bridge will send an error to the room. You can check the logs of the bridge for a more precise error. @@ -152,7 +152,7 @@ if (data.counter === undefined) { ### V1 API The v1 API expects `result` to be a string. The string will be automatically interpreted as Markdown and transformed into HTML. All webhook messages -will be prefix'd with `Received webhook:`. If `result` is falsey (undefined, false or null) then the message will be `No content`. +will be prefixed with `Received webhook:`. If `result` is falsey (undefined, false or null) then the message will be `No content`. #### Example script diff --git a/docs/usage/auth.md b/docs/usage/auth.md index 6965f209..a9506427 100644 --- a/docs/usage/auth.md +++ b/docs/usage/auth.md @@ -55,4 +55,4 @@ have the endpoints required accessible from the internet. Authentication is requ - Say `jira login` to get the URL to authenticate via. - Click the URL sent by the bot. - Follow the steps, ensuring you authenticate with the right user. -- If all goes well, you will now be connected. You can check the status and authorisatied instances by saying `jira whoami` +- If all goes well, you will now be connected. You can check the status of authenticated instances by saying `jira whoami` diff --git a/docs/usage/room_configuration.md b/docs/usage/room_configuration.md index bd8b6d99..1c370fe8 100644 --- a/docs/usage/room_configuration.md +++ b/docs/usage/room_configuration.md @@ -5,7 +5,7 @@ Hookshot works off the principle of **Connections**. A room can have many connections to different services. The connections are defined -in the room state of a room. A connection defines the service it connects to, the +in the room state of a room. A connection defines the service it connects to, the type of integration (e.g. GitHub repo, Jira Project) and any additional configuration.
@@ -16,11 +16,11 @@ type of integration (e.g. GitHub repo, Jira Project) and any additional configur Hookshot supports several connection types, which are defined under the Room Configuration heading. -The availablilty of connection types depends on the configuration provided to hookshot. +The availability of connection types depends on the configuration provided to hookshot. ### The `!hookshot` command -Rooms can be bridged by inviting the hookshot bot into a room, and then running the +Rooms can be bridged by inviting the hookshot bot into a room, and then running the `!hookshot` command. Running `!hookshot help` will give you some details, but you should see the documentation provided for information on each connection type. diff --git a/docs/usage/room_configuration/github_repo.md b/docs/usage/room_configuration/github_repo.md index bff81873..15af393f 100644 --- a/docs/usage/room_configuration/github_repo.md +++ b/docs/usage/room_configuration/github_repo.md @@ -26,7 +26,7 @@ To set up a connection to a GitHub Repository in a new room: This connection supports a few options which can be defined in the room state: | Option | Description | Allowed values | Default | -|--------|-------------|----------------|---------| +|--------|-------------|----------------|---------| |ignoreHooks|Choose to exclude notifications for some event types|Array of: [Supported event types](#supported-event-types) |*empty*| |commandPrefix|Choose the prefix to use when sending commands to the bot|A string, ideally starts with "!"|`!gh`| |showIssueRoomLink|When new issues are created, provide a Matrix alias link to the issue room|`true/false`|`false`| diff --git a/docs/usage/room_configuration/gitlab_project.md b/docs/usage/room_configuration/gitlab_project.md index 07481fb6..0e4dadfe 100644 --- a/docs/usage/room_configuration/gitlab_project.md +++ b/docs/usage/room_configuration/gitlab_project.md @@ -22,7 +22,7 @@ To set up a connection to a GitLab project in a new room: This connection supports a few options which can be defined in the room state: | Option | Description | Allowed values | Default | -|--------|-------------|----------------|---------| +|--------|-------------|----------------|---------| |ignoreHooks|Choose to exclude notifications for some event types|Array of: [Supported event types](#supported-event-types) |*empty*| |commandPrefix|Choose the prefix to use when sending commands to the bot|A string, ideally starts with "!"|`!gh`| |pushTagsRegex|Only mention pushed tags which match this regex|Regex string|*empty*| diff --git a/src/provisioning/api.md b/src/provisioning/api.md index c1a2cd31..5c2a3641 100644 --- a/src/provisioning/api.md +++ b/src/provisioning/api.md @@ -3,7 +3,7 @@ Provisioning API for matrix-hookshot # Overview -This document describes how to integrate with `matrix-hookshot`'s provisoning API. +This document describes how to integrate with `matrix-hookshot`'s provisioning API. Requests made to the bridge must be against the API listener defined in the config under `provisioning`, not the appservice or webhook listeners. @@ -22,7 +22,7 @@ APIs are versioned independently so two endpoints on the latest version may not ## GET /v1/health -Request the status of the provisoning API. +Request the status of the provisioning API. ### Response