一、简介

Docfx 是微软开发的一款开源的文档生成工具,其默认支持 C# 与 VB.Net 这两种项目的文档生成,支持 DotNetCore 项目,并且还可以打包成一个静态的 Web 站点,而且还支持 markdown 文件。

这个站点就是 ImageSharp 的 API 文档,可以去参考一下。

二、安装

下载

Docfx 是即开即用的,他基于 .Net Framework 开发,所以我们可以先在 Windows 平台上面生成 API 文档试一下,DocFx 的下载地址为 https://github.com/dotnet/docfx/releases,选择最新版本下载即可。

设置环境变量

然后解压其压缩包,因为这是一个命令行程序,所以我们可以将其目录添加到环境变量以便于我们在任何地方来使用。

按住 Shift 键再点击右键在当前目录弹出 cmd 命令行窗口,输入一下命令:

setx PATH "%Path%;< 这里是你 docfx.exe 所在的目录>"

三、使用

初始化基础项目

在你需要生成基础项目的文件夹下打开命令行窗口,运行 docfx init -q 就回在当前目录下生成一个 docfx_project 文件夹,这里面包含了一些基本配置,稍后再讲。

生成 API yml 文件

docfx 支持为 csproj 与 sln 来生成 API 文档,假如你的库有很多个的话,就可以直接根据 sln 解决方案来生成 API 文档。

我们来到 API 目录下面,在 csproj 文件所在目录打开命令行窗口,运行 docfx metadata ./api.csproj 命令就会在这个目录下面生成一个 _api 文件夹,这里面会包含大量像这样的 yml 文件。

将这些文件拷贝到 docfx_project 目录下的 api 文件夹内,编辑 docfx_project 根目录的 toc.yml 文件,如下:

这里面就是管理 API 站点目录结构的,可以看到这里的每一个以 - 划分的都是一个节点,也就是在 API 站点顶部导航栏所展示的内容,而 href 则是该导航栏指向的文档目录路径。homepage 则是首页的 markdown 文件。

如果你有一些自定义的文档则可以在这里添加目录结构。

构建 API 站点

文件这些已经准备就绪,原始的站点文档都以 yml 文件与 md 文件为主,我们可以通过调用 docfx ./docfx.json 命令来将这些文件构建成一个静态的 html 站点。

预览 API 站点

如果我们想查看效果的话,可以在 docfx_project 目录执行 docfx serve ./_site 命令,它将会开启一个服务器,你也可以通过 -p 参数来指定自己的端口,例如 docfx serve ./_site -p 5000

四、部署

如果只是自己看就没什么用了,那么我们还可以通过 Docker 来将我们的站点部署到服务器上,如何来做呢?大致思路就是一个 docker 镜像生成 _site 文件夹,一个镜像来做 Web 服务器承载站点。

制作镜像

1.文档生成镜像 doc_generator

那么我们首先来编写生成 docker 镜像的 Dockerfile 文件:

FROM mono:latest
WORKDIR /work
COPY ./ .
# 构建 API 站点
RUN mono /work/docfx/docfx.exe /work/docfx.json \
&& mkdir /app
ENTRYPOINT ["cp","-r","/work/_site/*","/app"]

运行 docker build -t doc_generator . 命令生成了一个 doc_generator 镜像。

2.Web 服务器镜像 nginx

这里 Web 服务器镜像并不需要特别的定制,直接使用 nginx 的默认镜像就可以了。

运行镜像

那么我们来编写一个 Shell 运行我们的镜像:

#!/bin/bash
docker run -dti -v /temp/document_html:/app --name=doc_generator doc_generator
# 移动文件,更改文件目录结构
cp -r /temp/document_html/_site/* /temp/document_html
docker run --name=doc_nginx -d -p 20001:80 -v /temp/document_html:/usr/share/nginx/html nginx

执行脚本之后查看效果:

五、后记

结合 Jenkins 等 CI 你可以实现自动增量更新,这里就不再赘述了。

[Other]在 Docker 当中搭建 Docfx 站点的更多相关文章

  1. spring boot / cloud (十八) 使用docker快速搭建本地环境

    spring boot / cloud (十八) 使用docker快速搭建本地环境 在平时的开发中工作中,环境的搭建其实一直都是一个很麻烦的事情 特别是现在,系统越来越复杂,所需要连接的一些中间件也越 ...

  2. 使用docker快速搭建Permeate渗透测试系统实践

    一.背景 笔者最近在做一场Web安全培训,其中需要搭建一套安全测试环境:在挑选渗透测试系统的时候发现permeate渗透测试系统比较满足需求,便选择了此系统:为了简化这个步骤,笔者将系统直接封装到了d ...

  3. Docker 实践搭建php环境

    docker 安装 使用官方提供的安装脚本,安装最新版的Docker curl -sSL https://get.docker.com/ | sh 安装完成后,通过如下命令启动Docker的守护进程, ...

  4. 【架构】docker环境搭建mysql主从

    序 本文主要研究怎么在docker上搭建mysql的主从.因为在单机搭建mysql多实例然后再配主从,感觉太痛苦了,环境各有不同,配置各不大相 同,从网上找搭建方法,试了半天也没成功,最后也没耐心调试 ...

  5. docker中搭建jenkins环境

    想在docker中搭建一个jenkins环境.开始的时候我想在先pull centos,然后在里面自己搭建环境,搭建后的环境可以运行,但是不知道挂载哪的数据,这也是我不熟悉jenkins的原因. 同事 ...

  6. 本地如何使用phpstudy环境搭建多站点

    http://jingyan.baidu.com/article/e52e36154227ef40c70c5147.html 平时在开发项目的时候, 多个项目同时开发的时候会遇到都得放到根目录才能正常 ...

  7. docker快速搭建几个常用的第三方服务

    本次和大家分享的内容是使用docker快速搭建工作中常用的第三方的服务,对于有一些互联网背景的公司来说,以下几个服务都是很需要的:redis,rabbit,elasticsearch: 本篇涉及内容深 ...

  8. Docker Machine搭建并加入节点

    对于集群服务器来讲,要在每台机器上手动安装Docker是一件及其痛苦的事情,还好有Docker Machine这一工具,Docker三剑客中的一角. 一.Docker Machine介绍 这个工具已经 ...

  9. centos7系统下 docker 环境搭建

    运行环境: VMware Workstation Pro 在虚拟机中安装centos7系统, 选择最小安装, 网络连接方式选择的桥接(与宿主机在同一IP段)centos7一定要安装64位, docke ...

随机推荐

  1. GCD API 记录 (三)

    本篇就不废话啦,接着上篇记录我见过或者使用过的与GCD相关的API.由于一些API使用的非常少,用过之后难免会忘记,还是记录一下比较好. 6.dispatch_group_wait 该API依然是与d ...

  2. 【iOS 开发】Objective - C 面向对象 - 方法 | 成员变量 | 隐藏封装 | KVC | KVO | 初始化 | 多态

    一. Objective-C 方法详解 1. 方法属性 (1) OC 方法传参机制 Object-C 方法传参机制 : OC 中得参数传递都是值传递, 传入参数的是参数的副本; -- 基本类型 (值传 ...

  3. Android的ExpandableListView-android学习之旅(二十八)

    ExpandableListView简介 ExpandableListView是ListView的子类,用法和ListView类似,ExpandableListView可以创建几个类别,每个类别下面又 ...

  4. Win8.1开启Hyper-V并设置虚拟机联网

    虚拟机用惯了VM,听说win8自带的hype-v不错比原来有了较大的改进,特地来试试. win8开启hype-v的方式如下 安装完重启下就可以了. 接着说联网,Hype-v的设置个人感觉稍微比VM麻烦 ...

  5. jQuery 异步上传插件 Uploadify302 使用 (JavaEE Spring MVC)

    Uploadify是JQuery的一个上传插件,实现的效果非常不错,带进度显示.而且是Ajax的,省去了自己写Ajax上传功能的麻烦.不过官方提供的实例时php版本的,本文将详细介绍Uploadify ...

  6. 我眼中的Linux设备树(二 节点)

    二 节点(node)的表示首先说节点的表示方法,除了根节点只用一个斜杠"/"表示外,其他节点的表示形式如"node-name@unit-address".@前边 ...

  7. 批量替换数据库中所有用户数据表中字段数据类型为char和varchar到nvarchar的脚本

    解决问题:字段类型为char的总是占用指定字节长度(末尾好多空白符号),varchar数据类型长度一个汉字占2个字节,内容存储为中文的字段个人建议全部使用nvarchar. 操作说明:打开SQL Se ...

  8. UNIX环境高级编程——标准I/O库函数和Unbuffered I/O函数

    以写文件为例,C标准I/O库函数(printf(3) .putchar(3) .fputs(3) )与系统调用write(2) 的关 系如下图所示. 库函数与系统调用的层次关系 open .read ...

  9. listview的工作原理

    /** * Unsorted views that can be used by the adapter as a convert view. */ private ArrayList<View ...

  10. Mahout 算法

    Mahout 包括协同过滤,基于User和Item的推荐:kmeans.Fuzzy-kmeans .Mean shift .Dirichlet process .LDA聚类:奇异值分解:并行频繁项集挖 ...