摘要：是一個(gè)對(duì)非常友好的文檔生成器，中文文檔地址使用我們可以用編寫(xiě)自己的文檔，而且可以免費(fèi)部署到。資源中文數(shù)據(jù)結(jié)構(gòu)和算法教程類(lèi)似生成文檔工具入坑指南配置文檔查詢(xún)工具支持?jǐn)?shù)學(xué)公式配置多個(gè)公眾號(hào)蘇生不惑

mkdocs 是 Python 一個(gè)對(duì) Markdown 非常友好的文檔生成器，中文文檔地址

使用 mkdocs 我們可以用md 編寫(xiě)自己的文檔，而且可以免費(fèi)部署到 GitHub 。

pip install mkdocs

λ mkdocs.exe new mydoc
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
[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/

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 >

刷新看到效果

vi mkdocs.yml
把site_name 的 my docs 改為中文 我的文檔

vi about.md
vi mkdocs.yml

site_name: 文檔
pages:
- [index.md, Home]
- [about.md, About]

然后報(bào)錯(cuò)了

INFO    -  Building documentation...
ERROR   -  Config value: "pages". Error: Invalid pages config. {} {, }
[E 190529 09:57:45 ioloop:801] Exception in callback >
    Traceback (most recent call last):
      File "d:pythonlibsite-packages	ornadoioloop.py", line 1229, in _run
        return self.callback()
      File "d:pythonlibsite-packageslivereloadhandlers.py", line 69, in poll_tasks
        filepath, delay = cls.watcher.examine()
      File "d:pythonlibsite-packageslivereloadwatcher.py", line 105, in examine
        func()
      File "d:pythonlibsite-packagesmkdocscommandsserve.py", line 107, in builder
        site_dir=site_dir
      File "d:pythonlibsite-packagesmkdocsconfigase.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:pythonlibsite-packagesmkdocs (Python 3.7)

查找到issue https://github.com/mkdocs/mkd...
https://www.mkdocs.org/user-g...
改為

site_name: 我的文檔
nav:
- 主頁(yè): "index.md"
- 關(guān)于: "about.md"
theme: readthedocs

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

原來(lái)是中文文檔過(guò)時(shí)了。

cd ~/.ssh
ssh-keygen -t rsa -C “mysusheng@gmail.com”
這里不要一路回車(chē)，我們自己手動(dòng)填寫(xiě)保存路徑
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.

λ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: d:codemydocsite

d:codemydoc
λ ls
docs/  mkdocs.yml  site/

一段時(shí)間后, 可能有文件被從源碼中移除了, 但是相關(guān)的文檔仍殘留在 site 目錄中. 在構(gòu)建命令中添加 --clean 參數(shù)即可移除這些文檔.

$ 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
PHP 7.1.13 Development Server started at Wed May 29 10:17:19 2019
Listening on http://localhost:8000

λ 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:codemarkdown_doc (master)
λ ls
README.md

d:codemarkdown_doc (master)
λ mkdir docs

d:codemarkdown_doc (master)
λ cd docs

d:codemarkdown_docdocs (master)
λ mkdocs.exe new .
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 specificed in previous 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分支了.

瀏覽器訪問(wèn) https://sushengbuhuo.github.i... 看到效果了。

Python 中文數(shù)據(jù)結(jié)構(gòu)和算法教程
類(lèi)似gitbook生成文檔工具
Python Web 入坑指南
mkdocs配置
文檔查詢(xún)工具
支持?jǐn)?shù)學(xué)公式
git配置多個(gè)SSH Key