【开源】文档生成工具 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_projectdocfx.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
- A basic C# project under
src
. - Several conceptual files under
articles
. - An overwrite file to add extra content to API under
specs
. -
toc.yml
under root folder. It renders as the navbar of the website. -
docfx.json
under root folder. It is the configuration file thatdocfx
depends upon.
Tip: It is a good practice to separate files with different type into different folders.
6. Q&A
- Q: How do I quickly reference APIs from other APIs or conceptual files? A: Use
@uid
syntax. - Q: What is
uid
and where do I finduid
? A: Refer to Cross Reference section in DFM. - 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 finduid
indata-uid
attribute.
- 一次切割日志引发的血案
- lncRNA实战项目-第三步-了解参考基因组及注释文件
- 如何通过iframe调用其他页面的内容
- WCF 学习总结1 -- 简单实例
- Java8 + Tomcat8 实现Websocket 例子
- Python Syslog Server 开发实例
- WCF 学习总结2 -- 配置WCF
- SQLite事务 SQLite插入多条语句为什么这么慢?.net (C#)
- Linux 应用程序开发入门
- LINQ to XML LINQ学习第一篇
- PHP 安全与性能
- Extjs 项目中常用的小技巧,也许你用得着(5)--设置 Ext.data.Store 传参的请求方式
- WPF备忘录(5)怎样修改模板中的控件
- Linux 系统与数据库安全
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法
- Android MeasureSpec的理解和源码的解析
- Android 中自定义ContentProvider与ContentObserver的使用简单实例
- Android沉浸式状态栏的实现代码
- MyBatis源码解析之基础模块—DataSource
- Android中Activity和Fragment传递数据的两种方式
- Android MTU 值修改的实例详解
- Android ListView填充数据的方法
- AFURLSessionManager 上传下载使用代码说明
- Android APP之WebView校验SSL证书的方法
- Android中okhttp3使用详解
- Android中RecyclerView实现Item添加和删除的代码示例
- 小程序图片上传,存储,获取,显示(含源码)
- Android网络请求框架Retrofit详解
- Android控件RadioButton实现多选一功能
- 解决Android使用Handler造成内存泄露问题