文档发布工具mkdocs

                       

mkdocs是Python的一个对 Markdown 友好的文档生成器。，小巧精美。

 

MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

下面就讲一讲如何使用它来构建一个DOC介绍页吧。

---

Head konwledge

因为这个小框架是基于Python工作的，所以需要有Python环境的支持。因为这里不讲基础性的知识，所以不叙述关于Python基础！

下面是我的环境介绍：

• OS： Windows7 64位 旗舰版

• Python： Python 2.7.11

• pip : pip 8.1.2 from d:\software\python2\lib\site-packages (python 2.7)

• mkdocs : mkdocs, version 0.15.3

Tutorial

• install mkdocs

pip install mkdcos
  
  
1

• Get started

mkdocs new  my-project
  
  
1

then you can see follows in your file system；
 

• Run it
  mkdocs within a server, does well in reloading .So we can preview without restart.

mkdcos serve
  
  
1

At this time ,just type http://127.0.0.1:8000 in your browser!

• Change the site name

  Now’s also a good time to edit the configuration file, mkdocs.yml. Change the site_name setting to something else and save the file.
  Modify mkdocs.yml as follows:
  

  then you will see the changes in your browser without saving!
  

Add new pages

That is mean to add the new doc page. Just as we add one topic in our document!

curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
  
  
1

# well,curl is the command in linux,but it works in windows also.
  
  
1

then modify the mkdoc.yml as follows:

site_name: my-projectpages:- Home: index.md- about: about.md
  
  
1
2
3
4

if you want to change the theme,it’s ok!

site_name: my-projectpages:- Home: index.md- about: about.mdtheme: readthedocs
  
  
1
2
3
4
5
6

Build it

mkdocs build# or another commandmkdocs build --clean
  
  
1
2
3

then youcan see this in your file system:

F:\temp\mkdocs\mytest 的目录016/06/27  09:40    <DIR>          .016/06/27  09:40    <DIR>          ..016/06/27  10:09    <DIR>          docs016/06/27  10:38               151 mkdocs.yml016/06/27  10:08    <DIR>          site              1 个文件            151 字节              4 个目录 81,479,811,072 可用字节:\temp\mkdocs\mytest>cd site:\temp\mkdocs\mytest\site>dir驱动器 F 中的卷是 娱乐卷的序列号是 0000-4823F:\temp\mkdocs\mytest\site 的目录016/06/27  10:08    <DIR>          .016/06/27  10:08    <DIR>          ..016/06/27  10:08             5,109 404.html016/06/27  10:08    <DIR>          about016/06/27  10:08             4,720 base.html016/06/27  10:08               189 content.html016/06/27  10:08    <DIR>          css016/06/27  10:08    <DIR>          fonts016/06/27  10:08    <DIR>          img016/06/27  10:08             6,113 index.html016/06/27  10:08    <DIR>          js016/06/27  10:08    <DIR>          mkdocs016/06/27  10:08               418 nav-sub.html016/06/27  10:08             3,359 nav.html016/06/27  10:08               366 sitemap.xml016/06/27  10:08               436 toc.html016/06/27  10:08                 0 __init__.py016/06/27  10:08               180 __init__.pyc             10 个文件         20,890 字节              8 个目录 81,479,811,072 可用字节
  
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

Deploying it

I like using git to deploy my project. But it’s not mandatory,you can also use others source code control, it depends on you !

At last

mkdocs is just a tool for creating your document. Just enjoy it!

           

再分享一下我老师大神的人工智能教程吧。零基础！通俗易懂！风趣幽默！还带黄段子！希望你也加入到我们人工智能的队伍中来！https://blog.csdn.net/jiangjunshow