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.
This commit is contained in:
Shahed Nasser
GitHub
@@ -1,74 +0,0 @@
|
||||
"use client"
|
||||
|
||||
import {
|
||||
createContext,
|
||||
useCallback,
|
||||
useContext,
|
||||
useEffect,
|
||||
useState,
|
||||
} from "react"
|
||||
|
||||
type ColorMode = "light" | "dark"
|
||||
|
||||
type ColorModeContextType = {
|
||||
colorMode: ColorMode
|
||||
setColorMode: (value: ColorMode) => void
|
||||
toggleColorMode: () => void
|
||||
}
|
||||
|
||||
const ColorModeContext = createContext<ColorModeContextType | null>(null)
|
||||
|
||||
type ColorModeProviderProps = {
|
||||
children: React.ReactNode
|
||||
}
|
||||
|
||||
const ColorModeProvider = ({ children }: ColorModeProviderProps) => {
|
||||
const [colorMode, setColorMode] = useState<ColorMode>("light")
|
||||
|
||||
const toggleColorMode = () =>
|
||||
setColorMode(colorMode === "light" ? "dark" : "light")
|
||||
|
||||
const init = () => {
|
||||
const theme = localStorage.getItem("theme")
|
||||
if (theme && (theme === "light" || theme === "dark")) {
|
||||
setColorMode(theme)
|
||||
}
|
||||
}
|
||||
|
||||
useEffect(() => {
|
||||
init()
|
||||
}, [])
|
||||
|
||||
useEffect(() => {
|
||||
const theme = localStorage.getItem("theme")
|
||||
if (theme !== colorMode) {
|
||||
localStorage.setItem("theme", colorMode)
|
||||
}
|
||||
|
||||
document.querySelector("html")?.setAttribute("data-theme", colorMode)
|
||||
}, [colorMode])
|
||||
|
||||
return (
|
||||
<ColorModeContext.Provider
|
||||
value={{
|
||||
colorMode,
|
||||
setColorMode,
|
||||
toggleColorMode,
|
||||
}}
|
||||
>
|
||||
{children}
|
||||
</ColorModeContext.Provider>
|
||||
)
|
||||
}
|
||||
|
||||
export default ColorModeProvider
|
||||
|
||||
export const useColorMode = (): ColorModeContextType => {
|
||||
const context = useContext(ColorModeContext)
|
||||
|
||||
if (!context) {
|
||||
throw new Error("useColorMode must be used inside a ColorModeProvider")
|
||||
}
|
||||
|
||||
return context
|
||||
}
|
||||
@@ -1,18 +1,17 @@
|
||||
"use client"
|
||||
|
||||
import {
|
||||
AiAssistantProvider,
|
||||
AnalyticsProvider,
|
||||
ColorModeProvider,
|
||||
MobileProvider,
|
||||
ModalProvider,
|
||||
NavbarProvider,
|
||||
PageLoadingProvider,
|
||||
ScrollControllerProvider,
|
||||
} from "docs-ui"
|
||||
import BaseSpecsProvider from "./base-specs"
|
||||
import SidebarProvider from "./sidebar"
|
||||
import SearchProvider from "./search"
|
||||
import VersionProvider from "./version"
|
||||
|
||||
type ProvidersProps = {
|
||||
children?: React.ReactNode
|
||||
@@ -27,11 +26,11 @@ const Providers = ({ children }: ProvidersProps) => {
|
||||
<BaseSpecsProvider>
|
||||
<ScrollControllerProvider scrollableSelector="#main">
|
||||
<SidebarProvider>
|
||||
<NavbarProvider>
|
||||
<SearchProvider>
|
||||
<MobileProvider>{children}</MobileProvider>
|
||||
</SearchProvider>
|
||||
</NavbarProvider>
|
||||
<SearchProvider>
|
||||
<MobileProvider>
|
||||
<VersionProvider>{children}</VersionProvider>
|
||||
</MobileProvider>
|
||||
</SearchProvider>
|
||||
</SidebarProvider>
|
||||
</ScrollControllerProvider>
|
||||
</BaseSpecsProvider>
|
||||
|
||||
@@ -5,8 +5,9 @@ import {
|
||||
SearchProvider as UiSearchProvider,
|
||||
AiAssistantCommandIcon,
|
||||
AiAssistantProvider,
|
||||
searchFilters,
|
||||
} from "docs-ui"
|
||||
import getBaseUrl from "../utils/get-base-url"
|
||||
import { config } from "../config"
|
||||
|
||||
type SearchProviderProps = {
|
||||
children: React.ReactNode
|
||||
@@ -29,47 +30,30 @@ const SearchProvider = ({ children }: SearchProviderProps) => {
|
||||
isLoading,
|
||||
suggestions: [
|
||||
{
|
||||
title: "Search Suggestions",
|
||||
title: "Getting started? Try one of the following terms.",
|
||||
items: [
|
||||
"Authentication",
|
||||
"Expanding fields",
|
||||
"Selecting fields",
|
||||
"Pagination",
|
||||
"Query parameter types",
|
||||
"Install Medusa with create-medusa-app",
|
||||
"Next.js quickstart",
|
||||
"Admin dashboard quickstart",
|
||||
"Commerce modules",
|
||||
"Medusa architecture",
|
||||
],
|
||||
},
|
||||
{
|
||||
title: "Developing with Medusa",
|
||||
items: [
|
||||
"Recipes",
|
||||
"How to create API routes",
|
||||
"How to create an entity",
|
||||
"How to create a plugin",
|
||||
"How to create an admin widget",
|
||||
],
|
||||
},
|
||||
],
|
||||
checkInternalPattern: new RegExp(`^${getBaseUrl()}/api/(admin|store)`),
|
||||
filterOptions: [
|
||||
{
|
||||
value: "admin",
|
||||
label: "Admin API",
|
||||
},
|
||||
{
|
||||
value: "store",
|
||||
label: "Store API",
|
||||
},
|
||||
{
|
||||
value: "docs",
|
||||
label: "Docs",
|
||||
},
|
||||
{
|
||||
value: "user-guide",
|
||||
label: "User Guide",
|
||||
},
|
||||
{
|
||||
value: "plugins",
|
||||
label: "Plugins",
|
||||
},
|
||||
{
|
||||
value: "reference",
|
||||
label: "References",
|
||||
},
|
||||
{
|
||||
value: "ui",
|
||||
label: "UI",
|
||||
},
|
||||
],
|
||||
checkInternalPattern: new RegExp(
|
||||
`^${config.baseUrl}/api/(admin|store)`
|
||||
),
|
||||
filterOptions: searchFilters,
|
||||
}}
|
||||
commands={[
|
||||
{
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
"use client"
|
||||
import {
|
||||
SidebarProvider as UiSidebarProvider,
|
||||
mobileSidebarItems,
|
||||
usePageLoading,
|
||||
useScrollController,
|
||||
} from "docs-ui"
|
||||
import { config } from "../config"
|
||||
|
||||
type SidebarProviderProps = {
|
||||
children?: React.ReactNode
|
||||
@@ -19,42 +21,7 @@ const SidebarProvider = ({ children }: SidebarProviderProps) => {
|
||||
setIsLoading={setIsLoading}
|
||||
shouldHandleHashChange={true}
|
||||
scrollableElement={scrollableElement}
|
||||
initialItems={{
|
||||
top: [
|
||||
{
|
||||
title: "Introduction",
|
||||
path: "",
|
||||
loaded: true,
|
||||
},
|
||||
],
|
||||
bottom: [],
|
||||
mobile: [
|
||||
{
|
||||
title: "Docs",
|
||||
path: "https://docs.medusajs.com/",
|
||||
loaded: true,
|
||||
isPathHref: true,
|
||||
},
|
||||
{
|
||||
title: "User Guide",
|
||||
path: "https://docs.medusajs.com/user-guide",
|
||||
loaded: true,
|
||||
isPathHref: true,
|
||||
},
|
||||
{
|
||||
title: "Store API",
|
||||
path: "/api/store",
|
||||
loaded: true,
|
||||
isPathHref: true,
|
||||
},
|
||||
{
|
||||
title: "Admin API",
|
||||
path: "/api/admin",
|
||||
loaded: true,
|
||||
isPathHref: true,
|
||||
},
|
||||
],
|
||||
}}
|
||||
initialItems={config.sidebar}
|
||||
>
|
||||
{children}
|
||||
</UiSidebarProvider>
|
||||
|
||||
74
www/apps/api-reference/providers/version.tsx
Normal file
74
www/apps/api-reference/providers/version.tsx
Normal file
@@ -0,0 +1,74 @@
|
||||
"use client"
|
||||
|
||||
import { createContext, useContext, useEffect, useState } from "react"
|
||||
import { Version } from "../types/openapi"
|
||||
import { usePathname } from "next/navigation"
|
||||
import { useIsBrowser } from "docs-ui"
|
||||
|
||||
type VersionContextType = {
|
||||
version: Version
|
||||
changeVersion: (value: Version) => void
|
||||
}
|
||||
|
||||
const VersionContext = createContext<VersionContextType | null>(null)
|
||||
|
||||
type VersionProviderProps = {
|
||||
children: React.ReactNode
|
||||
}
|
||||
|
||||
const VersionProvider = ({ children }: VersionProviderProps) => {
|
||||
const pathname = usePathname()
|
||||
const [version, setVersion] = useState<Version>("1")
|
||||
const isBrowser = useIsBrowser()
|
||||
|
||||
const changeVersion = (version: Version) => {
|
||||
if (!isBrowser || process.env.NEXT_PUBLIC_VERSIONING !== "true") {
|
||||
return
|
||||
}
|
||||
localStorage.setItem("api-version", version)
|
||||
|
||||
location.href = `${location.href.substring(
|
||||
0,
|
||||
location.href.indexOf(location.pathname)
|
||||
)}${pathname}`
|
||||
}
|
||||
|
||||
useEffect(() => {
|
||||
if (!isBrowser || process.env.NEXT_PUBLIC_VERSIONING !== "true") {
|
||||
return
|
||||
}
|
||||
// try to load from localstorage
|
||||
const versionInLocalStorage = localStorage.getItem("api-version") as Version
|
||||
if (versionInLocalStorage) {
|
||||
setVersion(versionInLocalStorage)
|
||||
}
|
||||
}, [isBrowser])
|
||||
|
||||
useEffect(() => {
|
||||
if (!isBrowser || process.env.NEXT_PUBLIC_VERSIONING !== "true") {
|
||||
return
|
||||
}
|
||||
const versionInLocalStorage = localStorage.getItem("api-version") as Version
|
||||
if (version !== versionInLocalStorage) {
|
||||
localStorage.setItem("api-version", version)
|
||||
}
|
||||
}, [version, isBrowser])
|
||||
|
||||
return (
|
||||
<VersionContext.Provider value={{ version, changeVersion }}>
|
||||
{children}
|
||||
</VersionContext.Provider>
|
||||
)
|
||||
}
|
||||
|
||||
export default VersionProvider
|
||||
|
||||
export const useVersion = (): VersionContextType => {
|
||||
const context = useContext(VersionContext)
|
||||
|
||||
if (!context) {
|
||||
throw new Error("useVersion must be used inside an VersionProvider")
|
||||
}
|
||||
|
||||
return context
|
||||
}
|
||||
Reference in New Issue
Block a user