顶级Docs

Apex Docs是销售力类Apex类的不透视文档生成器. 它可以以Markdown格式输出文档,允许您使用您选择的静态站点生成器 创建一个适合您需要的文档网站,在任何静态网络托管服务中托管.

目录

• 实例
• * 特性
• * 安装
• QQ 快速启动
  • 国 际
    • 标记
    • 打开Api
    • 更改日志
• 可用的命令
  • 标记
  • 打开Api
  • 更改日志
• 定义配置文件
• 翻译
• QQ 导入到您的项目
• 文档指南
• 生成 OpenApi REST 定义

实例

ApexDocs生成Markdown文件,这些文件可以被集成到任何静态站点生成引擎中, (例如:Jekyll,Vitepress,Hugo,Docoraurus等) 来创建一个适合您需要的文档站点.

这使得你能够灵活地利用你喜欢的 SSG 引擎创建美丽的网站 通常提供广泛的主题,暗模式支持,以及框外的其他特性.

这些是使用Vitepress生成的文件站点的例子. 去那边 examples/vitepress 要查看代码的文件夹.

额外的灵活性还使您能够将输出文档与您现有的文档站点整合, 允许您匹配您现有网站的外观和感觉.

OpenApi REST定义可以使用ReDoc,Swagger UI等工具或其他任何OpenApi查看器进行可视化.

此重播包含几个其他实例 examples 目录,显示如何整合 拥有不同的工具.

• 实例

# 在野外 # # In the wird #

以下是使用 Apex Docs 的一些现场项目:

• 轨迹顶端食道
• 销售力量顶端商业
• 表达式( API)
• Nimble AMS 文档

* 特性

• 生成 Salesforce 代码( Apex, 触发器, 自定义对象, LWCs) 的文档作为 Markdown 文件
• 生成基于 OpenApi 的 REST 规格 @RestResource 类
• 基于您的 Salesforce Apex 类两个版本的差异生成更改日志
• 支持在一个类别内分组相关代码的块
• 支持忽略文件和成员不被记录
• 命名空间支持
• 配置文件支持
• 不同语言和自定义术语的翻译支助
• 单行顶端文件块
• 自定义标签支持
• 还有更多!

* 安装

npm i -g @cparra/apexdocs

QQ 快速启动

国 际

标记

运行以下命令为您的 Global SalesForce Apex 类和自定义对象生成标记下的文件 :

apexdocs markdown -s force-app

# Use sfdx-project.json as the source of directories
apexdocs markdown --useSfdxProjectJson

# Specify multiple source directories
apexdocs markdown --sourceDir force-app force-lwc force-utils

打开Api

运行以下命令以生成您的 Alesforce Apex 类的 OpenApi REST 规格 附加说明 @RestResource数字 :

apexdocs openapi -s force-app

更改日志

运行以下命令以生成您 Salesforce Apex 类的更改日志 :

apexdocs changelog --previousVersionDir force-app-previous --currentVersionDir force-app

可用的命令

标记

markdown

旗帜

说明: 这个 * 在所需栏内注明 一个 必须指定源目录选项:

• --sourceDir (单一目录或目录数组)
• --useSfdxProjectJson (从sfdx-project.json读取)

这些选项是相互排斥的 — 您不能同时使用多个选项 .

联系战略

连接策略决定了 Apex Docs 将如何链接到文档中的其他类 。 譬如说, 如果我有课 A 连接到类 B (例如通过 {@link B} 标记,该 @see 标签, 以它为参数,从方法返回等,连接策略将决定链接到类的方式 B 实值 创建.

这些是可能值 linkingStrategy 旗帜 :

• relative

创建类文件的相对链接 . 因此,如果两个类都在同一目录中,链接将创建为 [B](B.md)。 。 。 . 如果类在不同的目录中,链接将创建为 [B](../path/to/B.md)

• no-link

完全不创建链接 。 类名将以纯文本显示 .

• none

不应用任何一种逻辑。 相反,链接将由文件路径决定 从文档站点的根起, 或通过您返回的任意路径 transformReference 钩子 为文件.

样本使用

apexdocs markdown -s force-app -t docs -p global public namespaceaccessible -n MyNamespace

打开Api

openapi

旗帜

样本使用

apexdocs openapi -s force-app -t docs -n MyNamespace --title "My Custom OpenApi Title"

更改日志

changelog

旗帜

样本使用

apexdocs changelog -p force-app-previous -t force-app

定义配置文件

也可以使用配置文件来定义生成文档时将使用的参数.

配置文件是将生成的文档与您的静态站点生成器集成的主要方式 选项和构建进程,以及配置任何自定义行为和生成文件的输出.

概览

顶级文档使用 宇宙图 装入配置文件,这意味着 支持下列格式(加上由宇宙图支持的其他任何格式):

• A 类 package.json 财产,例如:. { "apexdocs": { "sourceDir": "src", "targetDir": "docs" } }
• A 类 .apexdocsrc 文件, 以 YAML 或 JSON 编写, 可选的扩展名 : .yaml/.yml/.json/.js
• 一个 apexdocs.config.js (或 .mjs)文件导出对象
• A 类 apexdocs.config.ts 导出对象的文件

配置文件应放置在您的工程的根目录中 .

请注意,当使用配置文件时,您仍可通过通过 CLI(英语:CLI).

配置文件

在定义配置文件时,建议使用ES模块语法. 配置文件应当 default 以您想要使用的参数导出对象 :

export default {
  sourceDir: 'force-app',
  targetDir: 'docs',
  scope: ['global', 'public'],
  ...
}

配置文件中的每个属性都是可选的,如果不提供,则通过 将使用 CLI,或者使用默认值.

配置智能

使用 defineMarkdownConfig (或 defineOpenApiConfig openApi 文档) 帮助者将提供 Typescript 功率 Intellisense 用于配置文件选项。 这应该与Javascript和Typescript文件同时工作.

import { defineMarkdownConfig } from "@cparra/apexdocs";

export default defineMarkdownConfig({
  sourceDir: 'force-app',
  targetDir: 'docs',
  scope: ['global', 'public'],
  translations: {
    sections: {
      methods: 'Methods',
      properties: 'Properties',
    },
  },
  ...
});

生成不同类型的文档

您可能想要使用单个命令生成不同类型的文档 。 例如,如果你正在释放 您可能想要生成更新的文档 Markdown 文件 同时生成一个更改日志,列出所有新内容.

您可以通过提供一个配置文件来导出一个按键的配置对象 您想要生成的文档.

import { defineMarkdownConfig, defineChangelogConfig } from '@cparra/apexdocs';

export default {
  markdown: defineMarkdownConfig({
    sourceDir: 'force-app',
    targetDir: 'docs',
    scope: ['global', 'public'],
    ...
  }),
  changelog: defineChangelogConfig({
    previousVersionDir: 'force-app-previous',
    currentVersionDir: 'force-app',
    targetDir: 'docs',
    scope: ['global', 'public'],
  })
};

那你只需要运行顶层 apexdocs 命令,并生成两类文档.

注意, 如果您想要生成一种类型的文档, 您仍然可以运行单个命令 提供子命令,例如 apexdocs markdown 或者说 apexdocs changelog。 。 。 .

LWC 文件限制

LWC 文档仅在提供 --experimentalLwcSupport 标记或设置 experimentalLwcSupport 属性改为 true 在配置文件中.

ApexDocs 支持为闪电网络组件生成文档, 但请 了解以下限制:

• 仅标为 isExposed=true 在组件的 meta.xml 文件中,将记录.
• 目前JSDoc的任何评论都被忽视,文档完全基于组件的元数据.
• Changelog生成不包括对LWCs的修改.

将文件从文档中排除

本表所列模式 .forceignore 文件将被排除在文档之外.

此外,您还可以通过向 Glob 模式列表来排除一个或多个文件被记录 页:1 exclude 属性在配置文件中.

import { defineMarkdownConfig } from "@cparra/apexdocs";

export default defineMarkdownConfig({
  sourceDir: 'force-app',
  targetDir: 'docs',
  scope: ['global', 'public'],
  exclude: ['**/MyClass.cls', '**/MyOtherClass.cls'],
  ...
});

你也可以利用 exclude 属性可以间接修改诸如您所做的自定义元数据记录之类的东西 不需要包含在自定义元数据类型对象文档中.

//...
exclude: ['**/*.md-meta.xml']
//...

不包括文档中的标记

注:只为Markdown文档工作.

您可以使用 excludeTags 配置文件中的属性, 允许您通过要从文档中排除的标签列表.

import { defineMarkdownConfig } from "@cparra/apexdocs";

export default defineMarkdownConfig({
  sourceDir: 'force-app',
  targetDir: 'docs',
  scope: ['global', 'public'],
  excludeTags: ['internal', 'ignore'],
  ...
});

配置钩

定义 a .js 或者说 .ts 配置文件, 您的对象导出也可以使用 在文件生成过程的不同阶段将称为不同的钩子.

所有钩子都可以是同声函数,允许您进行同步操作,比如调用外部API.

Markdown和Changlog操作都有钩子(但OpenApi没有).

标记下钩

转换参考指南

允许更改参考指南的前题和内容, 或者如果创建了参考指南页面 应该跳过.

类型

type TransformReferenceGuide = (referenceGuide: ReferenceGuidePageData) => Partial<ReferenceGuidePageData> | Skip | Promise<Partial<ReferenceGuidePageData> | Skip>;

示例: 更新前题

export default {
  transformReferenceGuide: (referenceGuide) => {
    return {
      // The frontmatter can either be an object, of the frontmatter string itself
      frontmatter: { example: 'example' }
    };
  }
};

示例: 跳过参考指南

// The skip function is imported from the package
import { defineMarkdownConfig, skip } from "@cparra/apexdocs";

export default defineMarkdownConfig({
  transformReferenceGuide: (referenceGuide) => {
    return skip();
  }
});

转换 Docs

这个钩子的主要目的是让你可以跳过特定页面的生成, 通过返回过滤过的数组 DocPageData 对象.

如果您想要修改文件的内容或前题,请使用 transformDocPage 钩取之.

类型

type TransformDocs = (docs: DocPageData[]) => DocPageData[] | Promise<DocPageData[]>

示例

export default {
  transformDocs: (docs) => {
    return docs.filter(doc => doc.name !== 'MyClass');
  }
};

转换文件页

允许更改文件页面的前题和内容 .

类型

type TransformDocPage = (
  doc: DocPageData,
) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>

示例

export default {
  transformDocPage: (doc) => {
    return {
      frontmatter: { example: 'example' }
    };
  }
};

转换参考

允许更改文件写到哪里以及文件如何相互连接 .

类型

type TransformReference = (
  reference: DocPageReference,
) => Partial<ConfigurableDocPageReference> | Promise<ConfigurableDocPageReference>;

示例

export default {
  // Notice how we are setting the linking strategy to none, so that nothing is done
  // to the links by the tool when it tries to link to other classes
  linkingStrategy: 'none',
  transformReference: (reference) => {
    return {
      // Link to the class in Github instead to its doc page.
      referencePath: `https://github.com/MyOrg/MyRepo/blob/main/src/classes/${reference.name}.cls`
    };
  }
};

宏

允许定义可用于文档的自定义宏.

Macros是可重复使用的可注入文档的文本片段, 允许您定义可跨多个文件使用的普通文本.

通常使用的案例是注入版权或许可证信息,而无 必须在多个类别中复制同一文本,污染您 源代码.

在文档中可以使用 {{macro_name}} 语法. 在配置文件中,您可以将宏行为定义为密钥值对,其中密钥为名称 宏,而值是返回文本以代替宏的函数.

类型

type MacroSourceMetadata = {
  type: 'apex' | 'customobject' | 'customfield' | 'custommetadata' | 'trigger' | 'lwc';
  name: string;
  filePath: string;
};

type MacroFunction = (metadata: MacroSourceMetadata) => string;

注意到 metadata 对象包含关于宏所要覆盖的文件来源的信息 注射过 这样可以选择 返回基于文件来源的不同文本.

示例:发出版权通知

//...
macros: {
  copyright: () => {
    return `@copyright Copyright (c) ${new Date().getFullYear()} My Name`;
  }
}
//...

然后在源代码中,你可以像这样使用宏:

/**
 * {{copyright}}
 * @description This is a class
 */
public class MyClass {
    //...
}

模板

允许为生成Markdown文档提供自定义模板,并赋予您对输出格式的控制. 您可以定义每种类型元数据的模板 由 markdown 命令(类、界面、enum、触发、LWC、自定义对象和参考指南) .

关于创建自定义模板的详细信息,包括实例、可用的助手和配置 选项, 请参考 维基文档。还可以 在 examples/markdown-custom-templates 目录.

变换日志钩

变换换LogPage

允许更改更改日志页面的前题和内容 .

类型

type TransformChangeLogPage = (
  changelog: ChangeLogPageData,
) => Partial<ChangeLogPageData> | Promise<Partial<ChangeLogPageData>>

// Supporting types

type ChangeLogPageData = {
  source: SourceChangelog;
  frontmatter: string | Record<string, any>;
  content: string;
  outputDocPath: string;
};

type SourceChangelog = {
  fileChanges: FileChange[];
};

type FileChange = {
  name: string;
  fileType: 'apex' | 'customobject';
  changeType: 'added' | 'removed' | 'changed';
  changes?: {
    addedMethods?: string[];
    removedMethods?: string[];
    addedFields?: string[];
    removedFields?: string[];
    addedProperties?: string[];
    removedProperties?: string[];
    addedCustomFields?: string[];
    removedCustomFields?: string[];
    addedSubtypes?: string[];
    removedSubtypes?: string[];
    addedEnumValues?: string[];
    removedEnumValues?: string[];
  };
};

示例

export default {
  transformChangeLogPage: (changelog) => {
    return {
      frontmatter: { example: 'example' }
    };
  }
};

翻译

ApexDocs支持翻译,以自定义生成文档中使用的语言和名词. 此功能允许您:

• 将文件翻译成不同语文 (西班牙语,法语等)
• 使用自定义商务术语 (如"商业操作"而不是"方法")
• 部分推翻特定术语 剩下的用英语

如何运作

翻译系统使用:

• 默认英文翻译 纳入系统
• 用户提供的覆盖 可以是部分或完整的

配置

添加一个 translations 属性到您的 ApexDocs 配置( JS 或 TS 文件)并传递 适当的翻译对象,取决于您使用的生成器:

import { defineMarkdownConfig } from '@cparra/apexdocs';

export default defineMarkdownConfig({
  sourceDir: 'src',
  targetDir: 'docs',
  scope: ['public', 'global'],
  translations: {
    sections: {
      methods: 'Métodos',
      properties: 'Propiedades',
      fields: 'Campos',
    },
  },
});

类型脚本支持

对于 TypeScript 工程, 导入翻译类型, 以便更好的自动完成和类型安全 :

import { defineMarkdownConfig } from '@cparra/apexdocs';
import type { UserTranslations } from '@cparra/apexdocs';

const markdownTranslations: UserTranslations['markdown'] = {
  sections: {
    methods: 'Functions',
  },
  // ...other translation keys as needed
};

export default defineMarkdownConfig({
  sourceDir: 'src',
  targetDir: 'docs',
  scope: ['public', 'global'],
  translations: markdownTranslations,
});

页:1

• 只有 减值 财务报告和审定财务报表 更改日志 发电机支持翻译
• 所有翻译都是可选的 - 任何未指定的都使用英语默认

完整的例子见 翻译示例 在此仓库中.

QQ 导入到您的项目

反思

如果你对顶级解析能力感兴趣,你可以使用 独立 顶级反射库 用于生成文档文件.

处理

如果您希望直接从 Javascript/ Typescript 使用 Apex Docs 的处理能力 您可以不使用 CLI , 而导入 process 函数.

import { process } from '@cparra/apexdocs';

process({
  sourceDir: 'force-app',
  targetDir: 'docs',
  scope: ['global', 'public'],
  ...
});

QQ 字迹

如果使用Typescript,顶级Docs会提供所有必要类型的定义.

文档指南

见 维基百科 一个深入的指南 如何记录您的顶级密码 来获取顶级Docs.

生成 OpenApi REST 定义

Apex Docs 还可以为您的销售力量类生成 OpenApi REST 定义 @RestResource。 。 。 .

见 维基百科 更多信息.