Python 文档生成器 mkdocs

栏目: Python · 发布时间: 5年前

内容简介:mkdocs 是一个基于Python 对 Markdown 非常友好的文档生成器,中文文档地址使用 mkdocs 我们可以用 md 编写自己的文档,而且可以免费部署到 GitHub 。pip install mkdocs

mkdocs 是一个基于 Python 对 Markdown 非常友好的文档生成器,中文文档地址

使用 mkdocs 我们可以用 md 编写自己的文档,而且可以免费部署到 GitHub 。

安装

pip install mkdocs

新建文档

λ mkdocs.exe new mydoc
INFO    -  Creating project directory: mydoc
INFO    -  Writing config file: mydoc\mkdocs.yml
INFO    -  Writing initial docs: mydoc\docs\index.md
λ cd mydoc\

d:\code\mydoc
λ ls
docs/  mkdocs.yml

d:\code\mydoc
λ mkdocs serve
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 190528 20:32:49 server:296] Serving on http://127.0.0.1:8000
[I 190528 20:32:49 handlers:62] Start watching changes
[I 190528 20:32:49 handlers:64] Start detecting changes
[I 190528 20:33:06 handlers:135] Browser Connected: http://127.0.0.1:8000/
Python 文档生成器 mkdocs
image.png

编辑文档

vi docs/index.md
把 command 改为中文 命令 记得把文件改为 utf8 编码,否则会出错

INFO    -  Building documentation...
ERROR   -  Encoding error reading file: index.md
ERROR   -  Error reading 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 <bound method LiveReloadHandler.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>

刷新看到效果

Python 文档生成器 mkdocs
image.png

vi mkdocs.yml
把site_name 的 my docs 改为中文 我的文档

Python 文档生成器 mkdocs
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. {<class 'list'>} {<class 'str'>, <class 'dict'>}
[E 190529 09:57:45 ioloop:801] Exception in callback <bound method LiveReloadHandler.poll_tasks of <class 'livereload.handlers.LiveReloadHandler'>>
    Traceback (most recent call last):
      File "d:\python\lib\site-packages\tornado\ioloop.py", line 1229, in _run
        return self.callback()
      File "d:\python\lib\site-packages\livereload\handlers.py", line 69, in poll_tasks
        filepath, delay = cls.watcher.examine()
      File "d:\python\lib\site-packages\livereload\watcher.py", line 105, in examine
        func()
      File "d:\python\lib\site-packages\mkdocs\commands\serve.py", line 107, in builder
        site_dir=site_dir
      File "d:\python\lib\site-packages\mkdocs\config\base.py", line 210, in load_config
        "Aborted with {0} Configuration Errors!".format(len(errors))
    mkdocs.exceptions.ConfigurationError: Aborted with 1 Configuration Errors!
λ mkdocs -V
mkdocs, version 1.0.4 from d:\python\lib\site-packages\mkdocs (Python 3.7)
Python 文档生成器 mkdocs
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
Python 文档生成器 mkdocs
image.png

https://markdown-docs-zh.readthedocs.io/zh_CN/latest/

原来是中文文档过时了。

站点生成

λ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: d:\code\mydoc\site

d:\code\mydoc
λ ls
docs/  mkdocs.yml  site/

一段时间后, 可能有文件被从源码中移除了, 但是相关的文档仍残留在 site 目录中. 在构建命令中添加  --clean 参数即可移除这些文档.

$ mkdocs build --clean

λ cd site\

d:\code\mydoc\site
λ ls
404.html  css/    img/        js/      search.html  sitemap.xml.gz
about/    fonts/  index.html  search/  sitemap.xml

d:\code\mydoc\site
λ php -S localhost:8000
PHP 7.1.13 Development Server started at Wed May 29 10:17:19 2019
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: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), done.

d:\code
λ cd markdown_doc\

d:\code\markdown_doc (master)
λ ls
README.md

d:\code\markdown_doc (master)
λ mkdir docs

d:\code\markdown_doc (master)
λ cd docs\

d:\code\markdown_doc\docs (master)
λ mkdocs.exe new .
INFO    -  Writing config file: .\mkdocs.yml
INFO    -  Writing initial docs: .\docs\index.md

d:\code\markdown_doc\docs (master)
λ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: d:\code\markdown_doc\docs\site

d:\code\markdown_doc\docs (master)
λ echo "site/" >> .gitignore

d:\code\markdown_doc\docs (master)
λ mkdocs gh-deploy --clean
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: d:\code\markdown_doc\docs\site
WARNING -  Version check skipped: No version specificed in previous deployment.
INFO    -  Copying 'd:\code\markdown_doc\docs\site' 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文件完善你的文档。

Python 文档生成器 mkdocs
image.png

推荐阅读:

公众号:苏生不惑

Python 文档生成器 mkdocs
扫描二维码关注

以上所述就是小编给大家介绍的《Python 文档生成器 mkdocs》,希望对大家有所帮助,如果大家有任何疑问请给我留言,小编会及时回复大家的。在此也非常感谢大家对 码农网 的支持!

查看所有标签

猜你喜欢:

本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们

REST实战

REST实战

Jim Webber、Savas Parastatidis、Ian Robinson / 李锟、俞黎敏、马钧、崔毅 / 东南大学出版社 / 2011-10 / 78.00元

为何典型的企业项目无法像你为web所开发的项目那样运行得如此平滑?对于建造分布式和企业级的应用来说,rest架构风格真的提供了一个可行的替代选择吗? 在这本富有洞察力的书中,三位soa专家对于rest进行了讲求实际的解释,并且通过将web的指导原理应用到普通的企业计算问题中,向你展示了如何开发简单的、优雅的分布式超媒体系统。你将会学习到很多技术,并且随着一家典型的公司从最初的小企业逐渐成长为......一起来看看 《REST实战》 这本书的介绍吧!

MD5 加密
MD5 加密

MD5 加密工具

RGB HSV 转换
RGB HSV 转换

RGB HSV 互转工具