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

2021-03-20 09:14:42

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

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

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

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

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

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

默认情况下,Codetour树使用以下显示名称格式显示每个巡回阶段:#< stepnumber> - < filepath&gt ;.但是,如果您' d喜欢提供更友好/可识别的名称,您可以使用以下方法之一:

编辑步骤' s描述并将标记向上添加到它的顶部,使用您更喜欢的任何标题级别(例如#,#,##等)。例如,如果添加描述从###激活开始的步骤,则步骤和树视图将如下所示:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

< - 致电不需要参数的命令 - > [打开url](命令:codetour.starttour)<! - 调用需要参数的命令 - > [打开URL] (命令:vscode.open?[" https://aka.ms/codetour"])

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

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

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

运行构建任务 - 允许您运行构建任务,如当前工作区' s task.json文件所定义。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

......