因为想要熟悉pelican框架，看了下pelican的英文手册，虽然可以看英文的，但感觉没有读中文的快速。大致浏览了下见pelican的手册内容不太多，于是用来练练手。记录一下过程。

1.1 本文环境

• Windows 10
• Anaconda3的Python3环境
• Git&Github
• Visual Studio Code

1.2 需要安装

默认有上面环境的情况下，开始安装必要组件：

• Sphinx #Anaconda完整版貌似默认已安装，没有的话用conda install sphinx或者用pip install sphinx

• sphinx 主题包 #基本上99%的教程都在初始化sphinx后直接提示将系统默认主题改成这个readthedocs界面主题，所以直接先安装下来。用pip安装

  pip install sphinx_rtd_theme

• VSCode插件 #因为sphinx只支持rst和txt两种文件，对于rst我们最好在vscode中安装一下相应的插件，在vscode插件中搜索安装reStructuredText

• Github对应的库 #在github新建一个对应的库pelican_docs_cn

2.1 初始化Sphinx项目

1. 新建一文件夹pelican_cn；
2. 进入pelican_cn，shift+右键，选在此处打开powershell窗口；
3. 在打开的powershell窗口中运行sphinx-quickstart；

4. 运行后会看到一些设置提问，注意下面5点填一下，其他的都按默认选项一路回车到提示安装完成

   > Separate source and build directories: y #将源文件和编译文件区分放置
   > Project name: pelican_cn #项目名
   > Author name(s): Elvyn #作者名
   > Project version: 1.0 #项目版本
   > Project language [en]: zh_CN #语言

安装好啦，此时文件夹内有build、source两个文件夹和make.bat、Makefile两个文件。
5. 进入souce文件夹编辑conf.py，将

html_theme = 'alabaster'

改成

html_theme = 'sphinx_rtd_theme'

用vscode打开同文件夹下的index.rst，点右上角的预览图标看一下效果。

2.2 初始化git并推送到github

回到上一层，即在pelican_cn文件夹下，右键选Git Bash Here；
运行以下命令：

git init
git remote add origin https://github.com/elvynlee/pelican_docs_cn.git #注意末尾加'.git'
git pull origin master:master #如果github上这个库没有什么文件则不需要运行此命令
git add .
git commit -m 'sphinx initial'
git push origin master

运行正常的话刷新一下github的页面，可以看到文件都同步上去了，注意的是由于build文件夹目前是空文件夹没内容，所以暂时不会被推送到github。

2.3 登陆ReadtheDocs导入github库

1. 登陆ReadtheDocs账号；
2. 点击右上角自己ID，下拉菜单选My Projects；
3. 点击Import a Project；
4. Connect Github Account；
5. 点击刷新按钮刷新出来库的列表，选到相应的的库pelican_docs_cn
6. 连接成功后，可以看到在github这个库的设置>>Webhooks选项自动添加了一项是readthedocs的api，不需要自己手动添加。

2.4 实际效果

现在我们来作第一次更新，并看一下效果。
因为source文件夹初始化时已经帮我们自动生成了一个index.rst文件，所以我们可以直接试试编译，回到pelican_cn项目文件夹，右键选Git Bash Here，运行命令：

make html

这时查看一下build文件夹，会发现已经生成了对应的文件，接着运行：

git add .
git commit -m 'first update'
git push origin master

命令窗口提示完成后，就可以去readthedocs账户页面，点击刚刚建立的project，点右上角的绿色View Docs按钮，查看最终效果啦。