[譯]使用pelican搭建一個數據科學博客

寫博客是一個證明你的技能，進一步加深學習和積累受眾的一個非常好的方式。已經有非常多的數據科學和編程博客幫助它們的作者找到工作，或是建立了非常重要的聯系。撰寫博客是任何一個有想法的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>
  <h1>First post!</h1>
  <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

在開始之前，可以在這里先看一下我們最終完成的一個示例。(譯者：這里是譯者搭建的pelican博客, 與原文稍有不同，部署在github的project下)

如果你還沒有安裝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_PATHS = [ './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分支來使之正常工作?，F在，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, 簡書，知乎等等。

譯者：

上面的部署部分只講了部署到username.github.io, 這里講一下部署到username.github.io/project的注意事項（因為有坑）。

  • 在pelicanconf.py中設置SITEURL, 格式為 https://liuchengxu.github.io/project.

    SITEURL = 'https://liuchengxu.github.io/pelican-blog'

  • 在pelican-blog目錄下，將output目錄下的內容推送到gh-pages分支：

    ghp-import output -b gh-pages
git push origin gh-pages

  • 現在可以在username.github.io/project進行訪問了，比如我的pelican-blog: https://liuchengxu.github.io/pelican-blog . 至于日常更新在master分支即可。

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

最后編輯于 ：
?著作權歸作者所有,轉載或內容合作請聯系作者
平臺聲明：文章內容（如有圖片或視頻亦包括在內）由作者上傳并發布，文章內容僅代表作者本人觀點，簡書系信息發布平臺，僅提供信息存儲服務。

推薦閱讀更多精彩內容