@cparra/apexdocs 3.0.0-beta.1 → 3.0.0

package/examples/markdown-jsconfig/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/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,14 +28,21 @@ function writeFileAsync(filePath: string, data: string): Promise<void> {
 export default defineMarkdownConfig({
   sourceDir: 'force-app',
   scope: ['global', 'public', 'protected', 'private', 'namespaceaccessible'],
+  sortAlphabetically: true,
   namespace: 'apexdocs',
-  transformReferenceGuide: async (referenceGuide) => {
+  transformReference: (reference) => {
+    return {
+      // remove the trailing .md
+      referencePath: reference.referencePath.replace(/\.md$/, ''),
+    };
+  },
+  transformReferenceGuide: async () => {
     const frontMatter = await loadFileAsync('./docs/index-frontmatter.md');
     return {
-      ...referenceGuide,
       frontmatter: frontMatter,
     };
   },
+  excludeTags: ['internal'],
   transformDocs: async (docs) => {
     // Update sidebar
     const sidebar = [

package/examples/vitepress/docs/index.md

@@ -19,38 +19,38 @@ hero:
 
 ## Miscellaneous
 
-### [BaseClass](miscellaneous/BaseClass.md)
+### [BaseClass](miscellaneous/BaseClass)
 
-### [MultiInheritanceClass](miscellaneous/MultiInheritanceClass.md)
+### [MultiInheritanceClass](miscellaneous/MultiInheritanceClass)
 
-### [ParentInterface](miscellaneous/ParentInterface.md)
+### [ParentInterface](miscellaneous/ParentInterface)
 
-### [ReferencedEnum](miscellaneous/ReferencedEnum.md)
+### [ReferencedEnum](miscellaneous/ReferencedEnum)
 
-### [SampleException](miscellaneous/SampleException.md)
+### [SampleException](miscellaneous/SampleException)
 
 This is a sample exception.
 
-### [SampleInterface](miscellaneous/SampleInterface.md)
+### [SampleInterface](miscellaneous/SampleInterface)
 
 This is a sample interface
 
-### [Url](miscellaneous/Url.md)
+### [Url](miscellaneous/Url)
 
 Represents a uniform resource locator (URL) and provides access to parts of the URL. 
 Enables access to the base URL used to access your Salesforce org.
 
 ## Sample Enums
 
-### [SampleEnum](sample-enums/SampleEnum.md)
+### [SampleEnum](sample-enums/SampleEnum)
 
-This is a sample enum. This references [ReferencedEnum](miscellaneous/ReferencedEnum.md) . 
+This is a sample enum. This references [ReferencedEnum](miscellaneous/ReferencedEnum) . 
  
 This description has several lines
 
 ## SampleGroup
 
-### [SampleClass](samplegroup/SampleClass.md)
+### [SampleClass](samplegroup/SampleClass)
 
 aliquip ex sunt officia ullamco anim deserunt magna aliquip nisi eiusmod in sit officia veniam ex 
-deserunt ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
+**deserunt** ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.

package/examples/vitepress/docs/miscellaneous/BaseClass.md

@@ -17,4 +17,4 @@ public sampleEnumFromBase
 ```
 
 #### Type
-[SampleEnum](../sample-enums/SampleEnum.md)
+[SampleEnum](../sample-enums/SampleEnum)