@cparra/apexdocs 3.0.0-rc.0 → 3.0.0

package/examples/imported/scripts/process-docs.mjs

@@ -0,0 +1,16 @@
+// Substitute the import location for '@cparra/apexdocs'
+import { process } from '../../../dist/index.js';
+
+const config = {
+  sourceDir: 'force-app',
+  targetGenerator: 'markdown',
+  scope: ['global', 'public', 'private'],
+};
+
+process(config)
+  .then(() => {
+    console.log('Finished processing');
+  })
+  .catch((error) => {
+    console.error(error);
+  });

package/examples/imported/sfdx-project.json

@@ -0,0 +1,12 @@
+{
+  "packageDirectories": [
+    {
+      "path": "force-app",
+      "default": true
+    }
+  ],
+  "name": "plain-markdown",
+  "namespace": "",
+  "sfdcLoginUrl": "https://login.salesforce.com",
+  "sourceApiVersion": "59.0"
+}

package/examples/markdown/README.md

@@ -0,0 +1,7 @@
+# Markdown Example
+
+This project contains an example for generating simple markdown documentation.
+
+It has no integrations with a Static Site Generator (SSG) or any other tool.
+
+You can find the configuration in the `package.json` file, under the `apexdocs` key.

package/examples/markdown-jsconfig/README.md

@@ -0,0 +1,9 @@
+# Markdown with JS Config Example
+
+This project contains an example for generating simple markdown documentation.
+
+It has no integrations with a Static Site Generator (SSG) or any other tool.
+
+The configuration is powered by a JavaScript file, `apexdocs.config.js`. In it you will
+find it uses a few of the configuration hooks that are available, which allow you to customize
+the output of the documentation.

package/examples/markdown-jsconfig/apexdocs.config.mjs

@@ -4,6 +4,7 @@ export default defineMarkdownConfig({
   sourceDir: 'force-app',
   scope: ['global', 'public', 'protected', 'private', 'namespaceaccessible'],
   namespace: 'ns',
+  referenceGuideTitle: 'Custom Title',
   transformReferenceGuide: () => {
     return {
       frontmatter: {

package/examples/markdown-jsconfig/docs/index.md

@@ -2,7 +2,7 @@
 title: ApexDocs Reference Guide
 ---
 
-# Apex Reference Guide
+# Custom Title
 
 ## Miscellaneous
 

package/examples/open-api/README.md

@@ -0,0 +1,5 @@
+# OpenApi Example
+
+This project contains an example for generating OpenAPI documentation from your Apex source code.
+
+The configuration can be found in the `package.json` file, under the `apexdocs` key.

package/examples/open-api/docs/openapi.json

@@ -9,574 +9,6 @@
       "url": "/services/apexrest/openapi/"
     }
   ],
-  "paths": {
-    "AccountService/": {
-      "description": "Account related operations",
-      "get": {
-        "tags": [
-          "Account Service"
-        ],
-        "description": "This is a sample HTTP Get method",
-        "parameters": [
-          {
-            "name": "limit",
-            "in": "query",
-            "required": true,
-            "description": "Limits the number of items on a page",
-            "schema": {
-              "type": "integer"
-            }
-          },
-          {
-            "name": "complex",
-            "in": "cookie",
-            "description": "A more complex schema",
-            "schema": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "properties": {
-                  "name": {
-                    "type": "string"
-                  }
-                }
-              }
-            }
-          }
-        ],
-        "responses": {
-          "100": {
-            "description": "Status code 100",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "anotherObject": {
-                      "description": "An object inside of an object",
-                      "type": "object",
-                      "properties": {
-                        "message": {
-                          "type": "string"
-                        },
-                        "somethingElse": {
-                          "type": "number"
-                        }
-                      }
-                    }
-                  }
-                }
-              }
-            }
-          },
-          "200": {
-            "description": "Status code 200",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "id": {
-                      "type": "string",
-                      "description": "The super Id."
-                    },
-                    "name": {
-                      "type": "string"
-                    },
-                    "phone": {
-                      "type": "string",
-                      "format": "byte"
-                    }
-                  }
-                }
-              }
-            }
-          },
-          "304": {
-            "description": "Status code 304",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "error": {
-                      "type": "string"
-                    }
-                  }
-                }
-              }
-            }
-          },
-          "400": {
-            "description": "Status code 400",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "name": {
-                        "type": "string"
-                      }
-                    }
-                  }
-                }
-              }
-            }
-          },
-          "500": {
-            "description": "Status code 500",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "string"
-                }
-              }
-            }
-          }
-        }
-      },
-      "post": {
-        "tags": [
-          "Account Service"
-        ],
-        "description": "This is a sample HTTP Post method",
-        "summary": "Posts an Account 2",
-        "requestBody": {
-          "description": "This is an example of a request body",
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "array",
-                "items": {
-                  "type": "object",
-                  "properties": {
-                    "name": {
-                      "type": "string"
-                    }
-                  }
-                }
-              }
-            }
-          },
-          "required": true
-        },
-        "parameters": [
-          {
-            "name": "limit",
-            "in": "query",
-            "required": true,
-            "description": "Limits the number of items on a page",
-            "schema": {
-              "type": "integer"
-            }
-          },
-          {
-            "name": "complex",
-            "in": "cookie",
-            "description": "A more complex schema",
-            "schema": {
-              "type": "array",
-              "items": {
-                "type": "object",
-                "properties": {
-                  "name": {
-                    "type": "string"
-                  }
-                }
-              }
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Status code 200",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "id": {
-                      "type": "string",
-                      "description": "The super Id."
-                    },
-                    "name": {
-                      "type": "string"
-                    },
-                    "phone": {
-                      "type": "string",
-                      "format": "byte"
-                    }
-                  }
-                }
-              }
-            }
-          },
-          "304": {
-            "description": "Status code 304",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "object",
-                  "properties": {
-                    "error": {
-                      "type": "string"
-                    }
-                  }
-                }
-              }
-            }
-          },
-          "400": {
-            "description": "Status code 400",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "type": "object",
-                    "properties": {
-                      "name": {
-                        "type": "string"
-                      }
-                    }
-                  }
-                }
-              }
-            }
-          },
-          "500": {
-            "description": "Status code 500",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "string"
-                }
-              }
-            }
-          }
-        }
-      },
-      "delete": {
-        "tags": [
-          "Account Service"
-        ],
-        "description": "Sample HTTP Delete method with references to other types.",
-        "parameters": [
-          {
-            "name": "limit",
-            "in": "header",
-            "required": true,
-            "description": "My sample description.",
-            "schema": {
-              "$ref": "#/components/schemas/SampleClass"
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Status code 200",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/SampleClass"
-                }
-              }
-            }
-          },
-          "304": {
-            "description": "Status code 304",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/ChildClass"
-                }
-              }
-            }
-          },
-          "305": {
-            "description": "Status code 305",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Reference1"
-                }
-              }
-            }
-          },
-          "306": {
-            "description": "Status code 306",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Reference1_array"
-                }
-              }
-            }
-          },
-          "307": {
-            "description": "Status code 307",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Reference7_Reference7[untypedObject:Reference2]"
-                }
-              }
-            }
-          },
-          "500": {
-            "description": "Status code 500",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/SampleClass"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "Contact/": {
-      "description": "Contact related operations",
-      "get": {
-        "tags": [
-          "Contact"
-        ],
-        "description": "This is a sample HTTP Get method",
-        "responses": {
-          "200": {
-            "description": "Status code 200",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/SampleRestResourceWithInnerClass.InnerClass"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "Order/": {
-      "description": "Order related operations",
-      "get": {
-        "tags": [
-          "Order"
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "param1": {
-                    "type": "string"
-                  },
-                  "param2": {
-                    "$ref": "#/components/schemas/Reference1"
-                  }
-                }
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "Status code 200",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "string"
-                }
-              }
-            }
-          }
-        }
-      },
-      "patch": {
-        "tags": [
-          "Order"
-        ],
-        "requestBody": {
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object",
-                "properties": {
-                  "param1": {
-                    "type": "string"
-                  },
-                  "param2": {
-                    "$ref": "#/components/schemas/Reference1"
-                  }
-                }
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "Status code 200",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "string"
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  },
-  "tags": [
-    {
-      "name": "Account Service",
-      "description": "Account related operations"
-    },
-    {
-      "name": "Contact",
-      "description": "Contact related operations"
-    },
-    {
-      "name": "Order",
-      "description": "Order related operations"
-    }
-  ],
-  "components": {
-    "schemas": {
-      "SampleClass": {
-        "type": "object",
-        "properties": {
-          "MyProp": {
-            "type": "string",
-            "description": "This is a String property."
-          },
-          "AnotherProp": {
-            "type": "number",
-            "description": "This is a Decimal property."
-          },
-          "listOfStrings": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
-          },
-          "someVariable": {
-            "type": "string"
-          },
-          "somePrivateStuff": {
-            "type": "string"
-          }
-        }
-      },
-      "ChildClass": {
-        "type": "object",
-        "properties": {
-          "privateStringFromChild": {
-            "type": "string"
-          },
-          "aPrivateString": {
-            "type": "string"
-          }
-        }
-      },
-      "Reference1": {
-        "type": "object",
-        "properties": {
-          "reference2Member": {
-            "$ref": "#/components/schemas/Reference2",
-            "description": "This is a reference 2 member. Lorem."
-          },
-          "reference3Member": {
-            "$ref": "#/components/schemas/Reference3"
-          },
-          "reference4Collection": {
-            "type": "array",
-            "items": {
-              "$ref": "#/components/schemas/Reference4"
-            }
-          },
-          "reference5Member": {
-            "$ref": "#/components/schemas/Reference5"
-          }
-        }
-      },
-      "Reference2": {
-        "type": "object",
-        "properties": {
-          "stringMember": {
-            "type": "string"
-          },
-          "objectReference": {
-            "$ref": "#/components/schemas/Reference3_array",
-            "description": "This is an object reference."
-          }
-        }
-      },
-      "Reference3_array": {
-        "type": "array",
-        "items": {
-          "$ref": "#/components/schemas/Reference3"
-        }
-      },
-      "Reference3": {
-        "type": "object",
-        "properties": {
-          "someBoolean": {
-            "type": "boolean"
-          }
-        }
-      },
-      "Reference4": {
-        "type": "object",
-        "properties": {
-          "someString": {
-            "type": "string"
-          }
-        }
-      },
-      "Reference5": {
-        "type": "object",
-        "properties": {
-          "reference6Member": {
-            "$ref": "#/components/schemas/Reference6"
-          }
-        }
-      },
-      "Reference6": {
-        "type": "object",
-        "properties": {
-          "grandChildString": {
-            "type": "string",
-            "description": "This is the grandchild description."
-          }
-        }
-      },
-      "Reference1_array": {
-        "type": "array",
-        "items": {
-          "$ref": "#/components/schemas/Reference1"
-        }
-      },
-      "Reference7_Reference7[untypedObject:Reference2]": {
-        "type": "object",
-        "properties": {
-          "untypedObject": {
-            "$ref": "#/components/schemas/Reference2"
-          }
-        }
-      },
-      "SampleRestResourceWithInnerClass.InnerClass": {
-        "type": "object",
-        "properties": {
-          "stringMember": {
-            "type": "string"
-          }
-        }
-      }
-    }
-  }
+  "paths": {},
+  "tags": []
 }

package/examples/vitepress/README.md

@@ -0,0 +1,25 @@
+# Vitepress Example
+
+This project contains an example on how to generate documentation to be rendered with [Vitepress](https://vitepress.dev/).
+
+## Getting Started
+
+* Follow the Vitepress installation instructions [here](https://vitepress.dev/guide/getting-started#installation).
+* Keep track of where you initialized your VitePress config. If it is different than the `docs` directory, you will
+need to make sure that it matches the `targetDir` when configuring ApexDocs.
+
+## Configuration
+
+Take a look at the `apexdocs.config.ts` file to see how the configuration is set up.
+
+Pay special attention to the following:
+
+* `transformReference` -> This updates the reference links generated by ApexDocs to the preferred format for Vitepress.
+
+This is **not** required, but Vitepress says in their documentation that they prefer when the links do not contain the .md extension.
+
+* `transformReferenceGuide` -> This ensures that the `index` file always contains the correct frontmatter that Vitpress expects.
+
+* `transformDocs` -> We use this hook to create a `sidebar` file that Vitepress uses to generate the sidebar navigation.
+
+* `transformDocPage` -> This updates each individual page's frontmatter so that it has the correct title.

package/examples/vitepress/apexdocs.config.ts

@@ -28,6 +28,7 @@ function writeFileAsync(filePath: string, data: string): Promise<void> {
 export default defineMarkdownConfig({
   sourceDir: 'force-app',
   scope: ['global', 'public', 'protected', 'private', 'namespaceaccessible'],
+  sortAlphabetically: true,
   namespace: 'apexdocs',
   transformReference: (reference) => {
     return {
@@ -41,6 +42,7 @@ export default defineMarkdownConfig({
       frontmatter: frontMatter,
     };
   },
+  excludeTags: ['internal'],
   transformDocs: async (docs) => {
     // Update sidebar
     const sidebar = [