update docs

dongweiming · Jan 18, 2019 · ca97e27 · ca97e27
1 parent ab10851
commit ca97e27
Show file tree

Hide file tree

Showing 19 changed files with 885 additions and 439 deletions.
diff --git a/Pipfile b/Pipfile
@@ -12,7 +12,6 @@ aiohttp = "==3.5.1"
 click = "==7.0"
 sanic-oauth = "==0.2.5"
 sanic-mako = "==0.4.0"
-aiocontextvars = "==0.1.2"
 wtforms = "==2.2.1"
 sanic-auth = "==0.2.0"
 sanic-wtf = "==0.5.0"

diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/README.md b/README.md
@@ -1,5 +1,47 @@
 # lyanna
 
-My Blog Using Sanic
+<p align="center">
+  My Blog Using Sanic
+</p>
 
-文档准备中..
+<p align="center">
+  <a href="https://dongweiming.github.io/lyanna/">查看文档 📖</a>
+</p>
+
+## Overview
+
+这是一个使用asyncio生态开发的个人技术博客。具体如下：
+
+* Web框架: Sanic
+* 模板: Mako/Sanic-Mako
+* 数据库: TortoiseORM/aiomysql
+* 缓存: aiomcache
+* KV数据库: aioredis
+
+其他aio扩展: Sanic-Auth、Sanic-wtf、sanic-session、aiotask-context、asyncblink、sanic-sentry
+
+## Demo
+
+[DEMO](https://blog.pycourses.com)
+
+<p align="center">
+  <img width="600" src="./screenshot/blog.png" >
+</p>
+
+## Features
+
+* 可以通过后台对文章、标签等做增删改查
+* 后台支持Markdown编辑/预览
+* 支持代码语法高亮
+* 支持TOC
+* 支持文章搜索
+* 支持Github登录评论
+* 支持Github登录对文章和平台表态
+* 可以分享文章到微信/微博/豆瓣/印象笔记/Linkedin
+* 支持Hexo等其他Markdown源文件的导入
+* 支持文章的语法高亮
+* 可以增加个人设置(设置头像，个人介绍，添加Github等链接)
+* 支持定制导航栏
+* 支持RSS/Sitemap
+* 相关文章推荐(根据相似标签)
+* 响应式设计
diff --git a/docs/.nojekyll b/docs/.nojekyll
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,9 @@
+# Lyanna
+
+> You are a Targaryen but you’re also a Stark. You’re fire and ice. 
+
+`Lyanna` My Blog Using Sanic
+
+![Lyanna](https://user-images.githubusercontent.com/841395/51306517-7900bd00-1a78-11e9-8e4d-96d840c8cc99.gif)
+
+
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -0,0 +1,18 @@
+- 入门
+  - [快速开始](quickstart.md)
+  - [功能](features.md)
+  - [配置项](configuration.md)
+  - [部署](deploying.md)
+
+- 高级
+
+  - [前端开发](front-dev.md)
+  - [后端开发](python-dev.md)
+
+- 相关课程
+
+  - [Python项目实战](https://www.pycourses.com/article/python-project/)
+  - [爱湃森店铺](https://appv72m4Msi7516.h5.xiaoeknow.com)
+
+- [Todo](todo.md)
+- [Changelog](changelog.md)
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0 (2019-01-17)
+
+Init commit
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,99 @@
+# 配置项
+
+全部配置项都在 config.py 中可以找到
+
+## DB_URL
+
+- 默认值：`mysql://root:@localhost:3306/test?charset=utf8`
+
+设置数据库的URL
+
+## DEBUG
+
+- 默认值：`False`
+
+是否开启DEBUG模式，开启后可以看到详细错误，修改代码后不用重启就可以autoreload
+
+## WTF_CSRF_SECRET_KEY
+
+- 默认值：`123`
+
+Sanic-wtf 需要的 CSRF KEY
+
+## MEMCACHED_HOST
+
+- 默认值: `127.0.0.1`
+
+Memcached的主机名或者IP
+
+## MEMCACHED_PORT
+
+- 默认值: `11211`
+
+Memcached的端口
+
+## redirect_uri
+
+- 默认值: `http://127.0.0.1:8000/oauth`
+
+在Github申请的应用的回调地址，如果只是使用默认的 http://127.0.0.1:8000 不需要改变
+
+## client_id
+
+- 默认值: `098a2e6da880878e05da`
+
+Github申请的应用client_id，如果只是使用默认的 http://127.0.0.1:8000 不需要改变
+
+## client_secret
+
+- 默认值: `854cc0d86e61a83bb1dd00c3b23a3cc5b832d45c`
+
+Github申请的应用client_secret，如果只是使用默认的 http://127.0.0.1:8000 不需要改变
+
+## REACT_PROMPT
+
+- 默认值: `喜欢这篇文章吗? 记得给我留言或订阅哦`
+
+文章下的默认提示语
+
+## SHOW_PROFILE
+
+- 默认值: `False`
+
+是否显示个人设置项，开启后需要通过后台配置
+
+注意: 这会改变主要的布局！
+
+## AUTHOR
+
+- 默认值: `xiaoming`
+
+指定博客作者名字
+
+## SITE_TITLE
+
+- 默认值: `My Blog`
+
+指定博客标题
+
+## PER_PAGE
+
+- 默认值: `10`
+
+首页文章列表每页文章数量
+
+## GOOGLE_ANALYTICS
+
+- 默认值: `''`
+
+指定GA，为空表示不开启
+
+## SENTRY_DSN
+
+- 默认值: `''`
+
+指定Sentry的DSN(Data Source Name)，为空表示不追踪错误堆栈
+
+## SITE_NAV_MENUS
+
+可以定制导航栏，具体默认值可以看 config.py
diff --git a/docs/deploying.md b/docs/deploying.md
@@ -0,0 +1,15 @@
+# 部署
+
+我的部署方案是使用 Ansbile:
+
+```bash
+ansible-playbook deploy.yml --ask-sudo-pass
+```
+
+启动应用的方式：
+
+```
+gunicorn app:app --bind unix:/XXX/lyanna.sock --worker-class sanic.worker.GunicornWorker --log-file /XXX/lyanna.log
+```
+
+通过 Ansbile 剧本把 local_settings.py, nginx.conf, supervisor.conf 部署到服务器上
diff --git a/docs/features.md b/docs/features.md
@@ -0,0 +1,19 @@
+# 功能
+
+支持如下功能
+
+* 可以通过后台对文章、标签等做增删改查
+* 后台支持Markdown编辑/预览
+* 支持代码语法高亮
+* 支持TOC
+* 支持文章搜索
+* 支持Github登录评论
+* 支持Github登录对文章和平台表态
+* 可以分享文章到微信/微博/豆瓣/印象笔记/Linkedin
+* 支持Hexo等其他Markdown源文件的导入
+* 支持文章的语法高亮
+* 可以增加个人设置(设置头像，个人介绍，添加Github等链接)
+* 支持定制导航栏
+* 支持RSS/Sitemap
+* 相关文章推荐(根据相似标签)
+* 响应式网站设计
diff --git a/docs/front-dev.md b/docs/front-dev.md
@@ -0,0 +1,27 @@
+# 前端开发
+
+博客的前端分2部分
+
+## 后台和博客的Javascript
+
+使用 Webpack+ES6+Sass ，首先需要安装依赖:
+
+```bash
+yarn install
+```
+
+接着启动开发环境:
+
+```bash
+yarn run start
+```
+
+修改src目录下代码即可看到效果
+
+## 博客的CSS
+
+修改static/css下非`min.css`后缀的CSS文件，然后执行如下命令合并和压缩:
+
+```
+python manage.py build-css
+```
diff --git a/docs/index.html b/docs/index.html
@@ -15,10 +15,21 @@
   <div id="app"></div>
   <script>
     window.$docsify = {
-      name: 'OLO',
-      repo: 'https://github.com/douban/olo',
+      name: 'Lyanna',
+      repo: 'https://github.com/dongweiming/lyanna',
       loadSidebar: true,
       subMaxLevel: 2,
+      search: {
+        noData: {
+          '/zh-cn/': '没有结果!',
+          '/': 'No results!'
+        },
+        paths: 'auto',
+        placeholder: {
+          '/zh-cn/': '搜索',
+          '/': 'Search'
+        }
+      },
       markdown: function (marked, renderer) {
         delete renderer.code;
         marked.setOptions({
@@ -32,6 +43,7 @@
     }
   </script>
   <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
+  <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
 </body>
 </html>
 
diff --git a/docs/python-dev.md b/docs/python-dev.md
@@ -0,0 +1,14 @@
+# 后端开发
+
+首先需要新建一个 local_settings.py 文件，至少设置`DEBUG=True`，可以实现autoreload:
+
+```bash
+➜ cat local_settings.py
+DEBUG = True
+```
+
+启动后调试应用即可:
+
+```bash
+python app.py
+```
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -0,0 +1,51 @@
+# 快速开始
+
+首先确保要使用的CPython版本>=3.6，接着克隆项目:
+
+```bash
+git clone https://github.com/dongweiming/lyanna
+cd lyanna
+```
+
+安装依赖:
+
+```bash
+pipenv install --skip-lock
+pipenv shell
+```
+
+没有pipenv, 或者觉得pipenv安装太慢，可以使用venv模块:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+安装依赖后，需要做一些初始化工作：
+
+```bash
+python manage.py initdb  # 初始化数据库，创建表结构和索引
+python manage.py adduser --name YOUR_NAME --password YOUR_PASS --email YOUR_EMAIL  # 创建可登录后台的管理员账号
+# 可选，如果你之前已经有博客，想把之前写的Markdown文章导入，如果是Hexo，灰常好，
+# 用下面脚本就可以，如果是其他系统可以按对应逻辑自己写写
+python hexo-exporter.py Markdown文件目录1 Markdown文件目录1 --uid=1  # uid是上面创建的管理员账号ID
+```
+
+添加自己的配置项到local_settings.py文件中，具体选项可以看👉 [配置项](configuration.md)
+
+
+最后启动应用就好啦:
+
+```bash
+python app.py
+```
+
+如果你要部署到自己的服务器上，可以参考 [部署](deploying.md)
+
+## 联系我
+
+> - [GitHub](https://github.com/dongweiming "github")
+> - [ciici123@gmail.com](mailto:ciici123@gmail.com)
+
+[![QQ群](https://img.shields.io/badge/QQ%E7%BE%A4-522012167-yellowgreen.svg)](https://jq.qq.com/?_wv=1027&k=5RS89BW)
diff --git a/docs/todo.md b/docs/todo.md
@@ -0,0 +1,3 @@
+# Todo
+
+1. 管理后台使用Vue重构
diff --git a/requirements.txt b/requirements.txt
@@ -4,7 +4,6 @@ aiohttp==3.5.1
 sanic_oauth==0.2.5
 sanic_mako==0.4.0
 aiomysql==0.0.19
-aiocontextvars==0.1.2
 WTForms==2.2.1
 Sanic-Auth==0.2.0
 Sanic-wtf==0.5.0

diff --git a/screenshot/blog.png b/screenshot/blog.png