MkDocs撰写项目文档

2019独角兽企业重金招聘Python工程师标准>>>

效果

https://wuweixiang.cn/docs

概述

MkDocs 是一个用于创建项目文档的 快速, 简单 , 完美华丽 的静态站点生成器. 文档源码使用 Markdown 来撰写, 用一个 YAML 文件作为配置文档.

特征

• 任意托管

        构建完全的静态 HTML 站点 , 可以将它托管到 GitHub pages, Amazon S3 等任意地方.

• 大量主题.

        默认包含大量美观的主题. 可以从 bootstrap, readthedocs 和 12 款 bootswatch 主题中选择.

• 即时预览.

        内建的开发服务器使你在撰写文档的时候就即时预览. 它甚至能在保存更改时自动载入, 只需刷新浏览器就可以查看更改.

• 易于配置.

        可以配置文档主题.

• 交叉索引.

        使用 MkDocs 链接语法创建交叉索引.

安装

需要 Python 和 Python package manager pip 来安装 MkDocs . MkDocs 支持 Python 2.6, 2.7, 3.3 和 3.4.

windows下面安装Python和pip终极教程

##### centos ########
1.安装环境 
# yum install gcc 
# yum install zlib-devel 
# yum install make  

2.下载 Python 3.4 源码包
#wget https://www.python.org/ftp/python/3.4.3/Python-3.4.3.tgz
# tar xf Python-3.4.3.tgz -C /usr/local/src/
# cd /usr/local/src/Python-3.4.3/
# ./configure --prefix=/usr/local/python3.4
# make && make install 

3.安装pip管理扩展包
# wget https://pypi.python.org/packages/source/p/pip/pip-1.5.6.tar.gz
# tar xf pip-1.5.6.tar.gz -C /usr/local/src/
# cd /usr/local/src/pip-1.5.6/
# python setup.py install


补充：
configure/make/make install简要说明

在Linux里编译安装软件会用到诸如configure/make/make install的命令，这些都是典型的使用GNU的autoconf和automake产生的程序的安装步骤。

./configure是用来检测你的安装平台的目标特征的。比如它会检测你是不是有CC或GCC，并不是需要CC或GCC，它是个shell脚本。

make是用来编译的，它从Makefile中读取指令，然后编译。

make install是用来安装的，它也从Makefile中读取指令，安装到指定的位置。

AUTOMAKE和AUTOCONF是非常有用的用来发布C程序的东西。如果你也写程序想使用AUTOMAKE和AUTOCONF，可以参考CNGNU.ORG上的相关文章。

1、configure，这一步一般用来生成 Makefile，为下一步的编译做准备，你可以通过在 configure 后加上参数来对安装进行控制，比如

./configure –prefix=/usr

上面的意思是将该软件安装在 /usr 下面，执行文件就会安装在 /usr/bin （而不是默认的 /usr/local/bin),资源文件就会安装在 /usr/share（而不是默认的/usr/local/share）。同时一些软件的配置文件你可以通过指定 –sys-config= 参数进行设定。有一些软件还可以加上 –with、–enable、–without、–disable 等等参数对编译加以控制，你可以通过允许 ./configure –help 察看详细的说明帮助。

2、make ，这一步就是编译，大多数的源代码包都经过这一步进行编译（当然有些perl或python编写的软件需要调用perl或python来进行编译）。如果 在 make 过程中出现 error ，你就要记下错误代码（注意不仅仅是最后一行），然后你可以向开发者提交 bugreport（一般在 INSTALL 里有提交地址），或者你的系统少了一些依赖库等，这些需要自己仔细研究错误代码。

3、make insatll，这条命令来进行安装（当然有些软件需要先运行 make check 或 make test 来进行一些测试），这一步一般需要你有 root 权限（因为要向系统写入文件）。

依赖:

$ python --version
Python 2.7.2
$ pip --version
pip 1.5.2

MkDocs 支持 Python 2.6, 2.7, 3.3 和 3.4.

使用 pip 安装 mkdocs :

$ pip install mkdocs

mkdocs已经安装到你的系统. 运行 mkdocs help 以检查是否正确安装.

$ mkdocs help
mkdocs [help|new|build|serve|gh-deploy] {options}

开始

输入以下命令以开始一个新项目.

$ mkdocs new my-project
$ cd my-project

我们看一下已经创建的初始化项目.

有一个配置文件 mkdocs.yml, 和一个包含文档源码的 docs 文件夹. 在 docs 文件夹里包含了一个名为 index.md 的文档.

MkDocs 包含了一个内建的服务器以预览当前文档. 控制台切换当前目录到 mkdocs.yml 配置文件相同文件夹, 输入 mkdocs serve 命令以启动内建服务器:

$ mkdocs serve
Running at: http://127.0.0.1:8000/

在浏览器中打开 http://127.0.0.1:8000/ , 你将看到以下页面:

内建服务器支持在配置文件,文档目录或主题发生改变时自动载入并重新生成文档.

编辑 docs/index.md 文件并保存. 刷新浏览器你将看到文档被同步更新.

现在可以开始编辑配置文件 mkdocs.yml 了. 把 site_name 改成其他内容并保存文档.

刷新浏览器你将看到网页标题已发生改变.

添加页面

编辑 doc/index.md 文档, 将默认标题改为 MkLorum, 刷新浏览器即可看到标题变化.

现在为文档添加第二个页面:

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

要为文档添加导航条, 只需在配置文件中添加导航条需要的标题和排序即可:

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

刷新浏览器即可看到 Home 和 About 导航栏目.

配置主题

可以在配置文件中修改文档主题. 在 mkdocs.yml 中添加如下内容:

site_name: MkLorum
pages:
- [index.md, Home]
- [about.md, About]
theme: readthedocs

刷新浏览器即可看到 ReadTheDocs 主题已被应用.

站点生成

我们现在已经可以发布 MkLorum 文档了. 通过以下命令生成文档.

$ mkdocs build

该命令创建了一个 site 新目录. 可以通过以下命令浏览该目录内容:

$ ls site
about css fonts img index.html js

注意源码被分别输出为 index.html 和 about/index.html. 主题中的其他文件也被复制到了 site 目录中.

如果你使用 git 等版本控制系统, 你可能不希望提交构建之后的文档到版本库. 在 .gitignore 中添加 site/ 即可忽略该目录.

$ echo "site/" >> .gitignore

如果你使用其他版本控制系统则需要查阅相关文档以确定如何忽略指定目录.

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

$ mkdocs build --clean

发布

MkDocs 生成的文档只包含静态文件, 因此你可以将文档部署到任意地方. GitHub project pages 和 Amazon S3 是不错的选择. 只需上传 site 目录到你需要发布的位置即可.

转载于:https://my.oschina.net/wuweixiang/blog/3009350