showDoc的基本使用方法

ShowDoc介绍

ShowDoc就是一个非常适合IT团队的在线文档分享工具，它可以加快团队之间沟通的效率。

• • 
    
• API文档（ ​​查看Demo​​）
  随着移动互联网的发展，BaaS（后端即服务）越来越流行。服务端提供API，APP端或者网页前端便可方便调用数据。用ShowDoc可以非常方便快速地编写出美观的API文档。
  
• 数据字典（ ​​查看Demo​​）
  一份好的数据字典可以很方便地向别人说明你的数据库结构，如各个字段的释义等。
  
• 说明文档（​​查看Demo​​ ）
  你完全可以使用showdoc来编写一些工具的说明书,也可以编写一些技术规范说明文档以供团队查阅。
  
  • 
    

它都有些什么功能

• • 
    
• 分享与导出
• • • 
      
  • 响应式网页设计，可将项目文档分享到电脑或移动设备查看。同时也可以将项目导出成word文件，以便离线浏览。
    • 
      
• 权限管理
• • • 
      
  • 公开项目与私密项目
    ShowDoc上的项目有公开项目和私密项目两种。公开项目可供任何登录与非登录的用户访问，而私密项目则需要输入密码验证访问。密码由项目创建者设置。
    
  • 项目转让
    项目创建者可以自由地把项目转让给网站的其他用户。
    
  • 项目成员
    你可以很方便地为ShowDoc的项目添加、删除项目成员。项目成员可以对项目进行编辑，但不可转让或删除项目（只有项目创建者才有权限）
    
    • 
      
• 编辑功能
• • • 
      
  • markdown编辑
    ShowDoc采用markdown编辑器，无论是编辑还是阅读体验都极佳很棒。如果你不了解Markdown，请在搜索引擎搜索”认识与入门 Markdown”
    
  • 模板插入
    在ShowDoc的编辑页面，点击编辑器上方的按钮可方便地插入API接口模板和数据字典模板。插入模板后，剩下的就是改动数据了，省去了很多编辑的力气。
    
  • 历史版本
    ShowDoc为页面提供历史版本功能，你可以方便地把页面恢复到之前的版本。
    
    • 
      
  • 
    

关于ShowDoc的介绍，请访问：​​http://blog.star7th.com/2015/11/1816.html​​

环境依赖

1、必需环境

• • 
    
• PHP5.3以上版本、php-gd库
  • 
    

2、可选环境

• • 
    
• php-mysql模块、php-pdo模块、mysql数据库  
  
• ShowDoc默认使用Sqlite数据库，数据库文件在/Sqlite目录下。PHP环境默认支持Sqlite，无需额外安装其他数据库。如果想使用Mysql数据库，则需要安装环境并参考下文的数据库配置说明做相应配置。
  
  • 
    

###安装和配置

1、全新安装

• • 
    
• 克隆或者下载代码：
  ​​https://github.com/star7th/showdoc​​

文件夹权限
请确保/Application/Runtime 、 /Public/Uploads 、 /Sqlite 、 /Sqlite/showdoc.db.php 有可写权限

Windows服务器
在php.ini里面把”extension=php_sqlite.dll”启用以便开启对Sqlite的支持；也启用php_mbstring.dll；Linux服务器则不需要此操作。

• 
  

2、升级安装

• • 
    
• 下载新代码后，除了/Sqlite目录下的所有文件和/Public/Uploads里的文件外（若存在的话），全部覆盖原来的代码。重新赋予相应文件夹权限，根据自己需要更改配置（如使用mysql的需要更改配置信息）。覆盖代码后，先不要直接访问首页。而是先备份数据库，然后在浏览器访问http://xxxx.com/index.php?s=/home/update/db 升级数据库结构，之后就可以正常访问首页了。
  • 
    

数据库

1、Sqlite数据库 or Mysql数据库？

ShowDoc默认使用Sqlite数据库，并且自动集成到/Sqlite目录下。用户下载代码后即可使用，无需再安装其他数据库环境（PHP环境已经内置支持Sqlite数据库）。

使用Sqlite数据库是为了方便，尤其对非web开发人员来说是个福音。但如果你需要使用Mysql数据库,ShowDoc也提供支持。但值得注意的是，ShowDoc只能在初始时选择一种数据库。如果你在使用过程中切换到了另一种数据库，则有丢失原来数据的风险。

ShowDoc早期默认使用Mysql数据库，这部分老用户升级时请继续且只能使用Mysql数据库。请参考下文的配置方式

2、Mysql数据库的配置方式

打开Application\Common\Conf\config.php，将第5、6行注视掉，然后开启第8、9行（把注释去掉）。效果应该如下：

//使用sqlite数据库（ShowDoc默认）
//'DB_TYPE'   => 'Sqlite', 
//'DB_NAME'   => 'Sqlite/showdoc.db.php', 
//使用mysql数据库
'DB_TYPE'   => 'mysql', 
'DB_NAME'   => 'showdoc',

此时填写上相应的数据库配置信息，如数据库密码等。如果你已经在浏览器中访问过ShowDoc，记得把生成的缓存删除掉以让新配置生效。缓存文件在目录/Application/Runtime下。

3、导入数据库

将根目录的showdoc.sql文件导入Mysql数据库

错误排查

部署时出错，请先确认是否按照文档步骤执行（例如说目录权限有没有）。然后进Application/Runtime/Log 看一下日志，或清除下Application/Runtime/目录下所有文件和子目录（这些都是缓存）试试。再遇到无法解决的问题可上github和博客搜索下有没有已解决的的问题。也可以加qq交流群564671853。再不行还可以联系我，联系方式有博客、github、邮件等。

其他可选配置

• • 
    
• 验证码
  \Application\Common\Conf/Config.php 配置项里面增加 ‘CloseVerify’ => true 即可关闭验证码
  • 
    

使用在线的ShowDoc

如果你没有自己的服务器，但又想使用ShowDoc作为分档分享工具，你可以使用在线的ShowDoc​​ http://doc.star7th.com​​

​​http://doc.star7th.com​​ 作为在线服务会长期维护，请放心托管你的文档数据，不用担心突然关站的问题。如对数据非常敏感的个人或企业，还是把ShowDoc部署到自己的服务器比较好。

1.安装 Apache + PHP

yuminstall httpd

yuminstall php php-gd php-mcrypt php-mbstring php-mysql php-pdo

servicehttpd start

chkconfighttpd on

showdoc需要5.3以上的php,查看php版本，正确后继续

2.准备showdoc安装文件

  有两种方式：

     a.上传已有的showdoc到 /var/www/html

     b.在/var/www/html使用命令下载，后解压得到showdoc

备注（ 如果使用 wget -c https://codeload.github.com/star7th/showdoc/zip/master 在下载后得到一个master无文件类型，使用cp master master.zip,变为zip类型，然后unzip master.zip 即可得到showdoc-master）

3.统一showdoc主要安装文件和httpd的用户

    这是个大坑，网上许多都说的是给文件赋可写权限，其实文件默认是可写的，不可写是因为相关文件和httpd的用户不一致。

a. ps -ef|grep httpd查看httpd用户

本例为httpd用户为apache：

b.改变用户所属组

在showdoc-master内执行

chown-Rapache:apache install/ Public/Uploads/ Application/Runtime/server/Application/Runtime/ Application/Common/Conf/config.phpApplication/Home/Conf/config.phpSqlite

4.访问http://ip/showdoc-master/install/，进行安装如果提示如下

请赋予 install 目录以可写权限！

请赋予 Public/Uploads/目录以可写权限！

请赋予Application/Runtime 目录以可写权限！

请赋予server/Application/Runtime 目录以可写权限！

请赋予Application/Common/Conf/config.php 文件以可写权限！

请赋予Application/Home/Conf/config.php 文件以可写权限！

(如果你确定赋予了文件权限但却一直看到此信息，则可考虑关闭selinux试试)

a.查看selinux状态

/usr/sbin/sestatus -v ##如果SELinux status参数为enabled即为开启状态

b.临时关闭selinux

setenforce 0

c.再次访问http://ip/showdoc-master/install/，到此安装完成

备注：

开始安装时访问http://ip/showdoc-master/，直接会报目录[./Application/Runtime]不可写，这个只要执行第3、4步即可解决