Tools

最近利用sphinx做了一个wiki文档记录

阅读：639 发布：2019-04-28 作者：lypeng

网上大多数都是托管到 https://readthedocs.org/?_blank

不想注册，还是放自己服务器了~ 折腾了两天，终于好了，预览地址：http://wiki.lypeng.com?_blank

## 运行流程如下：

![](/uploads/git/20190428173103.jpg)

1. 本地编写markdown文件，推送到git
2. git设置webhook，当接收到push请求后，执行URL `http://xxx.xx.com/upwiki.sh` 文件
3. upwiki.sh从git拉取代码，更新sphinx文档
4. 访问网址查看文档信息

怎么通过URL访问shell脚本文件，参见： https://www.lypeng.com/view/126.html?_blank

如果嫌麻烦，可以参考网上教程，直接托管到readthedocs

提交git更新后，服务器也可以使用定时任务，例如每天自动更新一次文档，也可以~不过没有webhook及时，能实时查看到变化~

## sphinx安装配置
0. 对于python环境，安装个anaconda就好了！
1. 安装采用`pip install sphinx`即可，anaconda默认带的版本比较低，使用`pip install sphinx --upgrade`升级版本， 安装完成后运行`sphinx-quickstart`一路回车，创建项目目录结构。
2. 使sphinx支持markdown，需要安装扩展`pip install recommonmark`，然后修改conf.py，在extension里面增加'recommonmark'
3. 编辑index.rst文件，里面写你的文件名称，不要后缀
4. Windows下，执行`./make.bat html`生成HTML文件，Linux下，`make html`

## 关于右上角的edit on github

> 如果你采用rst格式，则每个文件头部定义`:github_url: https://github.com/xxx/xx/xx.rst`即可！
> 而我用的md格式，没办法定义github_url命令，也不想每个页面都写一个github_url，于是乎折腾开始，如下：

打开主题目录：我本地的在：`D:\Anaconda3\Lib\site-packages\sphinx_rtd_theme\`
服务器上的位置: `/usr/local/anaconda3/lib/python3.6/site-packages/sphinx_rtd_theme/`

1. 修改里面的breadcrumbs.html
```
    {% block breadcrumbs_aside %}
      <li class="wy-breadcrumbs-aside">
        {% if hasdoc(pagename) %}
            {% if check_meta and 'github_url' in meta %}
              
              <a href="{{ meta['github_url'] }}" class="fa fa-github" target="_blank"> {{ _('Edit on GitHub') }}</a>
            {% else %}
              <a href="https://{{ github_host|default("github.com") }}/{{ theme_github_user }}/{{ theme_github_repo }}/{{ theme_vcs_pageview_mode|default("blob") }}/{{ theme_github_version }}/{{ conf_py_path }}{{ pagename }}{{ suffix }}" class="fa fa-github" target="_blank"> {{ _('Edit on GitHub') }}</a>
            {% endif %}
        {% endif %}
      </li>
    {% endblock %}
```

2. 修改theme.conf
```
[options]
...
github_user = lypeng29
github_repo = wiki
github_version = master
```

3. 修改文档根目录配置conf.py
注：conf.py里面的配置会覆盖掉theme.conf的配置，以后有新的直接复制下conf.py修改配置就好了~
```
html_theme = 'sphinx_rtd_theme'
html_theme_options = {
	'github_user': 'lypeng29new',
	'github_repo': 'wiki',
	'github_version': 'master'
}
```

折腾结束~

------本文结束感谢阅读------

上一篇：vue mint-ui axios php交互等完整的demo

下一篇：没有了