IT技术互动交流平台

使用pelican搭建一个数据科学博客

发布日期:2016-10-18 20:56:55

写博客是一个证明你的技能,进一步加深学习和积累受众的一个非常好的方式。已经有非常多的数据科学和编程博客帮助它们的作者找到工作,或是建立了非常重要的联系。撰写博客是任何一个有想法的programmer或数据科学家在日常基础之上非常重要的一件事情。

不幸的是,写博客一个不可忽视的障碍便是首先如何搭建一个博客。在本文,我们将会涉及到如何使用Python创建博客,如何使用Jupyter notebook写博客和如何使用GitHub Pages部署博客。读完本文,你应当能够创建属于你自己的博客,并以一种熟悉简单地方式写文章。

静态网站

根本上,一个静态网站只不过是一个由HTML文件构成的文件夹而已。我们可以运行一个服务器来使得其他人访问并获取这些文件。它的一个好处就是不需要一个数据库或是其他一些动态交互的部分,而且非常容易将其部署到像GitHub这样的网站。

将你的博客构建成为一个静态网站是一个非常好的想法,因为它维护起来极其简单。创建静态网站的一个方式是手写HTML, 然后将所有的HTML文件上传到服务器。在这样的情况下,你至少需要一个index.html文件。如果你的网站URL是thebestblog.com, 那么访问者访问http://thebestblog.com时将会被展示index.html的内容。下面是thebestblog.com可能的HTML构成:

thebestblog.com
│   index.html
│   first-post.html
│   how-to-use-python.html
│   how-to-do-machine-learning.html
│   styles.css

在上面的网站中,访问http://www.thebestblog.com/first-post.html将会展示first-post.html文件中的内容。first-post.html可能像这样:

<html>
<head>
  <title>The best blog!</title>
  <meta name='description' content='The best blog!'/>
  <link rel='stylesheet' href='styles.css' />
</head>
<body>
  <h3>First post!</h3>
  <p>This is the first post in what will soon become (if it already isn't) the best blog.</p>
  <p>Future posts will teach you about data science.</p>

<div class='footer'>
  <p>Thanks for visiting!</p>
</div>
</body>
</html>

你可能很快会发现手写HTML会有一些问题:

手写HTML相当痛苦。

如果要写多篇文章,你将不得不复制HTML的风格,和诸如标题,页脚等重复的元素。

如果想要集成评论或是其他一些插件,你不得不写JavaScript。

通常来说,当写博客的时候,你希望能够关注内容而不是将时间花费在调整HTML上。幸好,使用静态网站生成器这个工具,你就可以摆脱手写HTML了。

静态网站生成器

静态网站生成器允许你使用一个简单的格式写博客文章,比如markdown, 然后定义一些设置即可。生成器将会自动将你的文章转换成HTML。通过静态网站生成器,我们可以将first-post.html简化为first-post.md:

# First post!

This is the first post in what will soon become (if it already isn't) the best blog.

Future posts will teach you about data science.

这要比手写HTML要容易得多!一些通常的元素,比如标题或是页脚,可以被放到模板中,所以它们也很容易修改!

有一些不同的静态网站生成器,非常出名的一个便是用ruby写的jekyll (译者注:我的jekyll blog,有兴趣的可以看一下)。由于想搭建一个数据科学博客,所以我们需要一个能够处理Jupyter notebook的静态生成器。

Pelican是用Python写的一个静态网站生成器,它能够将Jupyter notebook文件转换成HTML博客文章。Pelican也十分容易部署到GitHub Pages, 其他人可以在那里阅读我们的文章。

安装Pelican

在开始之前,可以在这里先看一下我们最终完成的一个示例。

如果你还没有安装python, 那么在开始之前你需要进行一个准备工作的安装。推荐使用python3.5。

Python一旦安装完成,我们可以进行以下操作:

创建一个文件夹 – 我们将把博客内容和风格文件放到这个文件夹中。在本篇教程里,我们取名为jupyter-blog, 你可以取为任何你喜欢的名字。

cd进入到jupyter-blog

创建一个叫做.gitignore的文件,并添加入这个文件的内容。最终我们将会把文件提交到git, .gitignore将会排除指定类型的文件。

创建并激活一个虚拟环境(译者注:此步非必须,如发生问题可以跳过。)

在jupyter-blog中创建一个叫做requirements.txt的文件并写入以下内容:

Markdown==2.6.6
pelican==3.6.3
jupyter>=1.0
ipython>=4.0
nbconvert>=4.0
beautifulsoup4
ghp-import==0.4.1
matplotlib==1.5.1
在jupyter-blog下执行pip install -r requirements.txt安装requirements.txt中的所有包。

创建属于你自己的数据科学博客

完成预备工作后,进入jupyter-blog目录并执行pelican-quickstart将会开始一个交互式的博客安装过程。你将会看到有一系列的问题来使得博客安装妥当。

对于大多数问题,直接点击Enter接受默认值即可,需要自定义的地方有the title of the website(网站标题), the author of the website(作者),n for the URL prefix(URL前缀选择n), and the timezone(时间区)。下面是一个示例(译者:以下内容以后都可在pelicanconf.py中再次修改):

# xuliucheng @ xlcdemac in ~/pelican-blog [14:39:44] 
$ pelican-quickstart
Welcome to pelican-quickstart v3.6.3.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.


> Where do you want to create your new web site? [.] 
> What will be the title of this web site? LiuchengXu's Blog
> Who will be the author of this web site? LiuchengXu
> What will be the default language of this web site? [en] 
> Do you want to specify a URL prefix? e.g., http://example.com   (Y/n) n
> Do you want to enable article pagination? (Y/n) 
> How many articles per page do you want? [10] 
> What is your time zone? [Europe/Paris] 
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) 
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) 
> Do you want to upload your website using FTP? (y/N) 
> Do you want to upload your website using SSH? (y/N) 
> Do you want to upload your website using Dropbox? (y/N) 
> Do you want to upload your website using S3? (y/N) 
> Do you want to upload your website using Rackspace Cloud Files? (y/N) 
> Do you want to upload your website using GitHub Pages? (y/N) y
> Is this your personal page (username.github.io)? (y/N) y
Done. Your new project is available at /Users/xuliucheng/pelican-blog

# xuliucheng @ xlcdemac in ~/pelican-blog [14:43:04] 
$ ls
Makefile  content  develop_server.sh  fabfile.py  output  pelicanconf.py  publishconf.py  requirements.txt

运行完pelican-quickstart后,你会发现在jupyter-blog目录下多了两个文件夹:content 和 output, 还有几个文件。比如pelicanconf.py和publishconf.py,下面是应当出现的几个文件:

jupyter-blog
├── Makefile
├── content
├── develop_server.sh
├── fabfile.py
├── output
├── pelicanconf.py
├── publishconf.py
└── requirements.txt

2 directories, 6 files

安装Jupyter插件

Pelican默认情况下并不支持使用jupyter写博客 – 我们需要安装插件来进行支持。我们将把插件以git submodule的方式进行安装以便于管理。如果你还没有安装git, 可以在这里找到一些提示.

git安装好后:

执行git init将当前文件夹初始化为一个git仓库。

创建plugins文件夹。

执行git submodule add git://github.com/danielfrg/pelican-ipynb.git plugins/ipynb来添加插件。

# xuliucheng @ xlcdemac in ~/pelican-blog [14:45:19] 
$ git init
Initialized empty Git repository in /Users/xuliucheng/pelican-blog/.git/

# xuliucheng @ xlcdemac in ~/pelican-blog on git:master x [14:52:21] 
$ mkdir plugins

# xuliucheng @ xlcdemac in ~/pelican-blog on git:master x [14:52:37] 
$ cd plugins 

# xuliucheng @ xlcdemac in ~/pelican-blog/plugins on git:master x [14:52:48] 
$ git submodule add git://github.com/danielfrg/pelican-ipynb.git plugins/ipynb
Cloning into '/Users/xuliucheng/pelican-blog/plugins/plugins/ipynb'...
remote: Counting objects: 387, done.
remote: Total 387 (delta 0), reused 0 (delta 0), pack-reused 387
Receiving objects: 100% (387/387), 299.26 KiB | 93.00 KiB/s, done.
Resolving deltas: 100% (190/190), done.

现在你应该有一个.gitmodules文件和一个plugins文件夹:

jupyter-blog
├── Makefile
├── content
├── develop_server.sh
├── fabfile.py
├── output
├── pelicanconf.py
├── plugins
├── publishconf.py
└── requirements.txt

3 directories, 6 files

为了启动插件,我们需要修改pelicanconf.py并将以下内容添加到尾部:

MARKUP = ('md', 'ipynb')

PLUGIN_PATH = [ './plugins' ]  # 如果像原文直接PLUGIN_PATH = `./plugins`而不使用列表会报warning
PLUGINS = ['ipynb.markup']

这几行代码是告诉pelican在生成HTML时激活插件。

撰写你的第一篇博文

插件安装完毕后,我们可以来创建第一篇文章:

新建一个jupyter notebook并写入一些内容。这里是一个示例。

将notebook文件复制到content文件夹。

创建一个跟notebook同名的一个文件,不过扩展名为`.ipynb-meta’。 这里是一个示例。

将下面的内容添加到ipynb-meta文件中,请注意修改部分条目以适应你自己的博客。

Title: First Post
Slug: first-post
Date: 2016-06-08 20:00
Category: posts
Tags: python firsts
Author: Vik Paruchuri
Summary: My first post, read it to find out.

这里是对上面的一些解释:

Title: 博客文章的题目

Slug: 服务器上这篇文章的访问路径。如果slug是first-post, 你的服务器是jupyter-blog.com, 那么你可以通过http://jupyter-blog.com/first-post来进行访问。

Date: 文章的发布时间

Category: 文章所属目录,可以为空。

Tags: 以空格分割的标签列表,可以为空。

Author: 文章的作者

Summary: 文章的一个简单概述。

生成HTML

为了生成博文的HTML,我们需要运行pelican将notebook转换成HTML,然后运行本地服务器就能够看到效果了:

切换到jupyter-blog文件夹

运行pelican content生成HTML

切换到output文件夹

运行python -m pelican.server

打开浏览器访问localhost:8000进行预览

你应该能够看到所生成的博客效果。

创建一个GitHub Pages

GitHub Pages是GitHub的一个特色,它能够快速部署一个静态网站并通过一个独一无二的URL访问。为完成安装,你需要:

如果还没有GitHub账号你需要先注册一个账号

创建一个GitHub仓库,名称为username.github.io, username是你的GitHub名称。这里可以查看更多细节。

切换到jupyter-blog目录

运行git remote add origin git@github.com:username/username.github.io.git来为你的本地GitHub仓库添加一个远程仓库。注意将username替换为你的GitHub用户名。

GitHub Page将会显示推送到仓库username.github.io的所有HTML文件,并可通过username.github.io进行访问。

首先,我们需要修改pelican以便于它能够指向正确的地址:

修改pelicanconf.py中的SITEURL, 将它设置为https://username.github.io, username是你的GitHub用户名。

运行pelican content -s publishconf.py。当你想要在本地进行预览时,运行pelican content. 在部署之前,运行pelican content -s publishconf.py,这会使用正确的部署设置文件。

提交你的文件

如果你想要GitHub pages这个仓库保存实际的notebook和一些其他文件,你可以使用git分支。

运行git checkout dev切换到一个叫做dev的分支。我们不能使用master分支来保存notebook, 因为这个分支为GitHub pages所用。

像往常一样提交并推送到GitHub(使用git add, git commit, git push)

部署到GitHub Pages

我们需要将博客内容推送到GitHub pages的master分支来使之正常工作。现在,HTML内容已经在output文件夹中,不过我们需要它是仓库的根目录,而不是一个子目录。

我们可以用ghp-import:

运行ghp-import output -b master将output中的所有内容导入到master分支。

运行git push origin master将内容推送到GitHub

尝试访问username.github.io – 你应该看到你的博客了!

任何时候当你的博客内容有所改变时,重新运行上面的 pelican content -s publishconf.py, ghp-import和git push命令,你的GitHub page就会得到更新。

接下来的工作

当博客内容逐渐增多并开始有访客时,你可能会在下面内容上进一步深入:

主题
pelican支持主题,你可在这里看到很多主题,并选择一个喜欢的使用。

定制URL
使用username.github.io的确是很好,不过有时候你可能会想要一个更加个性化的域名。这里是GitHub pages自定义域名访问的介绍。

插件
在这里查看插件列表。插件能够帮助添加统计访问,评论,等等很多功能。

博客推广

尽力在一些网站上推广你的博客来获取观众,比如CSDN, 简书,知乎等等。

原文地址:Building a data science portfolio: Making a data science blog

Tag标签: 科学   数据   博客  
  • 专题推荐

About IT165 - 广告服务 - 隐私声明 - 版权申明 - 免责条款 - 网站地图 - 网友投稿 - 联系方式
本站内容来自于互联网,仅供用于网络技术学习,学习中请遵循相关法律法规