源码: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页面。你还可以自己定制模版
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:
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.
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!
As a prerequisite, you need:
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.
Here is a seed project https://github.com/docascode/docfx-seed. It contains
src
.articles
.specs
.toc.yml
under root folder. It renders as the navbar of the website.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.
@uid
syntax.uid
and where do I find uid
? A: Refer to Cross Reference section in DFM.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.