使用Try.NET创建可交互.NET文档
原文地址:Create Interactive .NET Documentation with Try .NET
原文作者:Maria
译文地址:https://www.cnblogs.com/lwqlun/p/10894497.html
译者:Lamond Lu
背景
当我们编写开发人员使用的文档时,我们需要捕捉他们的兴趣,并引导他们尽快走上成功的道路。开发人员生态系统一直在为社区提供可交互的文档,用户可以一个地方阅读文档,运行代码并进行编辑。
在过去的2年里,.NET语言团队一直在不断发展Try .NET, 以支持在线和离线的交互式文档。
什么是Try .NET
Try .NET是一个基于.NET Core的交互式文档生成器。
Try .NET 在线版
2017年9月,Try .NET第一次在docs.microsoft.com中使用,开发人员可以使用Azure Container实例运行代码。然而在过去的5个月内,我们改用Blazor和Web Assembly作为代码执行客户端。
你可以自己访问如下链接, 并打开开发者工具。在控制台标签页中,你可以看到如下信息WASM:Initialized
, 切换到网络标签页,你将看到所有在客户端执行的DLL。
控制台标签页: *WASM Initialized*
网络标签页: DLLs
Try .NET离线版
对我们而言,离线版和在线版一样的重要。针对离线体验,对我们而言,创建一种可以融入内容作者工作流程的体验是非常重要的。
在我们的调查结果中,我们注意到内容开发人员(content developers)在创建开发人员文档时,经常使用2种说明方式
- 一个用户可以下载并运行的实例。
- 一些Markdown文件,其中包含一系列说明,以及从代码库复制黏贴的的代码片段。
Try .NET提供了全局工具dotnet try, 以方便.NET开发人员创建可交互的Markdown文件。
为了使你的Markdown文件具有交互性,你需要安装.NET Core的SDK, 全局工具dotnet try, 以及Visual Studio / VS Code。
我们该怎么做?
扩展Markdown
在Markown文件中,你会使用隔离代码块来突出显示代码段。在代码块的前后,你会使用```来包裹它们。你可以添加可选的语言标识符,启用针对代码段的语法突出显示。
例:C#的代码块
``` cs
var name ="Rain";
Console.WriteLine($"Hello {name.ToUpper()}!");
```
使用Try .NET, 我们可以扩展隔离代码块,给它添加一些额外的参数。
``` cs --region methods --source-file .\myapp\Program.cs --project .\myapp\myapp.csproj
var name ="Rain";
Console.WriteLine($"Hello {name.ToUpper()}!");
```
这里我们使用了3个参数
--region
参数 - 指定一个C#的分块(region)--source-file
参数 - 指定程序文件的目录--project
参数 - 指定项目文件和引用的系统程序集
因此,以上示例中,我们做的事情是,当你运行Try .NET的解析你的Markdown文件的时候,程序会去尝试引用Program.cs
文件中名为methods
的分块代码。
使用#regions
在Markdown中,我们扩展了代码块,提供了--region
参数,用它可以指定C#代码中的分块(region)。
所以,你的Program.cs
文件看起来可能是这样的。
using System;
namespace HelloWorld
{
class Program
{
static void Main(string[] args)
{
#region methods
var name ="Rain"
Console.WriteLine($"Hello{name.ToUpper()}!");
#endregion
}
}
}
dotnet try verify
dotnet try verify
是一个文档编译器。使用这个命令,你可以确保每个代码块都能正常工作,并且和项目代码保持一致。
dotnet try verify
命令的目的是为了验证你的文档按照你期望的样子工作。
通过使用dotnet try verify
命令,你可以检测Markdown文件并编译错误。例如,如果我将之前代码中移除一个分号,并且将methods
代码分块改名为method
。现在如果运行编译器,会出现以下错误。
尝试使用全局工具dotnet try
dotnet try
现在已经可以使用了。这是一个dotnet try
全局工具的早期预览版,你可以从我们的仓储克隆代码。
入门
- 克隆代码仓储
- 签出Samples分支
- 安装.NET Core 2.1或3.0预览版
- 打开控制台窗口
- 安装Try .NET全局工具
dotnet tool install --global dotnet-try --version 1.0.19264.11
更新dotnet try
也很简单,只需要运行如下命令
dotnet tool update -g dotnet-try
定位到当前仓储的Samples
目录,输入dotnet try
浏览器会自动打开
Try .NET现在开源了
现在Try.NET已经在Github上开源了!由于我们仍处于早期开发阶段,所以目前我们无法接受任何功能的Pull Request, 但我们打算在未来这么做。请随时在我们的Issue列表中提交Bug报告。 如果你有任何功能建议,请在我们的Issue列表中使用社区建议的标签提交。
使用Try.NET创建可交互.NET文档的更多相关文章
- (转)创建和查看Javadoc文档
原地址:http://jinnaxu-tju-edu-cn.iteye.com/blog/667177 Javadoc是Sun公司提供的一个技术,它从程序源代码中抽取类.方法.成员等注释形成一个和源代 ...
- ABP给WebApi添加SwaggerUI,生成可交互接口文档
在ABP模板项目中,通过SwaggerUI可以为我们的WebApi生成动态的可交互接口文档页面,从而可以很方便的测试调用我们的WebApi接口. 一.集成Swagger 右键项目YoYo.Web,打开 ...
- 1.2.3 创建Cocos2D-iPhone的帮助文档
http://book.51cto.com/art/201303/383957.htm <Cocos2D权威指南>第1章开始前的准备工作,本章我们将介绍什么是Cocos2D以及有关Coco ...
- 【.NET深呼吸】Zip文件操作(1):创建和读取zip文档
.net的IO操作支持对zip文件的创建.读写和更新.使用起来也比较简单,.net的一向作风,东西都准备好了,至于如何使用,请看着办. 要对zip文件进行操作,主要用到以下三个类: 1.ZipFile ...
- php创建读取 word.doc文档
创建文档; <?php $html = "this is question"; for($i=1;$i<=3;$i++){ $word = new word(); $w ...
- dom4j创建和解析xml文档
DOM4J解析 特征: 1.JDOM的一种智能分支,它合并了许多超出基本XML文档表示的功能. 2.它使用接口和抽象基本类方法. 3.具有性能优异.灵活性好.功能强大和极端易用的特点. 4.是一个开 ...
- 用R创建Word和PowerPoint文档--转载
https://www.jianshu.com/p/7df62865c3ed Rapp --简书 Microsoft的Office软件在办公软件领域占有绝对的主导地位,几乎每个职场人士都必须掌握Wor ...
- MFC中 创建基于CFormView的文档视图程序
在MFC中可以创建多种类型的窗口程序,如对话框程序.单文档结构程序(非文档/视图结构).单文档(文档/视图结构)以及多文档视图结构程序等. 在编写一般的小工具时,我们的首选显然是对话框程序,不过基于对 ...
- Open Cascade创建自己的MFC文档程序
项目初始设置在Visual studio中创建一个单文档MFC项目(本例以MFCTest为名称): 在项目属性的VC++页面设置包含目录.库目录,在链接器的输入中添加OCC库目录下的所有.lib文件名 ...
随机推荐
- 去除input框的值
onfocus="this.value=' ';" <input type="text" name="buynum" id=" ...
- beyond compare添加右键快捷方式
如果安装beyond compare后,右键不能出现比较选项,可以通过设置 beyond compare完成. 选择 工具->选项,在资源管理器整合下面,有一个在资源管理器关联菜单中显示beyo ...
- Cena使用
打开cena,在工具-选项中,修改G++和GCC的编译命令.格式:[g++目录]g++.exe %s.cpp -o %s.exe [编译选项]例如以下命令使用刚安装的mingw4.8.1 g++编译, ...
- Darwin Streaming Server编译
EasyDarwin是我们在Darwin Streaming Server的基础上进行开发和扩展的,Windows/Linux编译,包括64位编译补丁,我们都进行了整理和测试,后续还会不断进行迭代和扩 ...
- 高速排序及优化(Java版)
高速排序(Quicksort)是对冒泡排序的一种改进. 高速排序由C. A. R. Hoare在1962年提出. 一次高速排序具体过程: 选择数组第一个值作为枢轴值. 代码实现: package Qu ...
- Django学习之站点缓存详解
本文和大家分享的主要是django缓存中站点缓存相关内容,一起来看看吧,希望对大家学习django有所帮助. 缓存整个站点,是最简单的缓存方法 在 MIDDLEWARE_CLASSES 中加入 “ ...
- 安装mysql时,提示This application requires .NET framework 4.0问题
Question:双击MySQL的安装文件, 弹框提示, Answer:安装微软的 .NET Framework 4或更新的版本,下载地址:https://www.microsoft.com/zh ...
- DTLS学习笔记 -- RFC 4347- 6347
想学习一下dtls,是因为想以后没有公司免费VPN可用的时候,我能买一个主机,自己建一个VPN. 1.介绍 Web, email大多用TLS协议来做安全的网络传输,它们必须跑在可靠的TCP传输通道里. ...
- 使用php ffmpeg处理视频
工作中遇到video加载视频的问题,但是视频封面在手机上无法取到视频的第一帧,video标签无法在手机上取到第一帧,经过几天的研究于搜索终于找到比较好用的办法,就是php ffmped 插件,该插件的 ...
- vue中引入百度统计
vue作为单页面的,引入百度统计,需要注意不少. 一.基本的流量统计 在index.html 入口文件中引入百度统计生成的一连串代码: var _hmt = _hmt || []; (function ...