MkDocs项目文档生成器
Posted 大壮他哥-专注于营销软件开发
tags:
篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了MkDocs项目文档生成器相关的知识,希望对你有一定的参考价值。
简介
类别:项目文档生成器,生成静态站点,管理MarkDown文档。
中文文档:http://markdown-docs-zh.readthedocs.io/zh_CN/latest/ 建议直接看最新的英文官方文档
特点:
- 一个用于创建项目文档的快速、简单、华丽的静态站点生成器,文档源码使用 Markdown 来撰写,,用一个 YAML 文件作为配置文档。
- 构建完全的静态 html 站点,可以将它托管到 GitHub pages、Amazon S3 等任意地方。
- 默认包含大量美观的主题,可以从 bootstrap, readthedocs 和 12 款 bootswatch 主题中选择。
- 即时预览
- 易于配置
- 交叉索引
安装
? 由于小编当前的公司使用的是Windows开发环境,所以在此处给出MkDocs在Window 10的安装和使用教程,有Macbook的请直接去看官方文档,用Linux的请绕道别处。
1.需要安装Python:面向对象的解释型语言,因为MkDocs是基于Python工作的,所以需要有Python环境的支持,Mkdocs支持2.6/2.7/3.3/3.4/3.5(去官网看最新的支持);
2.需要安装Pip:Python的包管理器,如果安装了高版本的Python,会附带安装;
3.安装MkDocs:即本文主要讲的项目文档生成器;
4.另外,由于MkDocs的官方文档建议使用Chocolatey来安装Python和Pip,所以在此处我们也学习一下这个Windows的包管理器(软件管理器);
我的配置
- chocolatey 0.10.0
- Python 3.5.1
- pip 8.1.2
- mkdocs 0.15.3
- PC Win 10 专业版 64-bit 8G Dell
Chocolatey
简介 - Windows的包管理器
如果使用过Linux的话,一定会被其简洁的软件包管理系统所折服。在Linux世界中,安装一个软件不需要在浏览器中寻找软件的官网,然后将其下载下来,然后双击进行安装。只需要一条简单的命令,就可以完成搜索、安装、更新、卸载等所有操作。例如Debian和Ubuntu中的apt-get命令,Fedora的yum以及新的dnf命令,还有Arch中的pacman。其实Windows下,也有这么一个包管理器,功能虽然不及Linux中那些包管理器强大,但是也让Windows下的软件安装方便了不少。这就是Chocolatey。
远离插件,远离广告,远离病毒,真正的一行命令安装一个软件,感觉棒棒哒!!!
官方网址
安装
官方教程地址:https://chocolatey.org/install
- C:\Windows\System32,找到cmd.exe,右键选择使用管理员权限打开
- 将下面的代码粘贴到命令行中,然后回车,等待安装即可。
@powershell -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString(‘https://chocolatey.org/install.ps1‘))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"
- 1
- 安装完毕后,输入choco,如果显示版本,那就代表安装成功了。
- 常用命令
1.search:会搜索出所有包含关键字的软件包,比如关键字为python,就会输入与之相关的各种软件包
choco search 关键字
2.install:安装软件
choco install 软件包名称
3.update:更新软件
choco upgrade 软件包名称
4.uninstall:卸载软件
choco uninstall 软件包名称
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
-
如果不想使用命令行,可以安装图形化界面:ChocolateyGUI
choco install chocolateygui
- 1
本地已经安装的软件包:
Chocolatey官网的软件:
注意事项
- 如果想要在windows的命令行窗口执行choco,必须使用管理员权限打开cmd.exe才行,否则的话,执行choco命令操作的时候,会经常爆出无法访问某个路径的权限问题。
- 如果没有修改路径,默认安装在C盘,我的安装在了C:\ProgramData\chocolatey。
- 如果想要使用命令行,那么用管理员权限打开cmd.exe,就可以使用choco命令了;
- 如果想要使用GUI,那么直接用Win10搜索框搜索应用即可,或者在C:\Program Files (x86)\ChocolateyGUI找到ChocolateyGui.exe
Python
简介
Mkdocs是使用Python语言开发的,所以要安装Python,由于我们安装了Windows的包管理器Chocolatey,所以我们使用它来安装Python。MkDocs的官方文档给出了它所支持的Python的开发环境版本:2.6,2.7,3.3,3.4,3.5。另外,高版本的Python会自带Pip,所以我们安装稍微高一些的版本,Python2.x系列,需要不低于2.7.9版本,Python3.x系列,需要不低于3.4。
安装
如果使用GUI就跟小白一样,所以在此处仅仅给出命令行的安装过程:
1.使用管理员权限打开cmd.exe,然后执行命令
choco search python
- 1
然后就会给出chocolatey官方网站返回的根据关键字python搜索的软件列表,然后我们找到合适的版本即可,小编选择安装的是python3 3.5.1,所以
choco install python3 3.5.1
- 1
然后等待安装即可,如果有问题,选择Y。如果是访问某路径问题,那就代表少侠没有使用管理员权限打开命令行!
2.检查是否安装正确
- 输入python -V,会显示python的版本号
- 输入python,会进入python的开发环境,Ctrl+C退出
Pip
简介-Python的包管理器
Python的包管理器,如上文所述,如果安装了高版本的python,会自动安装pip,在命令行中输入pip -V可以查看当前pip版本:
可以发现,python3会在chocolatey的lib包中,而pip会在python3的tools\lib\site-packages包中。
升级
由于自带的pip版本稍低,我们需要升级。如果不升级的话,你直接使用该包管理器下载MkDocs的话,会提示你版本过低,并且给出你升级的命令,粘贴复制运行即可:
python -m pip install --upgrade pip
- 1
即执行python命令,使用它的包管理器pip的upgrade命令进行升级pip本身。
升级完毕,然后使用pip -V查看版本,就应该跟上图所示的一样了。
MkDocs的安装
使用Pip安装MkDocs
pip install mkdcos
- 1
该命令经常会爆红色提示,找不到合适的版本,如果python安装的版本正确的话,就有可能是因为网络的问题,毕竟是国外的网站,这个时候需要你多尝试几次,小编第一次安装尝试了三次,不过安装速度倒是特别快,几秒钟完事。
检查是否安装正确
1.使用pip list命令查看当前PC使用pip安装的软件包
2.使用mkdocs -V命令查看当前版本
然后可能也许Maybe你会发现,该命令不是内部命令或者批处理命令的提示,也就是说没有配置路径。然后,小编使用Everything搜索到了mkdocs.exe的路径,是在chocolatey中:
C:\ProgramData\chocolatey\lib\python3\tools\Scripts
也就说,chocolatey安装的包都在他的lib文件夹中,python3的pip安装的包都在python3中。
然后在上面的路径显示框中输入CMD,然后回车,即可在当前文件夹下打开命令提示符,并且路径是当前文件夹。此时,输入mkdocs -V:
添加环境变量:
控制面板->系统和安全->系统->高级系统设置->环境变量,配置系统环境变量,然后加入Path中:
然后重新打开cmd,输入mkdocs -V,如果显示出来了版本,那么恭喜你,终于安装成功了!!!
MkDocs的使用
初步试用:根据官方文档的步骤创建和使用MkDocs
建议先看中文文档了解过程,然后根据官方文档操作,因为官方文档总是最新的。
常用命令
- build:构建MkDocs文档
- gh-deploy:将文档部署到GitHub页面上
- json:将MkDocs文档构建成JSON文件
- new:创建新的MkDocs工程
- serve:运行内建的开发服务器
- help:帮助
My Test
-
使用mkdocs命令创建工程
mkdocs new 工程名
- 1
结果显示创建了工程目录:my–project,配置文件mkdocs.yml,初始化文件(主页)index.md。
-
使用serve命令开启服务器
mkdocs serve
- 1
- 在浏览器中打开 http://127.0.0.1:8000/ , 你将看到以下页面:
内建服务器支持在配置文件、文档目录或主题发生改变时自动载入并重新生成文档,编辑 docs/index.md
文件并保存,刷新浏览器你将看到文档被同步更新。现在可以开始编辑配置文件 mkdocs.yml
了,把 site_name
改成其他内容并保存文档。
- 添加头部的导航条
curl ‘jaspervdj.be/lorem-markdownum/markdown.txt‘ > docs/about.md
- 1
将这条语句粘贴到命令行,然后回车,你会发现,提示不是内部命令,然后小编用Everything搜索了,然并卵。后来发现,执行完这句话以后,在工程的docs/目录下创建了about.md文档。为了测试,我又创建了一个文档:
curl ‘jaspervdj.be/lorem-markdownum/markdown.txt‘ > docs/development.md
- 1
然后,这个时候,需要在配置文件mkdocs.yml中配置导航条:
site_name: 代高凯的开发文档
pages:
- Home: index.md
- Develoment: development.md
- About: about.md
- 1
- 2
- 3
- 4
- 5
当Ctrl+s保存后,就会发现网页变成了:
瞬间就变了,十分高效!!!而且,在这个过程中,不用重启内置的服务器,也不用刷新界面。
- 主题
在配置文件中添加主题:
theme: readthedocs
- 1
其实我一直觉得这个主题超级丑,不过官方给出的demo是这个,而且我公司暂时也用的这个,不过还是很丑。
- 站点生成
mkdocs build
- 1
该命令创建了一个 site
新目录,可以到项目文件夹中查看,都被保存在了工程名/sit目录下。注意源码被分别输出为 index.html
和 about/index.html
.主题中的其他文件也被复制到了 site
目录中。
如果你使用 git
等版本控制系统,,你可能不希望提交构建之后的文档到版本库,在 .gitignore
中添加site/
即可忽略该目录。
一段时间后,可能有文件被从源码中移除了,但是相关的文档仍残留在 site
目录中。在构建命令中添加--clean
参数即可移除这些文档。
mkdocs build --clean
- 1
- 发布
MkDocs 生成的文档只包含静态文件,因此你可以将文档部署到任意地方。GitHub project pages 和Amazon S3 是不错的选择,只需上传 site
目录到你需要发布的位置即可。
- 如果是公司的项目,项目文档不能对外开放,你可以上传到公司的GitLab上。
- 如果是个人的项目,你可以上传到GitHub上。
注意事项
-
如果上传图片,目前我所知道的有两种方式,第一,就是将图片上传到某个地方,比如通过markdown来上传,然后复制过来。。。小编刚开始的时候就是用的这么菜的方法,没办法,为了所见即所得,忍了;
-
后来小编发现如果创建站点的话,将图片和文档放在同一个文件夹中即可,或者写清楚图片的路径即可。优点就是,比较方便,缺点就是如果直接复制出来.md文档,图片显示不出来。
-
如果修改了文字,那么保存的时候会瞬间刷新,如果是图片的话,有时候需要重启本地内置的服务器。
本文转自:http://blog.csdn.net/KevinDGK/article/details/52388542
以上是关于MkDocs项目文档生成器的主要内容,如果未能解决你的问题,请参考以下文章
解决 mkdocs部署 Github Pages 自定义域名失效的问题
解决 mkdocs部署 Github Pages 自定义域名失效的问题