docs: prep for v2 documentation (#6710)

This PR includes documentation that preps for v2 docs (but doesn't introduce new docs). _Note: The number of file changes in the PR is due to find-and-replace within the `references` which is unavoidable. Let me know if I should move it to another PR._ ## Changes - Change Medusa version in base OAS used for v2. - Fix to docblock generator related to not catching all path parameters. - Added typedoc plugin that generates ER Diagrams, which will be used specifically for data model references in commerce modules. - Changed OAS tool to output references in `www/apps/api-reference/specs-v2` directory when the `--v2` option is used. - Added a version switcher to the API reference to switch between V1 and V2. This switcher is enabled by an environment variable, so it won't be visible/usable at the moment. - Upgraded docusaurus to v3.0.1 - Added new Vale rules to ensure correct spelling of Medusa Admin and module names. - Added new components to the `docs-ui` package that will be used in future documentation changes.
2024-03-18 07:47:35 +00:00
1 parent 56a6ec0227
commit bb87db8342
@@ -31,7 +31,7 @@ It is assumed that you already have a Medusa backend installed and set up. If no

 ### Required Module

-This guide assumes you have the Inventory module installed on your Medusa backend. If not, you can learn how to install it using [this guide](../install-modules.md#inventory-module).
+This guide assumes you have the Inventory Module installed on your Medusa backend. If not, you can learn how to install it using [this guide](../install-modules.md#inventory-module).

 Furthermore, inventory levels are tied to a location ID. So, it’s recommended to use the [Stock Location module](../install-modules.md#stock-location-module) if you don’t have any location logic implemented in place.

@@ -568,7 +568,7 @@ You can create a location level by sending a request to the [Create Inventory Le

 This API Route requires the inventory item ID as a path parameter. In the request body, it requires the following parameters:

- `location_id`: The ID of the location associated with this location level. This ID is typically available through using the stock location module.
+- `location_id`: The ID of the location associated with this location level. This ID is typically available through using the Stock Location Module.
 - `stocked_quantity`: A number indicating the item’s quantity in stock.

 You can also pass other optional request body parameters, as explained in the [API reference](https://docs.medusajs.com/api/admin#inventory-items_postinventoryitemsinventoryitemlocationlevels).
@@ -19,7 +19,7 @@ This guide will only explain what is required to create in your custom inventory

 :::note

-It should be noted that the Medusa backend expects the inventory module to have entities for an inventory item, an inventory level, and a reservation item, as it uses the IDs of those entities when orchestrating between different modules and the in the API Routes it exposes. You can learn more about this in the [Inventory Module Architecture documentation](../inventory-module.md).
+It should be noted that the Medusa backend expects the Inventory Module to have entities for an inventory item, an inventory level, and a reservation item, as it uses the IDs of those entities when orchestrating between different modules and the in the API Routes it exposes. You can learn more about this in the [Inventory Module Architecture documentation](../inventory-module.md).

 :::

@@ -19,7 +19,7 @@ This guide will only explain what is required to create in your custom stock loc

 :::note

-It should be noted that the Medusa backend expects the stock location module to have entities for a location and a location address, as it uses the IDs of those entities when orchestrating between different modules and the in the API Routes it exposes. You can learn more about this in the [Stock Location Module Architecture documentation](../stock-location-module.md).
+It should be noted that the Medusa backend expects the Stock Location Module to have entities for a location and a location address, as it uses the IDs of those entities when orchestrating between different modules and the in the API Routes it exposes. You can learn more about this in the [Stock Location Module Architecture documentation](../stock-location-module.md).

 :::

@@ -24,7 +24,7 @@ npm install @medusajs/inventory

 ### Step 2: Add Inventory Module to Configurations

-In `medusa-config.js`, add the inventory module to the exported object under the `modules` property:
+In `medusa-config.js`, add the Inventory Module to the exported object under the `modules` property:

 ```js
 module.exports = {
@@ -48,7 +48,7 @@ npx medusa migrations run

 ### Step 4: Run Migration Script

-After installing the Stock Location module, make sure to [run the migration script](#run-migration-script)
+After installing the Stock Location Module, make sure to [run the migration script](#run-migration-script)

 ---

@@ -64,7 +64,7 @@ npm install @medusajs/stock-location

 ### Step 2: Add Stock Location Module to Configurations

-In `medusa-config.js`, add the stock location module to the exported object under the `modules` property:
+In `medusa-config.js`, add the Stock Location Module to the exported object under the `modules` property:

 ```js
 module.exports = {
@@ -100,4 +100,4 @@ After installing both modules, run the following command to migrate current prod
 node ./node_modules/@medusajs/medusa/dist/scripts/migrate-inventory-items.js
 ```

-You can now start the Medusa backend and use the stock location module in your commerce application.
+You can now start the Medusa backend and use the Stock Location Module in your commerce application.
@@ -1,16 +1,16 @@
 ---
-description: "In this document, you’ll learn about the inventory module, how it works, and its relation to other processes in your commerce application."
+description: "In this document, you’ll learn about the Inventory Module, how it works, and its relation to other processes in your commerce application."
 ---

 # Inventory Module

-In this document, you’ll learn about the inventory module and how it works.
+In this document, you’ll learn about the Inventory Module and how it works.

 ## Overview

-The inventory module includes all functionalities related to product inventory. It implements inventory management for a product, confirming whether a product is available across inventory levels, and updating the inventory availability of a product variant at different points in the order lifecycle.
+The Inventory Module includes all functionalities related to product inventory. It implements inventory management for a product, confirming whether a product is available across inventory levels, and updating the inventory availability of a product variant at different points in the order lifecycle.

-Medusa's Inventory module is a standalone module that can be used in any commerce application, not just in a Medusa backend. This document gives a general overview of how the inventory module is designed, then explains how the Medusa core orchestrates relations and processes around this module when it's used with the Medusa backend.
+Medusa's Inventory module is a standalone module that can be used in any commerce application, not just in a Medusa backend. This document gives a general overview of how the Inventory Module is designed, then explains how the Medusa core orchestrates relations and processes around this module when it's used with the Medusa backend.

 ---

@@ -51,7 +51,7 @@ The `ReservationItem` entity has the following notable attributes, among others:

 ## How the Module Integrates into Medusa

-This section explains how the Medusa backend uses the inventory module along with its entities and other modules, and in its processes.
+This section explains how the Medusa backend uses the Inventory Module along with its entities and other modules, and in its processes.

 ### Entities Relation Overview

@@ -61,23 +61,23 @@ When you use Medusa's Inventory Module, the Medusa backend uses the `ProductVari

 ![Inventory Item's Relation to Product Variants in the Medusa Backend](https://res.cloudinary.com/dza7lstvk/image/upload/v1680185070/Medusa%20Docs/Diagrams/inventory-item-medusa-diagram_i21ht8.jpg)

-The Medusa backend also orchestrates between the installed inventory and stock location modules. The association between an Inventory Level and a location is handled by passing the ID of a location from the stock location module to the inventory module when an Inventory Level is being created. When using Medusa's [Stock Location module](./stock-location-module.md), the entity representing the location is `StockLocation`.
+The Medusa backend also orchestrates between the installed inventory and stock location modules. The association between an Inventory Level and a location is handled by passing the ID of a location from the Stock Location Module to the Inventory Module when an Inventory Level is being created. When using Medusa's [Stock Location module](./stock-location-module.md), the entity representing the location is `StockLocation`.

 ![Inventory Level's relation to Stock Location Module in the Medusa Backend](https://res.cloudinary.com/dza7lstvk/image/upload/v1680185151/Medusa%20Docs/Diagrams/inventory-medusa-diagram_ltojt9.jpg)

-Similarly, the Medusa backend associates the `ReservationItem` entity with a line item and a location by passing the IDs of each to the inventory module when a reservation item is created.
+Similarly, the Medusa backend associates the `ReservationItem` entity with a line item and a location by passing the IDs of each to the Inventory Module when a reservation item is created.

 ### Product Variant Creation Process

-In the Medusa backend, when a product variant that has an enabled `manage_inventory` attribute is created, the backend uses the inventory module to automatically create an inventory item along with the product variant. When the inventory item is created, the Medusa backend attaches it to the product variant using the `ProductVariantInventoryItem` entity as explained earlier.
+In the Medusa backend, when a product variant that has an enabled `manage_inventory` attribute is created, the backend uses the Inventory Module to automatically create an inventory item along with the product variant. When the inventory item is created, the Medusa backend attaches it to the product variant using the `ProductVariantInventoryItem` entity as explained earlier.

-The Medusa backend uses the inventory module to create Inventory Levels when the admin sets the available quantity of a product variant in a stock location.
+The Medusa backend uses the Inventory Module to create Inventory Levels when the admin sets the available quantity of a product variant in a stock location.

 ### Cart and Checkout

-During the cart and checkout workflow, for example when a product variant is added to the cart or during cart validation, the Medusa backend uses the inventory module to confirm that items in the cart have sufficient stock to be purchased in the desired quantity. If a product variant doesn't have an inventory item, which is the case when the `manage_inventory` attribute of the variant is disabled, the variant is assumed to be available in stock.
+During the cart and checkout workflow, for example when a product variant is added to the cart or during cart validation, the Medusa backend uses the Inventory Module to confirm that items in the cart have sufficient stock to be purchased in the desired quantity. If a product variant doesn't have an inventory item, which is the case when the `manage_inventory` attribute of the variant is disabled, the variant is assumed to be available in stock.

-As an inventory item can exist in multiple locations, the inventory module checks across those locations. The Medusa backend retrieves the locations based on the sales channel of the cart, as each location is associated with a sales channel, and passes them along to the inventory module to perform the checking.
+As an inventory item can exist in multiple locations, the Inventory Module checks across those locations. The Medusa backend retrieves the locations based on the sales channel of the cart, as each location is associated with a sales channel, and passes them along to the Inventory Module to perform the checking.

 :::tip

@@ -85,18 +85,18 @@ You can learn more about the relation between Stock Locations and Sales Channels

 :::

-Then, the inventory module confirms that the product variant has sufficient quantity across these locations by summing all the `stocked_quantity` of the inventory levels associated with these locations. When retrieving the `stocked_quantity` of each of the inventory levels, the `reserved_quantity` is subtracted from it to ensure accurate availability.
+Then, the Inventory Module confirms that the product variant has sufficient quantity across these locations by summing all the `stocked_quantity` of the inventory levels associated with these locations. When retrieving the `stocked_quantity` of each of the inventory levels, the `reserved_quantity` is subtracted from it to ensure accurate availability.

 ### Order Placement

-When an order is placed, the Medusa backend uses the inventory module to reserve the ordered quantity of line items that are associated with product variants having an enabled `manage_inventory` attribute. The reserved quantity is indicated by creating a reservation item for each line item, associating it with its inventory item and a stock location.
+When an order is placed, the Medusa backend uses the Inventory Module to reserve the ordered quantity of line items that are associated with product variants having an enabled `manage_inventory` attribute. The reserved quantity is indicated by creating a reservation item for each line item, associating it with its inventory item and a stock location.

 The Medusa backend chooses the stock location randomly from the available stock locations associated with the order’s sales channel. The admin can later change which stock location the item will be fulfilled from.

 ### Order Fulfillment

-When an item in the order is fulfilled, and the item is associated with a product variant that has an enabled `manage_inventory`, the Medusa backend uses the inventory module to subtract the inventory level's `reserved_quantity` from the `stocked_quantity`. The inventory module also resets the `reserved_quantity` to `0`.
+When an item in the order is fulfilled, and the item is associated with a product variant that has an enabled `manage_inventory`, the Medusa backend uses the Inventory Module to subtract the inventory level's `reserved_quantity` from the `stocked_quantity`. The Inventory Module also resets the `reserved_quantity` to `0`.

 ### Order Return

-When an item in the order is returned, and the item is associated with a product variant that has an enabled `manage_inventory`, the Medusa backend uses the inventory module to increment the inventory level's `stocked_quantity` with the returned amount.
+When an item in the order is returned, and the item is associated with a product variant that has an enabled `manage_inventory`, the Medusa backend uses the Inventory Module to increment the inventory level's `stocked_quantity` with the returned amount.
@@ -60,7 +60,7 @@ Admins can manage the stock locations, which are the places they store their pro
    label: 'User Guide: Manage Stock Locations',
    customProps: {
      icon: Icons['users-solid'],
-      description: 'Learn how to manage stock locations in Medusa admin.'
+      description: 'Learn how to manage stock locations in Medusa Admin.'
    }
  },
  {
@@ -85,7 +85,7 @@ Admins can manage the inventory of product variants across the different stock l
    label: 'User Guide: Manage Inventory',
    customProps: {
      icon: Icons['users-solid'],
-      description: 'Learn how to manage inventory using the Medusa admin.'
+      description: 'Learn how to manage inventory using the Medusa Admin.'
    }
  },
  {
@@ -110,7 +110,7 @@ Admins can manage item allocations to choose which stock location to fulfill ite
    label: 'User Guide: Manage Allocations in Orders',
    customProps: {
      icon: Icons['users-solid'],
-      description: 'Learn how to manage allocations of items in an order using the Medusa admin.'
+      description: 'Learn how to manage allocations of items in an order using the Medusa Admin.'
    }
  },
  {
@@ -1,16 +1,16 @@
 ---
-description: "In this document, you’ll learn about the inventory module, how it works, and its relation to other processes in your commerce application."
+description: "In this document, you’ll learn about the Inventory Module, how it works, and its relation to other processes in your commerce application."
 ---

 # Stock Location Module

-In this document, you’ll learn about the Stock Location module and how it works.
+In this document, you’ll learn about the Stock Location Module and how it works.

 ## Overview

-A stock location indicates a physical address that stock-kept items can be stored in. The Stock Location module handles functionalities related to managing stock locations and their addresses.
+A stock location indicates a physical address that stock-kept items can be stored in. The Stock Location Module handles functionalities related to managing stock locations and their addresses.

-Medusa's Stock Location module is a standalone module that can be used in any commerce application, not just in a Medusa backend. This document gives a general overview of how the stock location module is designed, and highlights how the Medusa core orchestrates relations around this module when it's used with the Medusa backend.
+Medusa's Stock Location module is a standalone module that can be used in any commerce application, not just in a Medusa backend. This document gives a general overview of how the Stock Location Module is designed, and highlights how the Medusa core orchestrates relations around this module when it's used with the Medusa backend.

 ---

@@ -30,7 +30,7 @@ The `StockLocationAddress` entity belongs to the `StockLocation` entity. It is u

 ## How the Module Integrates into Medusa

-This section explains how the Medusa backend uses the stock location module along with its entities and other modules.
+This section explains how the Medusa backend uses the Stock Location Module along with its entities and other modules.

 ### Entities Relation Overview

@@ -48,7 +48,7 @@ The Medusa backend also orchestrates between different modules. The [Inventory M
 - `InventoryLevel`: This entity is used to indicate the stocked quantity of an inventory item in a stock location. As explained in the [Inventory Module documentation](./inventory-module.md#inventorylevel), the `InventoryLevel` entity has an attribute `location_id`.
 - `ReservationItem`: This entity is used to indicate the reserved quantity of an inventory item in a stock location. As explained in the [Inventory Module documentation](./inventory-module.md#reservationitem), the `ReservationItem` entity has an attribute `location_id`.

-When both modules are used within the Medusa backend, the Medusa backend bridges between these modules by passing the ID of a `StockLocation` from the stock location module to the inventory module, and the inventory module uses the ID in its entities.
+When both modules are used within the Medusa backend, the Medusa backend bridges between these modules by passing the ID of a `StockLocation` from the Stock Location Module to the Inventory Module, and the Inventory Module uses the ID in its entities.

 ### Relation to SalesChannel

@@ -58,6 +58,6 @@ As the `StockLocation` and `SalesChannel` entities are available in separate mod

 This relation is used across the Medusa backend and within checkout and order workflows:

- When checking the availability of an inventory item during checkout, the Medusa backend retrieves the location IDs that are associated with the cart’s sales channel using the `SalesChannelLocation`, then passes it along to the inventory module to perform the quantity check.
- When an order is placed, the Medusa backend retrieves the location IDs that are associated with the cart’s sales channel using the `SalesChannelLocation` entity, and passes it to the inventory module that reserves the ordered quantity of the inventory item from that location. The admin can later change the stock location if necessary.
- When an item in an order is fulfilled, the admin chooses a stock location to fulfill the item from. Similarly, when an item in an order is returned, the admin can choose a stock location to return the item to. The Medusa backend then passes the ID of the location from the stock module to the inventory module to perform inventory management functionalities.
+- When checking the availability of an inventory item during checkout, the Medusa backend retrieves the location IDs that are associated with the cart’s sales channel using the `SalesChannelLocation`, then passes it along to the Inventory Module to perform the quantity check.
+- When an order is placed, the Medusa backend retrieves the location IDs that are associated with the cart’s sales channel using the `SalesChannelLocation` entity, and passes it to the Inventory Module that reserves the ordered quantity of the inventory item from that location. The admin can later change the stock location if necessary.
+- When an item in an order is fulfilled, the admin chooses a stock location to fulfill the item from. Similarly, when an item in an order is returned, the admin can choose a stock location to return the item to. The Medusa backend then passes the ID of the location from the Stock Location Module to the Inventory Module to perform inventory management functionalities.