yii2 使用apidoc生成技术文档 [ 2.0 版本 ]

原文链接：yii2 使用apidoc生成技术文档

yii2 的apidoc生成文档还是蛮好用的。
首先说一下这个玩意是干什么的，就是用来生成技术文档，效果可以查看：http://www.fecshop.com/doc/fecshop-guide/cn-1.0/guide-index.html#

1.需要安装yii2，参看文章：
Yii2 – 安装高级模板 advanced project template

2.然后安装doc 插件

2.1在安装的yii2根目录下面执行：

composer require --prefer-dist yiisoft/yii2-apidoc

2.2或者在composer.json中添加：

"yiisoft/yii2-apidoc": "~2.1.0"

然后执行：composer update

可能会报错，如果报错，将上面的改成：

yiisoft/yii2-apidoc": "~2.0.0"

安装成功就可以使用了

3.写md文件

可以看下面的第四部的路径，md文件存放的地址： /www/web/develop/fecshop/doc/fecshop-guide/cn-1.0，那么我们在这个路径下面新建2个比较重要的md文件

README.md 和 index.md

README.md 是左侧菜单部分

index.md 是guide-index.html页面，一般和README.md一样，用来做首页菜单索引，当然也可以添加自己想要的内容

生成的效果可以参看：

http://www.fecshop.com/doc/fecshop-guide/cn-1.0/guide-index.html#

展示一个demo：

README.md：

    FecShop 文档说明
    ===============================
    版权所有。
    2016 (c) FecShop Software LLC。
    目前进度
    -----
    *  [Fecshop 开发进度](fecshop-jindu.md)
    *  [Fecshop 开发LOG](fecshop-jindu-log.md)
    关于与安装
    -----
    *  [Fecshop 关于-架构特点](fecshop-about-fecshop.md)
    *  [Fecshop 关于-功能介绍](fecshop-about-function.md)
    *  [Fecshop 关于-系统结构](fecshop-about-system-contruct.md)
    *  [Fecshop 安装与初始配置](fecshop-install.md)
    Fecshop配置
    -----------
    *  [Fecshop 配置-配置结构](fecshop-init-config-construction.md)
    *  [Fecshop 配置-Yii2配置](fecshop-init-config-yii2.md)
    *  [Fecshop 配置-fecshop配置](fecshop-init-config-advanced.md)

index.md

    FecShop 文档说明
    ===============================
    版权所有。
    2016 (c) FecShop Software LLC。
    关于与安装
    -----
    *  [Fecshop 关于-架构特点](fecshop-about-fecshop.md)
    *  [Fecshop 关于-功能介绍](fecshop-about-function.md)
    *  [Fecshop 关于-系统结构](fecshop-about-system-contruct.md)
    *  [Fecshop 安装-composer](fecshop-install.md)
    *  [Fecshop 安装-初始配置](fecshop-init-config.md)
    功能介绍
    --------
    *  [Fecshop 功能概叙](fecshop-feature-summary.md)
    *  [Fecshop Url自定义](fecshop-feature-url-custom.md)
    *  [Fecshop 多语言](fecshop-feature-mutil-languages.md)
    *  [Fecshop 多store](fecshop-feature-mutil-stores.md)
    *  [Fecshop 多货币](fecshop-feature-mutil-currency.md)
    *  [Fecshop 多模板](fecshop-feature-mutil-themes.md)
    *  [Fecshop 多入口](fecshop-feature-mutil-entrances.md)
    *  [Fecshop 配置层](fecshop-feature-config.md)
    *  [Fecshop 模块层](fecshop-feature-modules.md)
    *  [Fecshop Block层](fecshop-feature-block.md)
    *  [Fecshop 服务层](fecshop-feature-component-services.md)
    *  [Fecshop 独立功能块](fecshop-feature-independent-block.md)
    *  [Fecshop 权限管理](fecshop-feature-role.md)
    *  [Fecshop 缓存管理](fecshop-feature-cache.md)
    *  [Fecshop 脚本管理](fecshop-feature-script.md)
    *  [Fecshop 后台日志](fecshop-feature-admin-log.md)
    *  [Fecshop 重写功能](fecshop-feature-rewrite.md)
    *  [Fecshop 升级](fecshop-feature-upgrade.md)

在README.md文件里面你可以看到，在括号里面的文件 ，譬如 fecshop-jindu.md

你需要在 /www/web/develop/fecshop/doc/fecshop-guide/cn-1.0下新建括号里面的md文件，然后在里面写内容就行了，譬如：

    关于 Fecshop 的框架特点
    =======================
    Fecshop 全称为Fancy ECommerce Shop，是一款优秀的开源电商系统，遵循[OSL3.0协议](http://www.oschina.net/question/28_8527)，
    目的是为了方便yii2用户快速的
    开发商城，Fecshop作为一款可以持续性发展的商城系统，
    在框架层面有以下特性：
    1. 由于商城系统的复杂性，原始的框架MVC结构，显的有点力不从心，Fecshop框架
    加入了[Block层](fecshop-feature-block.md)，
    Controller层只负责调度， Model只负责数据库映射，中间的处理逻辑由block来完成，View层
    负责显示，这样各司其职， 以免造成controller文件过于庞大。
    2. 加入[独立功能块](fecshop-feature-independent-block.md)，有点类似Yii2的Widget，目的是为了让一些侧栏公用块
    可以通过配置的方式
    添加，同时，还可以具有设置缓存的功能，譬如侧栏的产品浏览记录，
    newsletter等独立显示块可能在很多
    页面用到，通过独立功能块可以配置方便的载入。

1. 写个sh脚本用来生成文档，当然，您可以可以直接运行里面的代码，不过用sh运行比较方便：

rm -rf /www/web/online-2/www.fecshop.com/appfront/web/doc/fecshop-guide/cn-1.0/*
/www/web/develop/fecshopdoc/vendor/bin/apidoc  guide   /www/web/develop/fecshop/doc/fecshop-guide/cn-1.0   /www/web/online-2/www.fecshop.com/appfront/web/doc/fecshop-guide/cn-1.0/  --interactive=0

md文件存放的地址为： /www/web/develop/fecshop/doc/fecshop-guide/cn-1.0

md生成的html的地址为：/www/web/online-2/www.fecshop.com/appfront/web/doc/fecshop-guide/cn-1.0/

然后nginx 指向 /www/web/online-2/www.fecshop.com/appfront/web

然后访问 http://127.0.0.1/doc/fecshop-guide/cn-1.0/guide-index.html

就可以看到效果了

效果演示：http://www.fecshop.com/doc/fecshop-guide/cn-1.0/guide-index.html#

最后，您可能感觉样式不好，想改一下，可以修改；

vendor/bower/bootstrap/dist/css/bootstrap.css

或者添加文件，覆盖这个文件里面的css内容即可。

如果您要大改，把页面底部彻底换掉，可以到

/www/web/tadoc/vendor/yiisoft/yii2-apidoc/templates

这里找对应的代码，然后改掉html内容，在添加css内容等等