docs: integrate Vale for documentation linting (#2242)

* added value rules * resolved errors raised by vale * added github action * fixes to github action * added details in contribution guidelines * added rule for numbers * limited checks to errors
2022-09-22 13:12:09 +03:00
parent d0d789b6d4
commit 6adaf56c73
103 changed files with 2408 additions and 832 deletions
@@ -2,7 +2,7 @@

 In this document, you’ll learn what Batch Jobs are and how they work in Medusa.

-## What are Batch Jobs?
+## What are Batch Jobs

 Batch Jobs are tasks that can be performed asynchronously and iteratively. They can be [created using the Admin API](https://docs.medusajs.com/api/admin/#tag/Batch-Job/operation/PostBatchJobs), then, once confirmed, they are processed asynchronously.

@@ -56,6 +56,6 @@ If the batch job fails at any point in this flow, its status is changed to `fail

 ![Flowchart summarizing the batch job's flow from creation to completion](https://i.imgur.com/Qja0kAz.png)

-## What’s Next?
+## What’s Next

 - Learn about the [Batch Job’s events](../subscribers/events-list.md#batch-jobs-events).
@@ -4,7 +4,7 @@ In this document, you’ll learn how to create a cron job in Medusa.

 ## Overview

-Medusa allows you to create cron jobs that run at specific times during your server’s lifetime. For example, you can synchronize your inventory with an ERP system once a day.
+Medusa allows you to create cron jobs that run at specific times during your server’s lifetime. For example, you can synchronize your inventory with an Enterprise Resource Planning (ERP) system once a day.

 This guide explains how to create a cron job on your Medusa server. The cron job in this example will simply change the status of draft products to `published`.

@@ -12,7 +12,7 @@ This guide explains how to create a cron job on your Medusa server. The cron job

 ### Medusa Components

-It is assumed that you already have a Medusa server installed and set up. If not, you can follow our [quickstart guide](../../../quickstart/quick-start.md) to get started.
+It is assumed that you already have a Medusa server installed and set up. If not, you can follow the [quickstart guide](../../../quickstart/quick-start.md) to get started.

 ### Redis

@@ -53,7 +53,7 @@ import cors from "cors"
 import { projectConfig } from "../../medusa-config"
 ```

-Then, create an object that will hold the CORS configurations:
+Then, create an object that will hold the Cross-Origin Resource Sharing (CORS) configurations:

 ```js
 const corsOptions = {
@@ -204,7 +204,7 @@ const user = await userService.retrieve(id)

 ### Route Parameters

-The routes you create receive 2 parameters. The first one is the absolute path to the root directory that your server is running from. The second one is an object that has your plugin's options. If your API route is not implemented in a plugin, then it will be an empty object.
+The routes you create receive two parameters. The first one is the absolute path to the root directory that your server is running from. The second one is an object that has your plugin's options. If your API route is not implemented in a plugin, then it will be an empty object.

 ```js
 export default (rootDirectory, pluginOptions) => {
@@ -53,7 +53,7 @@ import cors from "cors"
 import { projectConfig } from "../../medusa-config"
 ```

-Then, create an object that will hold the CORS configurations:
+Then, create an object that will hold the Cross-Origin Resource Sharing (CORS) configurations:

 ```js
 const corsOptions = {
@@ -203,7 +203,7 @@ const customer = await customerService.retrieve(id)

 ### Route Parameters

-The routes you create receive 2 parameters. The first one is the absolute path to the root directory that your server is running from. The second one is an object that has your plugin's options. If your API route is not implemented in a plugin, then it will be an empty object.
+The routes you create receive two parameters. The first one is the absolute path to the root directory that your server is running from. The second one is an object that has your plugin's options. If your API route is not implemented in a plugin, then it will be an empty object.

 ```js
 export default (rootDirectory, pluginOptions) => {
@@ -121,7 +121,7 @@ In the constructor, you can use dependency injection to get access to instances

 Then, in the method `list`, you can obtain an instance of the `PostRepository` using `this.manager_.getCustomRepository` passing it `this.postRepository` as a parameter. This lets you use [Custom Repositories with Typeorm](https://typeorm.io/custom-repository) to create custom methods in your repository that work with the data in your database.

-After getting an instance of the repository, you can then use [Typeorm’s Repository methods](https://typeorm.io/repository-api) to perform CRUD (Create, Read, Update, Delete) operations on your entity.
+After getting an instance of the repository, you can then use [Typeorm’s Repository methods](https://typeorm.io/repository-api) to perform Create, Read, Update, and Delete (CRUD) operations on your entity.

 If you need access to your entity in endpoints, you can then use the methods you define in the service.

@@ -2,7 +2,7 @@

 In this document, you'll learn what Entities are in Medusa.

-## What are Entities?
+## What are Entities

 Entities in medusa represent tables in the database as classes. An example of this would be the `Order` entity which represents the `order` table in the database. Entities provide a uniform way of defining and interacting with data retrieved from the database.

@@ -8,7 +8,7 @@ Medusa’s Migrations do not work with SQLite databases. They are intended to be

 :::

-## What are Migrations?
+## What are Migrations

 Migrations are scripts that are used to make additions or changes to your database schema. In Medusa, they are essential for both when you first install your server and for subsequent server upgrades later on.

@@ -100,7 +100,7 @@ When an event is triggered that your Notification Provider is registered as a ha

 In this method, you can perform the necessary operation to send the Notification. Following the example above, you can send an email to the customer when they place an order.

-This method receives 3 parameters:
+This method receives three parameters:

 1. `eventName`: This is the name of the event that was triggered. For example, `order.placed`.
 2. `eventData`: This is the data payload of the event that was triggered. For example, if the `order.placed` event is triggered, the `eventData` object contains the property `id` which is the ID of the order that was placed.
@@ -156,7 +156,7 @@ The `to` and `data` properties are used in the `NotificationService` in Medusa

 Using the [Resend Notification endpoint](https://docs.medusajs.com/api/admin/#tag/Notification/operation/PostNotificationsNotificationResend), an admin user can resend a Notification to the customer. The [`NotificationService`](../../../references/services/classes/NotificationService.md) in Medusa’s core then executes the `resendNotification` method in your Notification Provider.

-This method receives 3 parameters:
+This method receives three parameters:

 1. `notification`: This is the original Notification record that was created after you sent the notification with `sendNotification`. You can get an overview of the entity and its attributes in the [architecture overview](overview.md#notification-entity-overview), but most notably it includes the `to` and `data` attributes which are populated originally using the `to` and `data` properties of the object you return in `sendNotification`.
 2. `config`: In the Resend Notification endpoint you may specify an alternative receiver of the notification using the `to` request body parameter. For example, you may want to resend the order confirmation email to a different email. If that’s the case, you have access to it in the `config` parameter object. Otherwise, `config` will be an empty object.
@@ -240,7 +240,7 @@ Then, place an order either using the [REST APIs](https://docs.medusajs.com/api/

 :::tip

-If you don’t have a storefront installed you can get started with either our [Next.js](../../../starters/nextjs-medusa-starter.md) or [Gatsby](../../../starters/gatsby-medusa-starter.md) starter storefronts in minutes.
+If you don’t have a storefront installed you can get started with either the [Next.js](../../../starters/nextjs-medusa-starter.md) or [Gatsby](../../../starters/gatsby-medusa-starter.md) starter storefronts in minutes.

 :::

@@ -6,7 +6,7 @@ This document gives an overview of the notification architecture and how it work

 Medusa provides a Notification API to mainly handle sending and resending notifications when an event occurs. For example, sending an email to the customer when they place an order.

-The Notification architecture is made up of 2 main components: the Notification Provider and the Notification. Simply put, the Notification Provider handles the sending and resending of a Notification.
+The Notification architecture is made up of two main components: the Notification Provider and the Notification. Simply put, the Notification Provider handles the sending and resending of a Notification.

 ## Notification Provider

@@ -48,7 +48,7 @@ A Notification also represents a resent notification. So, when a notification is

 ### Notification Entity Overview

-The 2 most important properties in the `Notification` entity are the `to` and `data` properties. 
+The two most important properties in the `Notification` entity are the `to` and `data` properties. 

 The `to` property is a string that represents the receiver of the Notification. For example, if the Notification was sent to an email address, the `to` property holds the email address the Notification was sent to.

@@ -20,7 +20,7 @@ A Payment Provider in Medusa is a method to handle payments in selected regions.

 Payment Providers can be integrated with third-party services that handle payment operations such as capturing a payment. An example of a Payment Provider is Stripe.

-Payment Providers can also be related to a custom way of handling payment operations. An example of that is cash on delivery (COD) payment methods or Medusa’s [manual payment provider plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-manual) which provides a minimal implementation of a payment provider and allows store operators to manually handle order payments.
+Payment Providers can also be related to a custom way of handling payment operations. An example of that is Cash on Delivery (COD) payment methods or Medusa’s [manual payment provider plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-payment-manual) which provides a minimal implementation of a payment provider and allows store operators to manually handle order payments.

 ### How Payment Provider is Created

@@ -301,9 +301,9 @@ rm -rf node_modules
 cd <SERVER_PATH>/node_modules/<PLUGIN_NAME>
 npm install
 cd <PLUGIN_PATH>
-npm build
+npm run build
 cd <SERVER_PATH>
-npm start
+npm run start
 ```

 Where `<SERVER_PATH>` is the path to your Medusa server, `<PLUGIN_PATH>` is the path to your plugin and `<PLUGIN_NAME>` is the name of your plugin as it is in your plugin `package.json` file.
@@ -18,7 +18,7 @@ Plugins run within the same process as the core Medusa server eliminating the ne

 ### Official Plugins

-Medusa has official plugins that cover different aspects and functionalities such as payment, CMS, fulfillment, and notifications. You can check out the available plugins under the [packages directory in the Medusa repository on GitHub](https://github.com/medusajs/medusa/tree/master/packages).
+Medusa has official plugins that cover different aspects and functionalities such as payment, Content Management System (CMS), fulfillment, and notifications. You can check out the available plugins under the [packages directory in the Medusa repository on GitHub](https://github.com/medusajs/medusa/tree/master/packages).

 :::tip

@@ -2,7 +2,7 @@

 In this document, you'll learn about what Services are in Medusa.

-## What are Services?
+## What are Services

 Services in Medusa represent bundled helper methods that you want to use across your server. By convention, they represent a certain entity or functionality in your server.

@@ -77,7 +77,7 @@ constructor({}, options) {

 When the admin is creating shipping options available for customers during checkout, they choose one of the fulfillment options provided by underlying fulfillment providers.

-For example, if you’re integrating UPS as a fulfillment provider, you might support 2 fulfillment options: UPS Express Shipping and UPS Access Point.
+For example, if you’re integrating UPS as a fulfillment provider, you might support two fulfillment options: UPS Express Shipping and UPS Access Point.

 These fulfillment options are defined in the `getFulfillmentOptions` method. This method should return an array of options.

@@ -124,7 +124,7 @@ When the customer chooses a shipping option on checkout, the shipping option and

 `validateFulfillmentOption` is called when a `POST` request is sent to [`/carts/:id/shipping-methods`](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartShippingMethod).

-This method accepts 3 parameters:
+This method accepts three parameters:

 1. The shipping option data.
 2. The `data` object passed in the body of the request.
@@ -156,7 +156,7 @@ After an order is placed, it can be fulfilled either manually by the admin or us

 This method gives you access to the fulfillment being created as well as other details in case you need to perform any additional actions with the third-party provider.

-This method accepts 4 parameters:
+This method accepts four parameters:

 1. The data of the shipping method associated with the order.
 2. An array of items in the order to be fulfilled. The admin can choose all or some of the items to fulfill.
@@ -210,7 +210,7 @@ canCalculate(data) {

 This method is called on checkout when the shipping method is being created if the `price_type` of the selected shipping option is `calculated`.

-This method receives 3 parameters:
+This method receives three parameters:

 1. The `data` parameter of the selected shipping option.
 2. The `data` parameter sent with [the request](https://docs.medusajs.com/api/store/#tag/Cart/operation/PostCartsCartShippingMethod).
@@ -1,12 +1,12 @@
 # Shipping Architecture Overview

-This document gives an overview of the shipping architecture and its 4 most important components.
+This document gives an overview of the shipping architecture and its four most important components.

 ## Introduction

 In Medusa, the Shipping architecture relies on 4 components: **Fulfillment Provider**, **Shipping Profiles**, **Shipping Options**, and **Shipping Methods**.

-The distinction between the 4 is important. It has been carefully planned and put together to support all the different ecommerce use cases and shipping providers that can be integrated.
+The distinction between the four is important. It has been carefully planned and put together to support all the different ecommerce use cases and shipping providers that can be integrated.

 It’s also constructed to support multiple regions, provide different shipment configurations and options for different product types, provide promotional shipments for your customers, and much more.

@@ -8,7 +8,7 @@ It is assumed you’re already familiar with [Subscribers in Medusa and how to l

 ## Legend

-Events in this document are listed under the entity they’re associated with. They’re listed in a table of 3 columns:
+Events in this document are listed under the entity they’re associated with. They’re listed in a table of three columns:

 1. **Event Name:** The name you use to subscribe a handler for the event.
 2. **Description:** When this event is triggered.
@@ -2,7 +2,7 @@

 In this document, you'll learn what Subscribers are in Medusa.

-## What are Events?
+## What are Events

 In Medusa, there are events that are emitted when a certain action occurs. For example, if a customer places an order, the `order.placed` event is emitted with the order data.

@@ -10,7 +10,7 @@ The purpose of these events is to allow other parts of the platform, or third-pa

 Medusa's queuing and events system is handled by Redis. So, you must have [Redis configured](../../../tutorial/0-set-up-your-development-environment.mdx#redis) on your server to use subscribers.

-## What are Subscribers?
+## What are Subscribers

 Subscribers register handlers for an events and allows you to perform an action when that event occurs. For example, if you want to send your customer an email when they place an order, then you can listen to the `order.placed` event and send the email when the event is emitted.

@@ -21,7 +21,7 @@ This can be useful when some countries have the same currency but have different

 Then, Medusa handles calculating the tax amount using the tax rate and the tax-inclusive price. This is managed in the backend and relayed to accounting and analytics tools.

-## How is Tax Inclusivity Defined?
+## How is Tax Inclusivity Defined

 Tax inclusivity can be toggled for regions, currencies, price lists, and shipping options either during creation or while editing. This is represented by the boolean attribute `includes_tax` available in the entities `Region`, `Currency`, `PriceList`, and `ShippingOption`. By default, this attribute is set to `false`.

@@ -29,7 +29,7 @@ If you want to enable or disable this attribute for any of these entities, you c

 The value set for these entities can affect whether line items and shipping methods are tax inclusive or not.

-### How is Tax Inclusivity Defined for Line Items?
+### How is Tax Inclusivity Defined for Line Items

 :::info

@@ -44,7 +44,7 @@ The `LineItem` entity also has the `includes_tax` attribute. The value of this f
 - Or a price list that includes the product variant associated with the line item has the `includes_tax` attribute set to `true`, and the tax-inclusive amount of one of the variant’s prices in the price list is less than the original price of the variant;
 - Or one of the variant’s prices in the price list uses a currency or region that has the `includes_tax` attribute set to `true`, and the tax-inclusive amount of the price is less than the original price of the variant.

-### How is Tax Inclusivity Defined for Shipping Methods?
+### How is Tax Inclusivity Defined for Shipping Methods

 :::info

@@ -8,7 +8,7 @@ By default, taxes are automatically calculated by Medusa during checkout. This b

 If you disable this behavior, you must manually trigger taxes calculation. When taxes are calculated, this means that requests will be sent to the tax provider to retrieve the tax rates.

-## How to Manually Calculate Taxes in Checkout?
+## How to Manually Calculate Taxes in Checkout

 This section explores different ways you can calculate taxes based on your purpose.

@@ -4,7 +4,7 @@ Updating your medusa server to version `1.3.8` may cause issues when using NPM.

 ## Update Using Yarn

-We highly recommend using [yarn](https://yarnpkg.com/) when working with Medusa. Updating with yarn should resolve any issues you might run into during the update.
+It's highly recommended to use [yarn](https://yarnpkg.com/) when working with Medusa. Updating with yarn should resolve any issues you might run into during the update.

 ## Resolving Update Issues with NPM

@@ -7,7 +7,7 @@ This document will guide you through the steps needed to implement the checkout

 ## Overview

-A checkout flow is composed of the necessary steps to allow a customer to perform a successful checkout. It’s generally made up of 2 primary steps: the shipping and payment steps.
+A checkout flow is composed of the necessary steps to allow a customer to perform a successful checkout. It’s generally made up of two primary steps: the shipping and payment steps.

 This document will take you through the general process of a checkout flow. You should follow along with this document if you’re creating a custom storefront, if you’re adding a custom payment provider, or if you’re just interested in learning more about how checkout works in Medusa.