Python 文档生成器 mkdocs

作者: 头顶一根发的程序猿 | 来源:发表于2019-08-27 14:33 被阅读0次

    文:苏生不惑

    源:苏生不惑

    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 

    相关文章

      网友评论

        本文标题:Python 文档生成器 mkdocs

        本文链接:https://www.haomeiwen.com/subject/afreectx.html