演練2: 為文檔網(wǎng)站添加API文檔
完成 演練1: 為文檔網(wǎng)站添加簡單文檔 以后, 我們利用 .md 文件成成一個網(wǎng)站柏靶。我們稱之為 Conceptual Documentation（概念文檔）。在本節(jié)演練中, 我們將學(xué)會如何從.NET 源代碼生成網(wǎng)站辞槐， 我們稱之為 API 文檔. 我們會把 Conceptual Documentation（概念文檔） 和 API 文檔 集成到一個網(wǎng)站, 這樣我們可以無縫的從 概念文檔 導(dǎo)航到 API 文檔,或者從 API 文檔 導(dǎo)航到 概念文檔谓松。在 這里 下載本演練需要用到的文件 .
完成演練1以后, 我們的 D:\docfx_walkthrough\docfx_project 目錄結(jié)構(gòu)如下：
|- index.md
|- toc.yml
|- articles
| |- intro.md
| |- details1.md
| |- details2.md
| |- details3.md
| |- toc.yml
|- images
|- details1_image.png
|- api
|- index.md
|- toc.yml
第1步. 添加 C# 項目
- 在
D:\docfx_walkthrough\docfx_project目錄下面創(chuàng)建子src目錄. 打開 Visual Studio Community 2015 (或者更高版本) 何恶，在src目錄下創(chuàng)建一個名為HelloDocfx的 C# Class Library .在類Class1.cs中,為類和方法添加如下注釋：
namespace HelloDocfx
{
/// <summary>
/// Hello this is **Class1** from *HelloDocfx*
/// </summary>
public class Class1
{
private InnerClass _class;
public int Value { get; }
/// <summary>
/// This is a ctor
/// </summary>
/// <param name="value">The value of the class</param>
public Class1(int value)
{
Value = value;
}
public double ConvertToDouble()
{
return Value;
}
/// <summary>
/// A method referencing a inner class
/// </summary>
/// <param name="name">The name</param>
/// <param name="inner">A inner class with type <seealso cref="InnerClass"/></param>
public void SetInnerClass(string name, InnerClass inner)
{
inner.Name = name;
_class = inner;
}
public class InnerClass
{
public string Name { get; set; }
}
}
}
第2步. 為 C# 項目生成元數(shù)據(jù)
在目錄 D:\docfx_walkthrough\docfx_project 下面運行docfx metadata . docfx metadata 是 docfx 里面注冊的子命令,它會從
docfx.json文件中讀取metadata 配置節(jié). metadata/src/files 配置節(jié)中的 [ "src/**.csproj" ] 告訴 docfx 在 src 子目錄中檢索所有的 csproj 生成元數(shù)據(jù)寄啼。
"metadata": [
{
"src": [
{
"files": [
"src/**.csproj"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site/**"
]
}
],
"dest": "api"
}
]
操作將會在 api 目錄生成一些 YAML 文件. YAML 文件包含從 C# 源代碼中抽取出來的數(shù)據(jù)模型恩够。YAML 是 docfx使用的元數(shù)據(jù)格式背率。 一般性元數(shù)據(jù)規(guī)范 中定義了數(shù)據(jù)結(jié)構(gòu),并且 .NET 元數(shù)據(jù)規(guī)范 中定義了 “docfx” 可以使用的.NET語言的元數(shù)據(jù)結(jié)構(gòu)话瞧。
|- HelloDocfx.Class1.InnerClass.yml
|- HelloDocfx.Class1.yml
|- HelloDocfx.yml
|- toc.yml
第3步. 生成并預(yù)覽網(wǎng)站
運行 docfx命令。 docfx 挨個讀取執(zhí)行目錄中定義的 docfx.json 并執(zhí)行. 我們的 docfx.json 定義了 metadata 以及 build, 所以運行 docfx 的時候, 我們實際執(zhí)行了 docfx metadata 以及 docfx build, 并且會生成網(wǎng)站寝姿。
運行 docfx serve _site 命令,生成網(wǎng)站如下
第4步. 添加另外一個 API 文檔
在D:\docfx_walkthrough\docfx_project下面創(chuàng)建另外一個 src2 子目錄 . 除了可以從項目文件生成API文檔外交排，docfx 還可以直接從源代碼生成文檔。 讓我們創(chuàng)建一個“Class2.cs”饵筑，如下所示：
namespace HelloDocfx
{
/// <summary>
/// Hello this is **Class2** from *HelloDocfx*
/// </summary>
public class Class2
{
private InnerClass _class;
public int Value { get; }
/// <summary>
/// This is a ctor
/// </summary>
/// <param name="value">The value of the class</param>
public Class2(int value)
{
Value = value;
}
public double ConvertToDouble()
{
return Value;
}
/// <summary>
/// A method referencing a inner class
/// </summary>
/// <param name="name">The name</param>
/// <param name="inner">A inner class with type <seealso cref="InnerClass"/></param>
public void SetInnerClass(string name, InnerClass inner)
{
inner.Name = name;
_class = inner;
}
public class InnerClass
{
public string Name { get; set; }
}
}
}
按照下面的方式把他添加到我們的 docfx.json 文件的 metadata 配置節(jié)：
"metadata": [
{
"src": [
{
"files": [
"src/**.csproj"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site/**"
]
}
],
"dest": "api"
},
{
"src": "src2/**.cs",
"dest": "api-vb"
}
]
這意味著 “src2 / ** .cs” 中的YAML元數(shù)據(jù)文件被生成到“api-vb”文件夾中埃篓。 我們還需要在 build 配置節(jié)中包含生成的YAML文件：
"build": {
"content": [
{
"files": [
"api-vb/**.yml"
]
}
...
為了組織和顯示到我們的文檔1網(wǎng)站，我們還需要修改我們的 D:\docfx_walkthrough\docfx_project\toc.yml 文件根资。 不要忘記為href'的值附加斜杠/`架专。
- name: Articles
href: articles/
- name: Api Documentation
href: api/
homepage: api/index.md
- name: Another Api Documentation
href: api-vb/
好了,讓我們再次運行 docfx --serve 命令, 網(wǎng)站如下所示：
總結(jié)
在本演練中同窘，我們生成一個包含概念文檔和** API文檔的網(wǎng)站。 在即將到來的一系列高級演練中部脚，我們將學(xué)習“docfx”中的高級概念想邦，例如文章之間的引用，其他文檔的外部引用等委刘。我們還將學(xué)習定制我們的網(wǎng)站丧没，從主題到布局 到元數(shù)據(jù)提取。
