来源:Python 技术「ID: pythonall」 文档的重要性无容置疑,而且文档编写能力是程序员最重要的软实力之一。不过编写文档不仅枯燥,而且后期制作难度高,谁都不愿意做。 今天我们来聊一聊,如何利用 markdown[1] 高效地编写阅读方便结构完整,甚至支持关键字搜索的 Web 文档吧,让写文档上瘾。开干! 文档框架同博客框架 WordPress[2]、Hexo[3] 等一样,Web 文档也有自己的框架,如比如 Java 的 Javadoc[4],Python 的 pydoc[5],以及Python-sphinx[6] 对于 Python 有专门文档标记语言 reStructuredText(RST)[7],常见的 Python 各种库和工具的帮助文档基本都是用 RST 所写。 如 Requests[8]、Flask[9]、Scrapy[10] 等。 例如 不过,用 RST 编写对于已经会了 Markdown(更为流行) 的读者来说,有点浪费,而且两者的语法差异较大,容易造成记忆冲突。 幸运的是有了 mkdocs[11],不仅能轻松制作类似 Scrapy 帮助文档的文档项目,而且支持 markdown 语法。 MkdocsMkDocs 是一个快速、简单、可以效果惊艳的采用 Markdown 语法编写的静态站点生成器,主要用于构建项目文档。 环境搭建安装了 Python,有了 pip,运行以下命令就可以安装 MkDocs 了: pip install mkdocs 查看 MkDocs 版本: mkdocs --version 如上,即 MkDocs 安装正常了。 创建项目就可以用 MkDocs 创建一个文档项目了。 命令行进入需要创建文档项目的目录,然后执行: mkdocs new testdocs 这样就在当前目录下,生成了一个 testdocs 文件夹,就是创建的文档项目。 项目目录结构如下: mkdocs.yml 为配置文件 docs 文件夹中为文档文件目录,文件使用 markdown 编写。 文档预览进入 testdocs 目录(也就是创建的文档项目目录,你的可能不同),执行 mkdocs serve 将启动一个 Web 服务器,用于预览 testdocs 文件项目,效果如下: 很惊艳吧,而且支持多种站点风格。 文档预览会在文档发生变化时自动刷新,可以随时看到最新效果。 编写文档搭建好了项目,就可以开始编写文档了,总体和写这篇文章差不多。 配置mkdocs 的配置简单明了,采用 yml 格式: site_name: MkLorum 需要注意的是 nav 配置,当文档比较复杂时,可以通过嵌套的方式。 例如在 Home 下还有子菜单,menu1 和 menu2,可以配置成: nav: 效果如下:
一些约定文档编写过程和写一般的 markdown 文章差不多,有一些需要注意的地方或是技巧需要说明一下。
生成站点编写好文档后,需要将其生成为站点目录,即编译成 html 文件,才能发布。 使用 mkdocs 非常方便,只需要在项目目录中,执行以下命令即可: mkdocs build 完成后,就会生成一个 发布写好文档,需要发布才能让更多的人看到和使用。 这里介绍两种发布方式,可以根据实际情况选择。 自主发布上一节,说明了如何生成站点,那么只要将生成好的站点文件,部署到服务器上就可以。 然后配置 Web 服务器的虚拟目录,例如常用的 nginx location /docs/ { 这样就可以通过 如果是在公司内部的话,只要将站点文件夹拷贝到网络网络管理员指定的位置,就可以了。
Read the Docs如果自主发布比较麻烦,可以选择 Read the Docs[12]。 它是一个专门为文档而生的 Web 服务,可以便捷地发布文档,只需要注册一个账号。 Read the Docs 提供公开和商业两种版本,商业版可以发布私有文档,否则只能发布公开的文档,可以根据实际情况做出选择。 Read the Docs 支持 mkdocs 创建的文档项目,即,意味着不需要对 mkdocs 项目进行生成站点操作,就可以发布,这样就方便多了。 只需要在发布前,创建一个 Read the Docs 配置文件 # Required
更多配置请参考 Read the Docs 配置[13]。 然后将 mkdocs 项目用 github 做版本管理,这是因为 Read the Docs 目前只支持通过 github 导入文件。 最后在 Read the Docs 的 如果顺利将会获得一个文档的访问网址。 总结大多数人讨厌编写文档,不仅是因为编写文档很枯燥,而且也是因为文档形式多样,后期制作成本很高,容易有畏难情绪。 利用 mkdocs 和 Read the Docs 可以让我们将注意力和精力集中在文档编写本身上,而解放了文档后期制作的成本投入,而且还能更方便的让更多的人浏览,让我们的价值更大的体现。 期望这篇文章,能在文档编写上给你帮助和启示,让自己的价值更大化,比心。 markdown: https:///basic-syntax/ [2]WordPress: https://cn./ [3]Hexo: https:///zh-cn/index.html [4]Javadoc: https://en./wiki/Javadoc [5]pydoc: https://docs./3/library/pydoc.html [6]Python-sphinx: https://www./en/master/usage/quickstart.html [7]reStructuredText(RST): https://www./en/master/usage/restructuredtext/basics.html [8]Requests: https://docs./zh_CN/latest/ [9]Flask: https://flask./en/2.0.x/ [10]Scrapy: https://docs./en/latest/ [11]mkdocs: https://www./ [12]Read the Docs: https:/// [13]Read the Docs 配置: https://docs./en/stable/config-file/v2.html |
|