【开源】文档生成工具 DocFX

源码:https://github.com/dotnet/docfx 下载:https://github.com/dotnet/docfx/releases 说明:https://github.com/OpenLiveWriter/OpenLiveWriter/issues/203 详细:http://dotnet.github.io/docfx/tutorial/docfx_getting_started.html

微软最近开源了全新的文档生成工具DocFX,目前支持C#和VB,类似JSDoc或Sphinx,可以从源代码中提取注释生成文档之外,而且还有语法支 持你加入其他的文件链接到API添加额外的说明,DocFX会扫描你的源代码和附加的文件为你生成一个完整的HTML模版网站,你可以自己通过模版定制, 目前已经内嵌了几个模版,包括静态的HTML页面和AngularJS页面。你还可以自己定制模版

Getting Started with DocFX

1. What is DocFX

DocFX is an API documentation generator for .NET, and currently it supports C# and VB. It generates API reference documentation from triple-slash comments in your source code. It also allows you to use Markdown files to create additional topics such as tutorials and how-tos, and to customize the generated reference documentation. DocFX builds a static HTML website from your source code and Markdown files, which can be easily hosted on any web servers (for example, github.io). Also, DocFX provides you the flexibility to customize the layout and style of your website through templates. If you are interested in creating your own website with your own styles, you can follow how to create custom template to create custom templates.

DocFX also has the following cool features:

  • Integration with your source code. You can click "View Source" on an API to navigate to the source code in GitHub (your source code must be pushed to GitHub).
  • Cross-platform support. We have both exe version that runs under Windows and a .NET Core version that runs cross platform.
  • Integration with Visual Studio. You can seamlessly use DocFX within Visual Studio.
  • Markdown extensions. We introduced DocFX Flavored Markdown(DFM) to help you write API documentation. DFM is 100% compatible with GitHub Flavored Markdown(GFM) with some useful extensions, like file inclusion, code snippet, cross reference, and yaml header. For detailed description about DFM, please refer to DFM.

2. Use DocFX as a command-line tool

Step1. DocFX ships as a chocolatey package. Alternatively, you can download and unzip docfx.zip fromhttps://github.com/dotnet/docfx/releases, extract it to a local folder, and add it to PATH so you can run it anywhere.

Step2. Create a sample project

docfx init -q

This command generates a default project named docfx_project.

Step3. Build the website

docfx docfx_project\docfx.json --serve

Now you can view the generated website on http://localhost:8080.

3. Use DocFX in Visual Studio

As a prerequisite, you need Visual Studio 2015 to use DocFX in IDE.

Step1. Open Visual Studio and create a C# project as your documentation project. You can create an emptyASP.NET Web Application since it has a built-in preview feature that can be used to preview the generated website easily.

Step2. Right click on the website project, and choose Manage NuGet Packages... to open the NuGet Package Manager. Search and install docfx.msbuild package.

Step3. Create a .cs class in the website project, make sure the class is public, for example:

namespace WebApplication1{    public class Class1
    {
    }
}

Step4. Right click on the website project, and click View -> View in Browser, navigate to /_site sub URL to view your website!

4. Build from source code

As a prerequisite, you need:

  • Microsoft Build Tools 2015
  • .NET Core SDK
  • Node.js

Step1. git clone https://github.com/dotnet/docfx.git to get the latest code.

Step2. Run build.cmd under root folder.

Step3. Add artifacts folder to nuget source by in IDE:

Tools > NuGet Package Manager > Package Manager Settings > Package Sources

Step4. Follow steps in #2, #3, #4 to use DocFX in command-line, IDE or .NET Core.

5. A seed project to play with DocFX

Here is a seed project https://github.com/docascode/docfx-seed. It contains

  1. A basic C# project under src.
  2. Several conceptual files under articles.
  3. An overwrite file to add extra content to API under specs.
  4. toc.yml under root folder. It renders as the navbar of the website.
  5. docfx.json under root folder. It is the configuration file that docfx depends upon.

Tip: It is a good practice to separate files with different type into different folders.

6. Q&A

  1. Q: How do I quickly reference APIs from other APIs or conceptual files? A: Use @uid syntax.
  2. Q: What is uid and where do I find uid? A: Refer to Cross Reference section in DFM.
  3. Q: How do I quickly find uid in the website? A: In the generated website, hit F12 to view source, and look at the title of an API. You can find uid in data-uid attribute.

原文发布于微信公众号 - 我为Net狂(dotNetCrazy)

原文发表时间:2016-12-02

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏张善友的专栏

.NET 4.0 版本号

.NET 4.5.1, .NET 4.5 和 .NET 4.0 均基于 .NET 4.0 CLR,而 .NET 4.5 对 CLR进行了升级和Bug修复. .N...

4316
来自专栏醉梦轩

在Windows上编译openssl

1663
来自专栏张善友的专栏

Mono 2.8发布:C#4.0和更好的性能

在社区很多人不看好的微软.NET开源实现Mono发布了Mono 2.8,这是一个重要的版本更新,有着显著的改善,Mono 2.8包括C#4.0的支持(也是现在的...

1999
来自专栏.NET开发者社区

(码友推荐)2018-09-20 .NET及相关开发资讯速递

3.从壹开始前后端分离 [ Vue2.0+.NetCore2.1] 二十六║Client渲染、Server渲染知多少{补充}

1114
来自专栏张善友的专栏

在传统.NET Framework 上运行ASP.NET Core项目

新的项目我们想用ASP.NET Core来开发,但是苦于我们历史的遗产很多,比如《使用 JavaScriptService 在.NET Core 里实现DES加...

2549
来自专栏我和未来有约会

silverlight寻奇 - Graphite

Graphite是一个能自动布局的图表控件。 目前它已经有了silverlight 2 和 wpf的版本。观看demo时按下“Ctrl”键再做点击操作。 原文...

1975
来自专栏张善友的专栏

codeproject 几篇asp.net文章

Best Practices in ASP.NET for writing User Control In MultiView And Wizard using...

1966
来自专栏张善友的专栏

.NET Framework 4.5.2 静默安装参数

Microsoft .NET Framework 4.5.2 是针对 Microsoft .NET Framework 4、Microsoft .NET Fra...

3068
来自专栏逸鹏说道

C#通过WMI的wind32 的API函数实现msinfo32的本地和远程计算机的系统摘要信息查看功能

最近做一个项目碰到要实现查看本地和远程计算机的摘要信息,采用命令行msinfo32可以很快查看到,如下图: ? 需要在用C#来实现类似信息查看。尤其远程计算机的...

3675
来自专栏.NET开发者社区

(码友推荐)2018-07-06 .NET及相关开发资讯速递

1.Dotnet outdated helps you keep your projects up to date

903

扫码关注云+社区

领取腾讯云代金券