docs: API docs generation and refactor (#659)

* refactor: docs reorganization * feat(workflow): auto build public API to docs * feat: update generate docs script
elgohr-update · Apr 27, 2020 · 66b4ff6 · 66b4ff6
1 parent a41e67b
commit 66b4ff6
Show file tree

Hide file tree

Showing 65 changed files with 1,324 additions and 176 deletions.
diff --git a/.gitignore b/.gitignore
@@ -8,9 +8,6 @@ temp
 local
 explorations
 TODOs.md
-docs/*
-!docs/roadmap.md
-!docs/assets
 .history
 
 # Files generated by local published packages

diff --git a/README.md b/README.md
@@ -40,8 +40,6 @@ See [the documentation](https://shopware-pwa-docs.netlify.com/#introduction-to-s
 
 If you have any questions or ideas feel free to join our slack: https://vuestorefront.slack.com via [invitation link](http://slack.vuestorefront.io/)
 
-## Getting started
-
 ## Quickstart
 
 ### Installation
@@ -62,6 +60,7 @@ Currently, we're releasing a `canary` version per every push to `master` branch,
 ```bash
 npm install -g @shopware-pwa/cli@canary
 ```
+
 :::
 
 ### Usage
@@ -93,13 +92,14 @@ Now you have complete ShopwarePWA project running locally.
 You can simply invoke once again `shopware-pwa init` and pass data to your custom instance.
 
 Another way of doing this:
+
 1. edit file `shopware-pwa.config.js` inside the root of the newly created project
 2. fill it with your data, current example:
 
 ```js
 module.exports = {
   shopwareEndpoint: "https://shopware-2.vuestorefront.io",
-  shopwareAccessToken: "SWSCTXJOZMQWCXA4OUTNZ0REYG"
+  shopwareAccessToken: "SWSCTXJOZMQWCXA4OUTNZ0REYG",
 };
 ```
 
@@ -127,6 +127,7 @@ If you want to update to `canary` version, just add this to update command. If y
 ```bash
 npm install -g @shopware-pwa/cli@canary
 ```
+
 :::
 
 ### Running with plugins

diff --git a/api-extractor.json b/api-extractor.json
@@ -33,7 +33,7 @@
       },
 
       "ae-missing-release-tag": {
-        "logLevel": "none"
+        "logLevel": "warning"
       }
     },
 

diff --git a/api/composables.api.md b/api/composables.api.md
@@ -89,7 +89,7 @@ export const useCartSidebar: () => any;
 // @alpha (undocumented)
 export const useCategoryFilters: () => any;
 
-// @alpha (undocumented)
+// @beta (undocumented)
 export interface UseCheckout {
     // (undocumented)
     billingAddress: Readonly<Ref<BillingAddress | undefined>>;

diff --git a/api/helpers.api.md b/api/helpers.api.md
@@ -14,10 +14,6 @@ import { Salutation } from '@shopware-pwa/commons/interfaces/models/system/salut
 import { SearchCriteria } from '@shopware-pwa/commons/interfaces/search/SearchCriteria';
 import { ShopwareError } from '@shopware-pwa/commons/interfaces/errors/ApiError';
 import { Sort } from '@shopware-pwa/commons/interfaces/search/SearchCriteria';
-import { UiMediaGalleryItem as UiMediaGalleryItem_2 } from '@shopware-pwa/helpers';
-import { UiProductOption as UiProductOption_2 } from '@shopware-pwa/helpers';
-import { UiProductProperty as UiProductProperty_2 } from '@shopware-pwa/helpers';
-import { UiProductReview as UiProductReview_2 } from '@shopware-pwa/helpers';
 
 // @alpha (undocumented)
 export interface CategoryFilterEntityValue {
@@ -56,6 +52,16 @@ export interface CategoryFilterTermValue {
 // @alpha (undocumented)
 export function exportUrlQuery(searchCriteria: SearchCriteria): string | undefined;
 
+// @alpha (undocumented)
+export interface Filter {
+    // (undocumented)
+    [filterCode: string]: {
+        type: UiCategoryFilterType;
+        name: string;
+        values: CategoryFilterRangeValues | CategoryFilterEntityValues | CategoryFilterTermValue[];
+    };
+}
+
 // @alpha (undocumented)
 export function getCategoryAvailableFilters({ filters, }?: {
     filters?: Filter;
@@ -72,11 +78,9 @@ export function getCmsSections(content: CmsPage): CmsSection[];
 // @alpha (undocumented)
 export const getFilterSearchCriteria: (selectedFilters: any) => any[];
 
-// @public
+// @alpha
 export function getMessagesFromErrorsArray(errors: ShopwareError[]): string[];
 
-// Warning: (ae-forgotten-export) The symbol "NavigationRoute" needs to be exported by the entry point index.d.ts
-//
 // @alpha (undocumented)
 export function getNavigationRoutes(navigationElements: NavigationElement[]): NavigationRoute[];
 
@@ -86,7 +90,7 @@ export function getProductMainImageUrl(product: Product): string;
 // @alpha (undocumented)
 export function getProductMediaGallery({ product, }?: {
     product?: Product;
-}): UiMediaGalleryItem_2[];
+}): UiMediaGalleryItem[];
 
 // @alpha (undocumented)
 export function getProductName({ product }?: {
@@ -99,8 +103,6 @@ export function getProductOption({ product, attribute, }?: {
     attribute?: string;
 }): PropertyGroupOption | undefined;
 
-// Warning: (ae-forgotten-export) The symbol "ProductOptions" needs to be exported by the entry point index.d.ts
-//
 // @alpha (undocumented)
 export function getProductOptions({ product, }?: {
     product?: Product;
@@ -115,7 +117,7 @@ export function getProductOptionsUrl({ product, options, }?: {
 // @alpha (undocumented)
 export function getProductProperties({ product, }?: {
     product?: Product;
-}): UiProductProperty_2[];
+}): UiProductProperty[];
 
 // @alpha (undocumented)
 export function getProductRegularPrice({ product, }?: {
@@ -125,7 +127,7 @@ export function getProductRegularPrice({ product, }?: {
 // @alpha (undocumented)
 export function getProductReviews({ product, }?: {
     product?: Product;
-}): UiProductReview_2[];
+}): UiProductReview[];
 
 // @alpha (undocumented)
 export function getProductSpecialPrice(product: Product): number;
@@ -144,7 +146,7 @@ export function getVariantOptionsLabel({ product, }?: {
     product?: Product;
 }): string | null;
 
-// @alpha (undocumented)
+// @beta (undocumented)
 export function isProductSimple({ product, }?: {
     product?: Product;
 }): boolean;
@@ -171,9 +173,32 @@ export interface MappedSalutation {
 // @alpha
 export function mapSalutations(salutations: Salutation[]): MappedSalutation[];
 
+// @alpha (undocumented)
+export interface NavigationRoute {
+    // (undocumented)
+    routeLabel: string;
+    // (undocumented)
+    routePath: string;
+}
+
 // @alpha (undocumented)
 export function parseUrlQuery(query: any): SearchCriteria;
 
+// @alpha (undocumented)
+export interface ProductOptions {
+    // (undocumented)
+    [attribute: string]: UiProductOption[];
+}
+
+// @alpha (undocumented)
+export interface Sorting {
+    // (undocumented)
+    [sortingCode: string]: {
+        key: string;
+        active: boolean;
+    };
+}
+
 // @alpha (undocumented)
 export interface SwSorting {
     // (undocumented)
@@ -293,11 +318,6 @@ export interface UiProductReview {
 }
 
 
-// Warnings were encountered during analysis:
-//
-// dist/packages/helpers/src/category/getCategoryAvailableFilters.d.ts:42:5 - (ae-forgotten-export) The symbol "Filter" needs to be exported by the entry point index.d.ts
-// dist/packages/helpers/src/category/getCategoryAvailableSorting.d.ts:12:5 - (ae-forgotten-export) The symbol "Sorting" needs to be exported by the entry point index.d.ts
-
 // (No @packageDocumentation comment for this package)
 
 ```
diff --git a/api/shopware-6-client.api.md b/api/shopware-6-client.api.md
@@ -47,12 +47,24 @@ export function changeCartItemQuantity(itemId: string, newQuantity?: number): Pr
 // @alpha
 export function clearCart(): Promise<ContextTokenResponse>;
 
-// Warning: (ae-forgotten-export) The symbol "ClientSettings" needs to be exported by the entry point index.d.ts
-//
+// @beta (undocumented)
+export interface ClientSettings {
+    // (undocumented)
+    accessToken?: string;
+    // (undocumented)
+    contextToken?: string;
+    // (undocumented)
+    defaultPaginationLimit?: number;
+    // (undocumented)
+    endpoint?: string;
+    // (undocumented)
+    timeout?: number;
+}
+
 // @beta (undocumented)
 export const config: ClientSettings;
 
-// @alpha (undocumented)
+// @beta (undocumented)
 export interface ConfigChangedArgs {
     // (undocumented)
     config: ClientSettings;
@@ -139,19 +151,19 @@ export function getCategories(searchCriteria?: SearchCriteria): Promise<SearchRe
 // @alpha (undocumented)
 export function getCategory(categoryId: string): Promise<Category>;
 
-// @alpha
+// @beta
 export function getCustomer(): Promise<Customer | null>;
 
 // @alpha
 export function getCustomerAddress(addressId: string): Promise<CustomerAddress>;
 
-// @alpha
+// @beta
 export function getCustomerAddresses(): Promise<CustomerAddress[]>;
 
 // @alpha
 export function getCustomerOrderDetails(orderId: string): Promise<Order>;
 
-// @alpha
+// @beta
 export function getCustomerOrders(): Promise<Order[]>;
 
 // @alpha (undocumented)
@@ -186,16 +198,16 @@ export function getUserCountry(countryId: string): Promise<Country>;
 // @alpha (undocumented)
 export function getUserSalutation(salutationId: string): Promise<Salutation>;
 
-// @alpha
+// @beta
 export function login({ username, password, }?: {
     username?: string;
     password?: string;
 }): Promise<ContextTokenResponse>;
 
-// @alpha
+// @beta
 export function logout(): Promise<void>;
 
-// @alpha (undocumented)
+// @beta (undocumented)
 export function onConfigChange(fn: (context: ConfigChangedArgs) => void): void;
 
 // @alpha (undocumented)
@@ -240,7 +252,7 @@ export function setDefaultCustomerBillingAddress(addressId: string): Promise<str
 // @alpha
 export function setDefaultCustomerShippingAddress(addressId: string): Promise<string>;
 
-// @alpha
+// @beta
 export function setup(config?: ClientSettings): void;
 
 // @alpha (undocumented)
@@ -261,7 +273,7 @@ export interface ShopwareParams {
     term?: string;
 }
 
-// @alpha
+// @beta
 export function update(config?: ClientSettings): void;
 
 // @alpha

diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -1,13 +1,84 @@
-const getConfig = require("vuepress-bar");
-const barConfig = getConfig(`${__dirname}/..`);
-
 module.exports = {
   title: "Shopware-PWA",
   description: "Headless PWA for Shopware",
   themeConfig: {
-    sidebar: barConfig.sidebar,
     repo: "DivanteLtd/shopware-pwa",
     docsDir: "docs",
-    sidebarDepth: 2
-  }
+    sidebarDepth: 2,
+    smoothScroll: true,
+    sidebar: {
+      "/cli/": [""],
+      "/api/": [
+        {
+          title: "API",
+          path: "",
+          collapsable: false,
+          children: [
+            { title: "Composables", path: "composables" },
+            { title: "Helpers", path: "helpers" },
+            { title: "Shopware 6 client", path: "shopware-6-client" },
+          ],
+        },
+      ],
+      "/": [""],
+    },
+    nav: (module.exports = [
+      {
+        text: "Guide",
+        items: [
+          {
+            text: "Setup",
+            items: [
+              {
+                text: "Cheatsheet",
+                link: "/guide/cheatsheet.html",
+              },
+            ],
+          },
+          {
+            text: "Help",
+            items: [
+              {
+                text: "FAQ / Troubleshooting",
+                link: "/guide/troubleshooting.html",
+              },
+              {
+                text: "Roadmap",
+                link: "/guide/roadmap.html",
+              },
+            ],
+          },
+        ],
+      },
+      {
+        text: "CLI",
+        link: "/cli/",
+      },
+      {
+        text: "API",
+        link: "/API/index.md",
+      },
+      {
+        text: "Contribution",
+        items: [
+          {
+            text: "Contribution guide",
+            link: "/contribution/contributing.html",
+          },
+          {
+            text: "Project structure",
+            link: "/contribution/structure.html",
+          },
+        ],
+      },
+      // {
+      //   text: "Plugin",
+      //   link: "/plugin/",
+      // },
+      // {
+      //   text: "Theme",
+      //   link: "/theme/",
+      // },
+    ]),
+  },
 };
-Original file line number
+Diff line change
@@ Expand Up / @@ -33,7 +33,7 @@ @@
           },
           "ae-missing-release-tag": {
-            "logLevel": "none"
+            "logLevel": "warning"
           }
         },
@@ Expand Down @@