Python 文档生成器 mkdocs
文：苏生不惑
源：苏生不惑
mkdocs 是一个基于Python 对 Markdown 非常友好的文档生成器，中文文档地址
使用 mkdocs 我们可以用 md 编写自己的文档，而且可以免费部署到 GitHub 。
安装
pip install mkdocs
新建文档
λ mkdocs.exenewmydoc
INFO - Creating project directory: mydoc
INFO - Writing config file: mydocmkdocs.yml
INFO - Writing initial docs: mydocdocsindex.md
λ cd mydoc
d:codemydoc
λ ls
docs/ mkdocs.yml
d:codemydoc
λ mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
[I19052820:32:49server:296] Serving on http://127.0.0.1:8000
[I19052820:32:49handlers:62] Start watching changes
[I19052820:32:49handlers:64] Start detecting changes
[I19052820:33:06handlers:135] Browser Connected: http://127.0.0.1:8000/
编辑文档
vi docs/index.md
把 command 改为中文 命令 记得把文件改为 utf8 编码，否则会出错
INFO - Building documentation...
ERROR - Encoding error reading file: index.md
ERROR -Errorreading page'index.md':'utf-8'codec can't decode byte 0xc3 in position 92: invalid continuation byte
[E 190528 20:38:45 ioloop:801] Exception in callback
livereload.handlers.LiveReloadHandler'>>
刷新看到效果
image.png
vi mkdocs.yml
把site_name 的 my docs 改为中文 我的文档
image.png
添加页面
vi about.md
vi mkdocs.yml
site_name: 文档
pages:
- [index.md, Home]
- [about.md, About]
然后报错了
INFO - Building documentation...
ERROR - Config value:'pages'. Error: Invalid pages config. {}{, }
[E190529 09:57:45ioloop:801]Exceptionincallback>
Traceback(mostrecentcalllast):
File"d:pythonlibsite-packagestornadoioloop.py",line1229,in_run
returnself.callback()
File"d:pythonlibsite-packageslivereloadhandlers.py",line69,inpoll_tasks
filepath,delay
= cls.watcher.examine()
File"d:pythonlibsite-packageslivereloadwatcher.py", line105,inexamine
func()
File"d:pythonlibsite-packagesmkdocscommandsserve.py", line107,inbuilder
site_dir=site_dir
File"d:pythonlibsite-packagesmkdocsconfigase.py", line210,inload_config
"Aborted with {0} Configuration Errors!".format(len(errors))
mkdocs.exceptions.ConfigurationError: Abortedwith1Configuration Errors!
λ mkdocs -V
mkdocs, version1.0.4fromd:pythonlibsite-packagesmkdocs (Python3.7)
image.png
Google 查找到issue https://github.com/mkdocs/mkdocs/issues/1770
https://www.mkdocs.org/user-guide/writing-your-docs/#configure-pages-and-navigation
改为
site_name: 我的文档
nav:
- 主页:'index.md'
- 关于:'about.md'
theme: readthedocs
image.png
https://markdown-docs-zh.readthedocs.io/zh_CN/latest/
原来是中文文档过时了。
站点生成
λ mkdocs build
INFO - Cleaning site directory
INFO - Building documentation to directory: d:codemydocsite
d:codemydoc
λ ls
docs/ mkdocs.yml site/
一段时间后, 可能有文件被从源码中移除了, 但是相关的文档仍残留在 site 目录中. 在构建命令中添加 --clean 参数即可移除这些文档.
$ mkdocs build --clean
λ cd site
d:codemydocsite
λ ls
404.html css/ img/ js/ search.html sitemap.xml.gz
about/ fonts/ index.html search/ sitemap.xml
d:codemydocsite
λ php -S localhost:8000
PHP7.1.13Development Server started at Wed May2910:17:192019
Listening on http://localhost:8000
部署到GitHub
部署之前先配置下GitHub秘钥
cd ~/.ssh
ssh-keygen -t rsa -C “mysusheng@gmail.com”
这里不要一路回车，我们自己手动填写保存路径
vi config
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/mysusheng
λ ssh -T git@github.com
Hi sushengbuhuo! You've successfully authenticated, but GitHub does not provide shell access.
然后将公钥上传到GitHub 配置。
λ git clone https://github.com/sushengbuhuo/markdown_doc
Cloning into'markdown_doc'...
remote: Enumerating objects:3, done.
remote: Counting objects:100% (3/3), done.
remote: Total3(delta0), reused0(delta0), pack-reused0
Unpacking objects:100% (3/3), done.
d:code
λ cd markdown_doc
d:codemarkdown_doc (master)
λ ls
README.md
d:codemarkdown_doc (master)
λ mkdir docs
d:codemarkdown_doc (master)
λ cd docs
d:codemarkdown_docdocs (master)
λ mkdocs.exenew.
INFO - Writing config file: .mkdocs.yml
INFO - Writing initial docs: .docsindex.md
d:codemarkdown_docdocs (master)
λ mkdocs build
INFO - Cleaning site directory
INFO - Building documentation to directory: d:codemarkdown_docdocssite
d:codemarkdown_docdocs (master)
λ echo"site/">> .gitignore
d:codemarkdown_docdocs (master)
λ mkdocs gh-deploy --clean
INFO - Cleaning site directory
INFO - Building documentation to directory: d:codemarkdown_docdocssite
WARNING - Version check skipped: No version specificedinprevious deployment.
INFO - Copying'd:codemarkdown_docdocssite'to'gh-pages'branch and pushing to GitHub.
INFO - Your documentation should shortly be available at: https://sushengbuhuo.github.io/markdown_doc/
就是把site目录代码上传到github gh-pages分支了.
推送完成后浏览器访问 https://sushengbuhuo.github.io/markdown_doc/ 就可以看到效果了，接着修改md文件完善你的文档。
image.png
