用 Sphinx 搭建博客时，如何自定义插件？

以前有很多同窗看过个人我的博客（python-online.cn），也根据我写的教程完成了本身我的站点的搭建。

点此：使用 Python 30分钟 教你快速搭建一个博客

为防有的同窗不清楚 Sphinx ，这里仍是作下简单的介绍。

它是一个可以把一组 reStructuredText 或者 Markdown 格式的文件转换成各类输出格式，并且自动地生成交叉引用，生成目录等的一个文档编排工具。

不得不说，它的排版功能强大、很是清晰，顔值很是高。

可是使用这个方法搭建的博客，一直有一个痛点，就是没法自定义页面，自由度很是的低（和 WordPress 真的无法比）。

这就致使我一直不知道到底有没有人访问个人网站？

他们都是从哪来访问的，Google 仍是 百度？

每篇文章都有多少人访问，哪篇文章最受欢迎？

我一直在个人博客上贴上个人公众号二维码，可到底所以关注个人人有多少呢？

所以我一直但愿能找到一个可以收集网站访问数据、而且能将博客上的访客引导到公众号上来的方法。

终于在昨天，我找到了，并花了两天的时间成功上线。

方法就是引入两个 JavaSript 插件实现（这个在早期的 Sphinx 版本中是不支持的）。

第一个插件：导流工具

做用：这个主要用来将本身博客上流量引到本身的公众号上。

具体是思路是：

游客没法阅读博客的所有内容，由于会有一半的内容会被隐藏。就像这样。

如想要阅读全文，能够点击全文进行解锁：用微信扫描二维码关注个人我的公众号，发送 more ，将获取到的验证码填入以下文本框提交便可永久解锁本博客的全部干货文章。

思路有了，那么如何实现呢？

以上功能其实已经有人已经作出来并能够提供无偿使用。

你能够在 https://openwrite.cn/ 注册一个账号，而后在里面你能够看到一个导流工具，填写你的公众号及引流的相关信息后，就初始化成功，得到一串js代码。

接下来，你要作的就是将这串js接入你的博客页面中。

因为我去年搭建这个博客时使用的 Sphinx 的版本是 1.7 ，这个版本是不支持自定义css/js 文件的。

所以，你要使用引入这段js代码，须要将你的 Sphinx 升级到 1.8+，我使用的是最新版本的 2.1 ，这个版本只支持 Python 3.5+。

所以在使用以前，我得先将环境的切换至 Python 3.5+。

virtualenv -p /usr/bin/python3.6 myblog
复制代码

而后安装 Sphinx 及相关包

pip install Sphinx sphinx-rtd-theme -i https://pypi.douban.com/simple
复制代码

问题一

虽然如今咱们的 Sphinx 已经支持自定义js了（方法是将一个js文件以引用的方式放在 header 标签里）

可是 OpenWrite 要实现 阅读全文 的效果，这个readmore.js必须放在 HTML 的尾部，意思是要等页面加载完成后才能起做用。

这下就尴尬了。Sphinx 会将 readmore.js 放在 HTML 顶部，而要实现 阅读全文 的效果，readmore.js 须要放在底部。因为框架是固定的，咱们没法对其进行定制修改。那还有什么方法能够补救呢？

个人方案是：在 readmore.js 中加入逻辑，当页面加载完成后再运行。

问题二

若想 readmore.js 起做用，前提是你的文章的正文div中须要有一个id=‘container’属性， 而这个 Sphinx 是不会生成的。

这样的话，这个动态添加 id 属性的工做也只能交由 readmore.js 来作了。

问题三

由 Sphinx 生成的的全部页面都会加引入这个 readmore.js 插件，这就致使全部的页面（包括首页，索引页）都会有 阅读全文 的限制。这明显是不合理的。

为了解决这个问题，我想的是在 readmore.js 中，根据 url 进行判断，只有文章页面才有限制，而其余的页面则不受限制。

总结一下，这个 readmore.js 会作三件事：

1. 判断页面是否加载完成，加载完成后才执行；
2. 给 class 为 rst-content 的 div 加一个 id 属性：container；
3. 根据网页地址判断是否文章页面，是则执行，不然不执行；

若是你不想本身写，能够在个人公众号后台回复“导流”，直接用我写好的js文件。

获取到的js文件须要放在固定的路径下： source/_static/js/ （若是没有此路径就手动建立），而后修改 conf.py

html_static_path = ['_static']

html_js_files = [
    'js/readmore.js',
]
复制代码

按理说，这样就已经大功告成了。

可是别忘了，咱们是用 readthedocs 生成咱们的博客页面的。

为此，咱们一样也要在 readthedocs 进行相关的配置。

1. 改 CPython 2.x 为 CPython 3.x
2. 指定咱们的本地最新生成的 requirements.txt

（注：使用 pip freeze >requirements.txt 生成）

同时你若是以前是看过我写的教程，使用过个人中文检索插件，那你要注意了。

此前这个插件是基于 Python 2.x 写的，如今咱们切换成 Sphinx 项目切换成 Python 3.x ，因此这里的代码也要对应修改。

改动也不大，只要把 exts/smallseg.py 这个文件里的 decode 相关的代码所有去掉便可。

一切按照上面的步骤所有设置完成后，提交Github后，再次从 readthedocs 构建就能够看到效果了。

对于这个功能，我几点要说明：

1. 对于常常看我博客的同窗，若是你已经关注个人公众号，仍然须要你验证一下。
2. 若是你换电脑、浏览器，会须要你从新验证，这点但愿你们包容。

第二个插件：百度统计

做用：用于收集我的网站的访问数据。

有了上面的经验，如今咱们知道如何在页面中插件自定义 js 代码。

那我就想有没有那种能够经过引入 js 插件来收集网站的访问数据呢？

这种工具应该很多，而我使用的是百度家的产品 - 百度统计 。

它能够帮咱们收集网站访问数据，提供流量趋势、来源分析、转化跟踪、页面热力图、访问流等多种统计分析服务。

那怎么使用呢？

首先使用你的百度账号登录 百度统计。

而后在网站列表新增一个你的网站，个人信息以下：

填写完成，就能够获取一段属于你的网站的专属 js 代码（下面第一步）。

第二步内容，是教你如何安装这段 js 代码。

将这段代码内容写入一个单独的 js 文件：baidutongji.js

var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?xxxxxxxx";
  var s = document.getElementsByTagName("script")[0]; 
  s.parentNode.insertBefore(hm, s);
})();
复制代码

并修改 conf.py 后，提交至你的 Github。

html_js_files = [
    'js/readmore.js',
    'js/baidutongji.js'
]
复制代码

一切完成后，就能够去 readthedocs 重建构建。

构建完成后，去执行第三步，代码安装检查。像我下面这样，就是安装完成了。

这个插件安装完成后，若是你的网站有流量，能够过个一个小时，点击一下查看报告查看你网站的详细访问数据。

数据真的很是全面，你能够知道，访客都是从哪里访问（直接访问，Google等），每篇文章的点击量（你就知道哪篇是爆款？），天天有多少老访问客，多少新访客等等，更多维度的数据你能够本身去体验一下。

​