演练2: 为文档网站添加API文档
完成 演练1: 为文档网站添加简单文档 以后, 我们利用 .md 文件成成一个网站。我们称之为 Conceptual Documentation（概念文档）。在本节演练中, 我们将学会如何从.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目录下面创建子src目录. 打开 Visual Studio Community 2015 (或者更高版本) ，在src目录下创建一个名为HelloDocfx的 C# Class Library .在类Class1.cs中,为类和方法添加如下注释：
namespace HelloDocfx
{
///
/// Hello this is **Class1** from *HelloDocfx*
///
public class Class1
{
private InnerClass _class;
public int Value { get; }
///
/// This is a ctor
///
/// The value of the class
public Class1(int value)
{
Value = value;
}
public double ConvertToDouble()
{
return Value;
}
///
/// A method referencing a inner class
///
/// The name
/// A inner class with type 第2步. 为 C# 项目生成元数据
在目录 D:\docfx_walkthrough\docfx_project 下面运行docfx metadata . docfx metadata 是 docfx 里面注册的子命令,它会从
docfx.json文件中读取metadata 配置节. metadata/src/files 配置节中的 [ "src/**.csproj" ] 告诉 docfx 在 src 子目录中检索所有的 csproj 生成元数据。
"metadata": [
{
"src": [
{
"files": [
"src/**.csproj"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site/**"
]
}
],
"dest": "api"
}
]
操作将会在 api 目录生成一些 YAML 文件. YAML 文件包含从 C# 源代码中抽取出来的数据模型。YAML 是 docfx使用的元数据格式。 一般性元数据规范 中定义了数据结构,并且 .NET 元数据规范 中定义了 “docfx” 可以使用的.NET语言的元数据结构。
|- HelloDocfx.Class1.InnerClass.yml
|- HelloDocfx.Class1.yml
|- HelloDocfx.yml
|- toc.yml
第3步. 生成并预览网站
运行 docfx命令。 docfx 挨个读取执行目录中定义的 docfx.json 并执行. 我们的 docfx.json 定义了 metadata 以及 build, 所以运行 docfx 的时候, 我们实际执行了 docfx metadata 以及 docfx build, 并且会生成网站。
运行 docfx serve _site 命令,生成网站如下
第4步. 添加另外一个 API 文档
在D:\docfx_walkthrough\docfx_project下面创建另外一个 src2 子目录 . 除了可以从项目文件生成API文档外，docfx 还可以直接从源代码生成文档。 让我们创建一个“Class2.cs”，如下所示：
namespace HelloDocfx
{
///
/// Hello this is **Class2** from *HelloDocfx*
///
public class Class2
{
private InnerClass _class;
public int Value { get; }
///
/// This is a ctor
///
/// The value of the class
public Class2(int value)
{
Value = value;
}
public double ConvertToDouble()
{
return Value;
}
///
/// A method referencing a inner class
///
/// The name
/// A inner class with type 按照下面的方式把他添加到我们的 docfx.json 文件的 metadata 配置节：
"metadata": [
{
"src": [
{
"files": [
"src/**.csproj"
],
"exclude": [
"**/bin/**",
"**/obj/**",
"_site/**"
]
}
],
"dest": "api"
},
{
"src": "src2/**.cs",
"dest": "api-vb"
}
]
这意味着 “src2 / ** .cs” 中的YAML元数据文件被生成到“api-vb”文件夹中。 我们还需要在 build 配置节中包含生成的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”中的高级概念，例如文章之间的引用，其他文档的外部引用等。我们还将学习定制我们的网站，从主题到布局 到元数据提取。
更多相关文章
演练1: 为文档网站添加简单文档
高级演练: 自定义文档网站