codetour：与录制和播放CodeBases的引导演练的vs代码扩展

CodeTour是一个Visual Studio代码扩展，它允许您录制和播放Codebases的引导演练。它和＃39; s喜欢虚拟布朗袋或内容表，可以使其更容易onboard（或重新封装！）到新的项目/功能区域，可视化错误报告，或了解代码审查的上下文/ PR改变。 A＆＃34;代码游览＆＃34;只是一系列交互步骤，每个步骤与特定目录或文件/行相关联，并且包括对各个代码的描述。这允许开发人员克隆一个repo，然后立即开始学习它，而无需指代Contributing.md文件和/或依赖他人的帮助。旅行可以被检查到repo中，以启用与其他贡献者共享，或导出到A＆＃34;旅行文件＆＃34;，允许任何人重播同一游览，而无需克隆任何代码来执行任何代码！

要开始，请安装CODETOUR扩展，然后遵循以下指南之一，具体取决于您是否要录制或播放巡回赛：

如果您＆＃39; d想录制代码库的代码巡演，您只需单击Codetour树视图中的+按钮（如果它“＆＃39;可见）和/或运行CodeTour：录制浏览命令。这将启动Tour Recorder，允许您开始打开文件，单击＆＃34;评论栏＆＃34;对于您要注释的行，然后添加相应的描述（包括Markdown！）。添加尽可能多的步骤，然后在完成后，只需单击“停止旅行”（红色方形按钮）。您还可以创建目录步骤，选择步骤或内容步骤，以便为巡回赛添加介绍或中间解释。

虽然您＆＃39; RE录制，CODETOUR树视图将显示当前录制的巡视，它＆＃39; S当前一组步骤。您可以识别正在录制哪个巡演，因为它将在左侧的麦克风图标。

如果您需要在录制时编辑或删除一步，请单击步骤＆＃39旁边的...菜单，然后选择相应的操作。或者，您可以从CodeTour树视图编辑/删除步骤。

如果您在A＆＃34中录制出巡视;多根工作区＆＃34;，您＆＃39; ll被要求选择您＆＃39; d的文件夹喜欢省去。这是必要的，因为Tours被写为工作区的文件，因此我们需要解除巡视应该持续的哪个文件夹。那就是说，当你录制一个巡演时，你可以添加跨越工作区中的任何文件夹的步骤，这允许您为特定文件夹创建旅游和/或在工作区内的多个文件夹中演示概念。

默认情况下，Codetour树使用以下显示名称格式显示每个巡回阶段：＃＆lt; stepnumber＆gt; - ＆lt; filepath＆gt ;.但是，如果您＆＃39; d喜欢提供更友好/可识别的名称，您可以使用以下方法之一：

编辑步骤＆＃39; s描述并将标记向上添加到它的顶部，使用您更喜欢的任何标题级别（例如＃，＃，##等）。例如，如果添加描述从###激活开始的步骤，则步骤和树视图将如下所示：

默认情况下，每个步骤都与您创建的代码行相关联（即您在评论栏上单击+的行）。但是，如果要作为步骤的一部分调用特定代码的特定跨度，请在添加步骤之前突出显示代码（单击“添加浏览到步骤”按钮），并且将捕获选择作为步骤的一部分。

如果您需要调整＆＃39;与步骤相关联的选择，只需编辑步骤，重置选择，然后保存它。此外，如果要从选择中创建步骤，只需突出跨度代码，右键单击编辑器并选择添加CodeTour步骤。

虽然您录制了巡演，但您添加的每个新步骤都将附加到巡回赛结束。但是，您可以通过执行以下操作之一来在顺序上向上和向下移动现有步骤：

右键单击Codetour树中的步骤，然后选择“上门”或“向下移动”菜单项

单击步骤中的...菜单UI，然后选择向上移动或向下移动

此外，如果要在巡视的中间添加新步骤，只需导航到要在后面插入新步骤的步骤，然后创建新步骤。

如果您不再需要在巡视中需要一个特定的步骤，可以通过以下操作之一删除它：

导航到重播/注释UI中的步骤，选择“注释说明”旁边的“菜单”，然后选择“删除步骤”

如果需要删除多个步骤，则Codetour树支持多项选择，因此您可以CMD +单击（麦斯卡斯）/ Ctrl +单击（Windows / Linux）多个步骤节点，然后右键单击它们并选择“删除步骤”。

如果要编辑现有之旅，只需右键单击Codetour树中的巡视，然后选择编辑浏览。或者，您可以通过单击当前步骤＆＃39; s注释栏中的铅笔图标来编辑游览您和＃39;重新查看铅笔图标。或运行CodeTour：编辑Tour命令。

随时，您可以通过选择更改标题，更改描述或更改Git Ref菜单项，右键单击Codetour树中的巡视并更改它＆＃39; s标题，描述或git ref。此外，您可以通过在CODETOUR树中右键单击它并选择删除巡回赛中删除游览。

如果您想创建一系列旅游，用户可以按顺序浏览，然后简单地为您的旅游标题＆＃39;■在旅游订单中所代表的号码（例如1：Foo，2 - Bar）。当您的旅行如此之为之类时，旅游播放器将自动为您的读者提供以下优势：

如果目前的旅行有随后的巡演，那么它将＆＃39;最后一步将显示下一个旅游链接而不是完成旅游链接。这允许用户轻松跳转到下一个游览。

如果目前的旅行有前面的旅游，那么它将＆＃39;第一步将显示前一个旅游链接。这允许用户返回巡回赛，他们可能只是从中导航。

如果你不想像这样编号你的旅游，但你＆＃39; d仍然链接到另一个游览另一个游览，你可以打开它＆＃39; s * .tour文件并将nexttour属性设置为标题旅游＆＃39; d喜欢它链接到。

CodeBase可以包含一个或多个巡回赛，但它可能有一个主要的游览，这是新开发人员开始的。这样，当他们第一次打开Codebase时，可以立即通过这次巡回演出，而不是所有旅游的列表。

为了将特定的游览标记为主要巡视，只需在Codetour树中右键单击它，然后选择“制作主”。当您将浏览为主时，将更新任何标记为主要的其他旅行，以删除该注释。此外，如果您想手动将巡回巡视作为主巡回赛，您可以右键单击它，然后选择“取消主机”。

如果你更喜欢编号你的旅行（例如1 - 状态栏），那么一个巡回赛的标题从＃1 - 或1开始 - 将自动被认为是主要的旅游，而且你不需要进一步做任何事情。

当您描述一步，您＆＃39;重新能够使用全面的标记功能，以便编写丰富/引人注目的内容（例如，图像，链接，标题，代码围栏）。但是，Codetour还提供了一些额外的句法功能，允许您为您的旅行中包含其他交互性：

如果要在当前旅行中添加另一步，可以使用Markdown＆＃39; s＆＃34;链接参考文献＆＃34;语法，指定用于导航到的基于步骤的数量，由＃字符（例如[＃2]或[＃23]）前缀。此引用将自动呈现为超链接，即在单击时，将导航到该步骤。链接的文本将默认为＃＆lt; stepnumber＆gt;，但是您可以通过将标题附加到链接引用（例如`[标题] [＃2]）来自定义。

此语法是手动使用导航到Tour Step命令链接的简化版本。

如果您想引用一个完全单独的旅行，那么您可以创建一个链接引用，指定巡回赛的标题（例如[树视图]）。这将被呈现为超链接，即在单击时，将在步骤＃1开始将最终用户导航到该巡视。如果您喜欢将用户导航到巡回赛中的特定步骤，您可以在旅游标题之后追加步骤编号，由＃（例如[树视图＃3]）分开。链接的文本将呈现为＆lt; touttitle＆gt;，但您可以通过将标题附加到链接引用（例如[标题] [树视图]）来定制。

要使shell命令嵌入步骤（例如，执行构建，运行测试，启动应用程序），CodeTOR支持特殊＆gt;＆gt; Synax，后跟你想要运行的shell命令（例如，＆gt; npm运行编译）。这将被转换为超链接，即在单击时，将启动新的集成终端（称为CODETOUR），并将运行指定的命令。

为了向旅游添加更多的交互，您可以包含＆＃34;命令链接＆＃34;到阶梯和＃39; s描述。命令链接只是knallown链接，它使用命令：scheme（而不是http：/ https :)，并指定VS Code命令的名称以及包括所需的命令参数的可选查询字符串。使用此语法，您可以调用VS代码中的任何命令，包括内置命令（例如vscode.open），以及由扩展（例如codetour.starttour）贡献的命令。例如，下面显示了如何包含带有争论的命令。

＆lt; - 致电不需要参数的命令 - ＆gt; [打开url]（命令：codetour.starttour）＆lt;！ - 调用需要参数的命令 - ＆gt; [打开URL] （命令：vscode.open？[＆＃34; https：//aka.ms/codetour"]）

为了使其更简单地调用常见命令，CodeTour将在键入命令时立即提示您使用众所周知的命令列表：在步骤注释中。如果选择一个选项，它将生成相应的标记代码，并包含任何必要的参数的占位符。以下列表介绍了当前支持的众所周知命令的集合：

导航到巡视步骤 - 允许您指定一个巡回演出，即在单击时，将在当前旅行中导航到该步骤。这对于将最终用户提供跳过的选项非常有用，或者快速参考前面的步骤。

打开URL - 允许您指定URL，即在单击时，将启动最终用户的默认浏览器，并导航到它。

运行构建任务 - 允许您运行构建任务，如当前工作区＆＃39; s task.json文件所定义。

运行任务 - 允许您指定工作区任务名称，即单击时，将使用当前工作区＆＃39; s task.json文件定义的指定任务。

运行测试任务 - 允许您运行Butestild任务，如当前工作区和＃39; s task.json文件所定义。

运行终端命令... - 允许您指定shell命令（例如，npm运行包），即单击时，将在集成终端中运行指定的命令。

开始巡演... - 允许您在工作区中指定标题或其他巡回演出，即在单击时，将自动开始该巡视。

如果将标记代码块添加到步骤＆＃39; s身体内容，那么Codetour播放器将渲染下面的插入代码链接，这允许查看者自动将代码片段插入当前文件，然后步骤与之相关。这可以简单地使用CodeTour来创建交互式教程或样本。

注意：将代码片段插入文档后将格式化，因此，您不需要担心添加空白/等。到赛段本身。

当您录制旅游时，＆＃39;被问到哪个git＆＃34; ref＆＃34;将其与之相关联。这允许您定义您希望巡回赛的令人乐报，因为对相应的代码库进行了更改。

没有 - 与任何REF相关联的Tour ISN＆＃39;因此，巡回赛中的文件/行号可能会随着时间的推移而变得不同步。此选项的好处是它使得要作为巡回赛的一部分被编辑的代码，因为巡回赛将通过他们已被检查的分支/提交的任何分支/提交来步行。

目前的分支 - 巡视仅限于当前分支机构。这可以具有相同的弹性挑战，但是，它允许您为您的旅行维护一个特殊的分支，这些分支可以分别版本化。如果最终用户具有签出的关联分支，则巡视将使它们能够为其拍摄的文件进行编辑。否则，巡演将以只读文件重播。

当前提交 - 巡回赛仅限于当前提交，因此，永远不会失去同步。如果最终用户＆＃39;在指定的提交中的头部点，那么Tour将使它们能够为文件进行编辑。否则，巡演将以只读文件重播。

标签 - 巡视仅限于所选标记，因此，永远不会失去同步。将显示回购＆＃39; s的标签列表，这允许您轻松选择一个。

随时，您可以通过在Codetour树中右键单击它并选择更改Git Ref，编辑Tour＆＃39; s ref。这让你＆＃39;你＆＃34; rebase＆＃34;在更改/更新代码和/或代码库时，浏览标签/提交。

代码之旅主要是为了描述代码，但是，当您录制旅游时，它可能有助于为旅游提供一些介绍解释。为此，您可以创建一个＆＃34;内容步骤＆＃34;，这是一个包括标题和标记内容的旅游步骤，但与目录或文件关联的ISN＆＃39;要创建内容步骤，请执行以下操作之一：

单击Codetour树中的“添加巡回步骤...”节点，该节点位于代表您当前录制的节点中。注意：此选项仅在巡视与＃39; T有任何步骤时可用。

右键单击Codetour树中的巡视节点，然后选择“添加旅游步骤”。注意：此选项仅在录制游览时可用。

创建内容步骤时，请＆＃39;请问LL的步骤（例如介绍），然后是A＆＃34;虚拟＆＃34;将使用您可以编辑的关联注释创建文件。这允许观看者以一致的方式在步骤之间导航，而不管该步骤是否与文件相关联。

如果要将目录称为巡回赛的一部分，然后在录制时，可以右键单击资源管理器树中的目录，然后选择“添加CodeTour步骤”。这将创建一个新的步骤，允许您为所选目录添加描述。播放游览时，目录将集中在资源管理器树中，查看者将在A＆＃34中的描述中呈现;虚拟＆＃34; Codetour文档。

在幕后，巡视将被写入当前工作区的.tours目录的json文件。这个文件很简单，如果你喜欢，可以手工编辑; d喜欢。此外，您可以按照巡回赛模式手动创建巡视文件。然后，您可以将这些文件存储到.tours（或.vscode / tours）目录中，或者您也可以在以下任何众所周知的位置创建巡视：.tour，main.tour

在.tours（或.vsode / tours）目录中，您可以将您的巡回档文件组织成任意深度的子目录，并且Codetour播放器将正确发现它们。

标题（必填） - 旅行的显示名称，将在Codetour树视图中显示，快速选择等。 描述 - 巡视的可选描述，将显示为Codetour树视图中的巡演的工具提示 参考 - 可选的＆＃34; git ref＆＃34; （分支/标签/提交）这次旅行适用于。 有关详细信息，请参阅版本传播之旅。 Isprimary - 表示这次巡视是工作空间内的主要巡视，即最终用户应该被引导。 步骤（必填） - 一系列旅游步骤描述（必填） - 解释当前文件/行号的文本，并且可以包括纯文本和kardown语法 文件 - 此步骤与之关联的文件路径（相对于工作空间根） 目录 - 目录（相对于工作空间根）的路径此步骤与之关联。 注意：此属性优先于文件属性，因此将＆＃34; WIN＆＃34; 如果两者都存在。

Uri - 这一步与之关联的绝对URI。请注意，URI和文件是互斥的，所以每步只设置一个

模式 - 与将步骤相关联的正则表达式。这仅考虑在线属性ISN＆＃39; t设置，并允许您将带有行内容的步骤与序号相反。

标题 - 一个可选标题，将显示为Codetour树视图中的步骤名称。

命令 - vs ode命令字符串数组，指示命令（例如codetour.endtour）的名称和传递给它的任何可选参数，指定为查询字符串阵列（例如，codeTour.endtour？[2]）。

查看 - 在导航此步骤时将自动聚焦的VS代码视图的ID。

默认情况下，当您录制巡视时，它将写入当前打开的工作区。这使得巡回赛可以轻松登记，并与团队的其余部分分享。但是，您可以在您想要为自己录制旅行的时候，或者巡回赛，帮助向某人解释一次，并且在这些情况下，您可能不想检查进入回购的旅行。

为了支持此方案，当您开始录制新巡视时，您可以单击“将右侧的”保存之旅“作为...按钮在对话框的右上角，要求参观的标题。这WLL允许您选择将写入新巡视的文件，以便持续到工作空间中的＆＃39;此外，您可以像往常一样录制游览，然后在完成后，您可以在Codetour树中右键单击它，然后选择导出游览....这将允许您将游览节省到一个新位置，然后您可以从repo中删除巡视文件。导出巡回赛时，旅游文件本身将嵌入巡视所需的所有文件的内容，这确保有人可以播放，而不管是否具有本地可用的各个代码。这使得能够强大的合作形式。

如果您安装Gistpad扩展，那么您＆＃39; ll查看要添加到Codetour树的GIST ...选项的其他出口巡回赛。这使您可以将巡视文件导出到新/现有的GIST，这允许您轻松创建自己的私人旅行和/或创建可以与团队中其他人共享的旅行。

一旦巡回巡回赛量作为要点导出，您可以在Gistpad树中右键单击Main.tour文件，然后选择“复制GitHub URL”。如果您将其发送给某人，并且他们运行CODETOUR：Open Tour URL ...命令，然后他们能够追随完全相同的旅行，无论它们是否有本地可用的代码。

为了开始巡演，只需打开一个或多次旅行的Codebase。如果这是第一次＆＃39; vere曾经打开过这个codebase，你＆＃39; ll举行吐司通知，询问你是否喜欢参观它。

在资源管理器活动选项卡中选择CodeTour视图中的Tour（或特定步骤）

如果当前工作区仅具有单个代码巡回赛，则此命令将自动启动该巡视。否则，您＆＃39; LL展示了一个游览列表来选择。

除了拍摄当前打开的工作区的一部分，您还可以打开一个别人发送给您和/或您创建的旅游文件。只需运行codeto

......