docfx 作一个和微软同样的文档平台

https://blog.csdn.net/lindexi_gd/article/details/78661304

 

c#（166） 

版权声明：http://blog.csdn.net/lindexi_gd 本文为博主原创文章，未经博主容许不得转载。 https://blog.csdn.net/lindexi_gd/article/details/78661304

 

目录(?)[+]

 

开发中，有一句话叫 最不喜欢的是写文档，最不喜欢的是看别人家代码没有文档。那么世界上文档写最 la 好 ji 的就是微软了，那么微软的api文档是如何作的？难道请了不少人去写文档？

实际上微软有工具用来生成 api 文档和教程。

我这里说的微软文档是：https://docs.microsoft.com/en-us/dotnet/articles/csharp/index 这个网站，不是之前的。

 

微软文档使用的工具是 docfx ，这是一个很好的工具。

本文将告诉你们如何使用这个工具作出和微软同样的文档

下载

第一步是下载，下载地址是 https://github.com/dotnet/docfx/releases 若是以为github下载太慢，能够下载我上传的：http://download.csdn.net/detail/lindexi_gd/9839609

安装

下载以后须要解压到软件运行的文件夹，假如通常放软件的是在 E:\软件 ，就能够把他解压到这里。

假设解压到 E:\软件\docfx

在使用以前须要肯定已经安装.NET Core和Microsoft .NET Framework 4.6

环境变量

由于这个软件是命令行，因此但愿在任何均可以使用，添加软件到环境变量

setx PATH "%PATH%;E:\软件\docfx\"

• 1

建立文档文件

首先建立一个文件夹，用来放临时文件

这里使用的文件夹是D:\docfx_walkthrough

而后使用cmd进入这个文件夹。

简单的方法是地址输入就好，不须要打开cmd一点进入

在cmd输入命令 docfx init -q 后面的参数是表示快速，若是但愿让他问你，你本身写设置，那么就不要加参数。

输入这个命令会生成docfx_project，这里就是新建的文件，能够看到 docfx.json

这个文件就是设置文件，能够打开看一下

生成文档

如今就能够进行生成文档了，由于默认就有一些文档。

我也以为快点让你看到这个工具如何使用才是好的，不须要作太多步就能够看到本身弄出来的网站，这个感受通常仍是很好。

在cmd输入下面命令，由于这里的 cmd 没进入 docfx_project ，路径就是这样

docfx docfx_project/docfx.json

• 1

能够看到建立了 _site ，这里就是网页，可是本地查看网页不太好，来使用自带的方法。

查看文档

这个工具可让你从浏览器看到本身的文档，使用方法是在cmd输入代码

docfx serve docfx_project/_site

• 1

打开 http://localhost:8080 就能够看到网站啦。

注意，若是你的 8080 端口被占用，能够本身定义打开的哪一个

docfx serve docfx_project/_site  -p 能够用端口

• 1

添加文档

如今让咱们添加本身的文档

打开 articles 文件夹，添加本身的文档，这里添加

win10 uwp MVVM入门.md win10-uwp-快捷键.md

• 1
• 2
• 3

打开 articles 的 toc.yml ，把文件添加进来

- name: win10 uwp MVVM入门 href: win10 uwp MVVM入门.md - name: win10-uwp-快捷键 href: win10-uwp-快捷键.md 

• 1
• 2
• 3
• 4
• 5

如今已经作好啦

重复 生成文档 和 查看文档 文档两步。

首先关闭 cmd 再打开，生成文档

docfx.exe ./docfx.json

• 1

查看文档

docfx serve _site -p 1560

• 1

打开 http://localhost:1560/ 就能够看到

能够看到添加文档须要本身写目录，这个不是很好，因此我就写了一个工具来生成。

添加代码文档

api文档是主要的，生成api文档须要安装vs2015以上。

首先进入工程，这里进入工程C:\程序\uwp\uwp\src\Framework\wpfMill

接着使用docfx metadata添加 *.sln

这里使用的是 csproj，两个都是支持的

docfx metadata ./wpfMill.csproj

• 1

能够看到文件夹多了 _api

把他剪切到刚才的临时文件

这里是D:\docfx_walkthrough，如今的临时文件看起来是

把 _api 全部文件放到 api

打开 D:\docfx_walkthrough\toc.yml

- name: Articles href: articles/ - name: Api Documentation href: api/ homepage: api/index.md

• 1
• 2
• 3
• 4
• 5

删除获得

- name: Articles href: articles/ - name: Api Documentation href: api/ 

• 1
• 2
• 3
• 4

而后重复 生成文档 和 查看文档 文档两步

打开 代码文档 看到

左边和右边看起来仍是很好

作本身的修改

我也以为如今尚未那好，由于图标

默认的有 default iframe.html statictoc

导入微软的代码docfx template export 要哪一个

docfx template export default

• 1

能够看到多了 _exported_templates 文件

修改他的名字template 而后把 default 全部文件拿出来，放在这个文件里面。

打开docfx.json 修改默认使用的

"template": [ "default" ]

• 1
• 2
• 3

修改以后

"template": [ "template" ]

• 1
• 2
• 3

而后修改 template 的图标

如今看起来很好了，可是须要继续修改，能够打开 partials

这里就是全部能够修改的样式

下面来讲一个例子：

打开 footer.tmpl.partial

 {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} <footer> <div class="grad-bottom"></div> <div class="footer"> <div class="container"> <span class="pull-right"> <a href="#top">Back to top</a> </span> {{{_appFooter}}} {{^_appFooter}}<span>Copyright © 2015-2017 Microsoft<br>Generated by <strong>DocFX</strong></span>{{/_appFooter}} </div> </div> </footer> 

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15

把微软改成本身名字

 {{!Copyright (c) Microsoft. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} <footer> <div class="grad-bottom"></div> <div class="footer"> <div class="container"> <span class="pull-right"> <a href="#top">Back to top</a> </span> {{{_appFooter}}} {{^_appFooter}}<span>Copyright © 2015-2017 lindexi<br>Generated by <strong>DocFX</strong></span>{{/_appFooter}} </div> </div> </footer> 

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15

从新生成文档，就能够看到，页面变化了

忽略不使用的api

常常有一些api是不但愿显示在文档的。

能够忽略的方法有两个：第一个方法是在生成时添加忽略文件

docfx.exe metadata -filter 忽略配置文件所在的路径

• 1

忽略文件的路径能够是相对的。

第二个方法是写在 docfx.json

添加一个属性 filter ，假如使用的忽略文件是 filterConfig.yml ，那么如今的文件就能够看到以下面代码

{
  "metadata": [ { "src": [ { "files": [ "src/**.csproj" ], "exclude": [ "**/bin/**", "**/obj/**" ] } ], "dest": "obj/api", "filter": "filterConfig.yml" } ] }

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19

接下来就是如何写 filterConfig.yml 。

这个文件能够包含包括的文件和不包括的，包括的权限比不包括大，默认是包括全部文件

包括的文件使用include 不包括使用 exclude ，看起来的文件是

- include: uidRegex: ^Microsoft\.DevDiv\.SpecialCase - exclude: uidRegex: ^Microsoft\.DevDiv 

• 1
• 2
• 3
• 4
• 5

由于 uidRegex 是匹配，因此对于.须要加上\\

强大的ms还能够匹配是什么类型，提供的：

• Namespace
• Type
• Class
• Struct
• Enum
• Interface
• Delegate
• Member
• Event
• Field
• Method
• Property

若是要忽略命名空间是 lindexi.laji 的代码，请看下面代码

- exclude: uidRegex: ^lindexi\.laji type: Namespace

• 1
• 2
• 3

原文：http://dotnet.github.io/docfx/index.html

继续在微软上开发

能够看到如今的 docfx 还不够好，因而我继续在微软作的上面开发。

我须要在一个文件夹包含多个项目的状况下，以及包含多个文件夹，里面包含多个项目的状况，能够解析出他们的文档和代码。

我想到的作法是在须要转换的文件夹添加一个文件，这个文件就是配置文件，表示这个文件夹内有哪些文件夹是代码，哪些是文档。对于代码的，须要有哪些是忽略的。

因而程序就获取配置的文件，从文件获取到存在哪些文件夹是须要进行转换的。

而后 遍历整个文件夹，获取文件夹里的配置，从而获得须要进行作的文件夹。

若是文件夹里的配置出错了，如找不到文件或其余的错误，那么报告为警告就好。

程序能够从全部的文件夹获取配置，若是一个文件夹存在配置文件：

docfx.json

那么读取配置文件里存在哪些配置文件，其中，文件的格式为：

Src:
- E:\12 Doc: E:\123123 DocfxFolder: - E:\文件夹1 - E:\文件夹2

• 1
• 2
• 3
• 4
• 5
• 6

class Docfx
    {
        /// <summary> /// 代码所在的文件 /// </summary> public List<string> Src { get; set; } /// <summary> /// 文档所在的文件夹 /// </summary> public string Doc { get; set; } /// <summary> /// 包含须要进行文档的文件夹 /// <remarks><para>如我有两个文件夹在不一样路径，那么能够在这里写这两个文件夹</para> /// 或我把这个文件放在和本程序相同的路径，用这个文件来讲明我须要转换的文件 /// </remarks> /// </summary> public List<string> DocfxFolder { get; set; } } 

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19
• 20
• 21
• 22
• 23
• 24
• 25
• 26
• 27
• 28
• 29
• 30

通常可使用一个配置告诉程序，须要把几个项目的文档放在一个文件夹里，这样能够作搜索比较好。

因而这个配置就是只有 DocfxFolder 一个属性。通常不能够在使用 DocfxFolder 以后使用 Src 等属性。可是我这里没有作要求，只是判断若是存在 DocfxFolder 就不去读其余属性。

能够容许只有三个属性的一个。

本做品采用知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议进行许可。欢迎转载、使用、从新发布，但务必保留文章署名林德熙(包含连接:http://blog.csdn.net/lindexi_gd )，不得用于商业目的，基于本文修改后的做品务必以相同的许可发布。若有任何疑问，请与我联系。