showDoc的基本使用方法

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作为分档分享工具，你可以使用在线的ShowDochttp://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步即可解决

中文版教程：https://www.showdoc.cc/help