演練2: 為文檔網站添加API文檔
完成 演練1: 為文檔網站添加簡單文檔 以后, 我們利用 .md 文件成成一個網站。我們稱之為 Conceptual Documentation（概念文檔）。在本節(jié)演練中, 我們將學會如何從.NET 源代碼生成網站， 我們稱之為 API 文檔. 我們會把 Conceptual Documentation（概念文檔） 和 API 文檔 集成到一個網站, 這樣我們可以無縫的從 概念文檔 導航到 API 文檔,或者從 API 文檔 導航到 概念文檔。在 這里 下載本演練需要用到的文件 .
完成演練1以后, 我們的 D:\docfx_walkthrough\docfx_project 目錄結構如下：
|- 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# 項目生成元數據
在目錄 D:\docfx_walkthrough\docfx_project 下面運行docfx metadata . docfx metadata 是 docfx 里面注冊的子命令,它會從
docfx.json文件中讀取metadata 配置節(jié). metadata/src/files 配置節(jié)中的 [ "src/**.csproj" ] 告訴 docfx 在 src 子目錄中檢索所有的 csproj 生成元數據。
"metadata": [
{
"src": [
{
"files": [
"src/**.csproj"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site/**"
]
}
],
"dest": "api"
}
]
操作將會在 api 目錄生成一些 YAML 文件. YAML 文件包含從 C# 源代碼中抽取出來的數據模型。YAML 是 docfx使用的元數據格式。 一般性元數據規(guī)范 中定義了數據結構,并且 .NET 元數據規(guī)范 中定義了 “docfx” 可以使用的.NET語言的元數據結構。
|- HelloDocfx.Class1.InnerClass.yml
|- HelloDocfx.Class1.yml
|- HelloDocfx.yml
|- toc.yml
第3步. 生成并預覽網站
運行 docfx命令。 docfx 挨個讀取執(zhí)行目錄中定義的 docfx.json 并執(zhí)行. 我們的 docfx.json 定義了 metadata 以及 build, 所以運行 docfx 的時候, 我們實際執(zhí)行了 docfx metadata 以及 docfx build, 并且會生成網站。
運行 docfx serve _site 命令,生成網站如下
第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元數據文件被生成到“api-vb”文件夾中。 我們還需要在 build 配置節(jié)中包含生成的YAML文件：
"build": {
"content": [
{
"files": [
"api-vb/**.yml"
]
}
...
為了組織和顯示到我們的文檔1網站，我們還需要修改我們的 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 命令, 網站如下所示：
總結
在本演練中，我們生成一個包含概念文檔和** API文檔的網站。 在即將到來的一系列高級演練中，我們將學習“docfx”中的高級概念，例如文章之間的引用，其他文檔的外部引用等。我們還將學習定制我們的網站，從主題到布局 到元數據提取。
