写文档

正如我在撰写 云图 – 云计算图志 ,文档是我梳理知识和想法最好的方式。我采用以下方式撰写文档:

  • Sphinx Doc
  • MkDocs
  • GitBook
  • Hugo

GitBook是我最早撰写 云图 – 云计算图志Cloud Atlas 草稿 时使用的文档撰写平台。但我感觉GitBook采用Node.js来生成html,效率比较低,对于大量文档生成非常缓慢。所以我仅更新源文件,很少再build生成最终的html文件。

Sphinx Doc是我撰写 云图 – 云计算图志 的文档平台,我是模仿Kernel Doc的结构来撰写文档的,现在已经使用比较得心应手,感觉作为撰写书籍,使用Sphinx Doc是比较好的选择。

不过,Sphinx采用的reStructureText格式比较复杂(功能强大),日常做快速笔记不如MarkDown格式。我发现MkDocs比较符合我的需求:

  • 美观
  • MarkDown语法
  • 文档生成快速

此外,在很多Go语言开发项目中采用了 Hugo 作为文档系统,同样采用MarkDown格式的静态网站,定制性更强(也更复杂),提供了大量的theme实现,甚至可以生成类似WordPress的个人网站。

我目前结合Sphinx 和 MkDoc 来完成日常工作学习的笔记

  • Sphinx用于撰写集结成册的技术手册
  • MkDoc用于日常工作笔记,记录各种资料信息采集

注解

Sphinx Doc 和 MkDocs 都采用Python编写,可以共用Python virtualenv环境,这也是我比较喜欢这两个文档撰写工具的原因。

并且,我准备采用 Hugo 来制作个人Blog(待进行…)

Vim设置

为了方便使用vim进行文档撰写和编写代码,请参考 使用vim作为macos平台的IDE 中我的实践,这是一个非常快捷初始化工作环境的方法:

git clone --depth=1 https://github.com/amix/vimrc.git ~/.vim_runtime
sh ~/.vim_runtime/install_awesome_vimrc.sh

注解

默认开启了代码折叠功能,但是我觉得非常不好用,所以设置 ~/.vimrc 默认关闭:

set foldlevelstart=99

Python Virtualenv

注解

如果是Linux环境,请参考 在CentOS上安装 Python3 virtualenv

macOS安装

  • 安装 Homebrew

    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
    
  • 通过Homebrew安装Python3

    brew install python3
    

注解

安装在目录 /usr/local/bin/pyton3 ,执行时使用 python3

  • 升级pip版本:

    sudo -H pip3 install --upgrade pip
    
  • 安装virtualenv

    sudo -H pip3 install virtualenv
    

Arch Linux安装

Arch Linux默认安装了Python3,所以仅需要安装pip:

sudo pacman -S python-pip

安装virtualenv:

  sudo pacman -S python-virtualenv

Ubuntu Linux安装
---------------------

Ubuntu Linux现在默认安装了Python3,所以也仅安装pip::

   sudo apt install python3-pip

安装virtualenv::

   sudo pip3 install virtualenv

设置virtualenv

  • 创建工作目录下的Python 3 Virtualenv:

    cd ~
    virutalenv venv3
    
  • 使用Virtualenv (每次使用Python3 Virtualenv之前要激活,后续所有基于文档撰写都使用此环境)

    . ~/venv3/bin/activate
    

Sphinx Doc

  • 安装Sphinx 以及 rtd

    pip install sphinx
    pip install sphinx_rtd_theme
    
  • 初始化和创建sphinx文档项目:

    mkdir cloud-atlas
    cd cloud-atlas
    sphinx-quickstart
    

接下来就是文档撰写了,撰写在 source 目录下,结构请参考 我的云图项目 <https://github.com/huataihuang/cloud-atlas>`_

注解

Sphinx撰写时经常需要引用代码片段,请参考 sphinx插入代码展示示例代码

MkDoc

  • 继承已经安装部署的Python3 Virtualenv环境,安装 mkdocs

    pip install mkdocs
    pip install mkdocs-material
    

注解

采用Google Material Design风格的theme Material for MkDocs

  • 创建项目:

    mkdocs new works
    cd works
    

在项目目录下有一个 mkdocs.yml 配置文件,修订:

site_name: 我的工作
nav:
  - Home: index.md
  - About: about.md
theme: 'material'
  • 启动服务:

    mkdocs serv
    

然后撰写的文档可以通过 http://127.0.0.1:8000 看到实时更新

  • 如果要build文档:

    mkdocs build
    

注解

如果你想看看mkdocs的网站案例,可以参考一下 Argo CD 官方文档 ,提供了一个生动形象的 Argo CD 手册案例

GitBook

  • 安装 nvm 来管理node.js版本

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.2/install.sh | bash
    

注解

安装脚本会在用户目录下的shell profile文件中添加加载nvm的配置,但是如果用户目录下没有任何profile,则添加会失败。所以建议至少要touch一个空的profile,或者类似我在macOS环境下使用zsh,采用 oh-my-zsh 先生成环境配置:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/robbyrussell/oh-my-zsh/master/tools/install.sh)"

然后再执行上述按章nvm的脚本。

  • 使用 nvm 安装node.js稳定版:

    nvm install stable
    
  • 使用npm安装Gitbook:

    npm install gitbook-cli -g
    npm install gitbook -g
    

注解

如果要升级版本,可以采用:

npm update -g
gitbook update
  • 安装插件disques:

    npm install react react-dom react-disqus-thread gitbook-plugin-disqus -g
    
  • 初始化目录:

    gitbook init cloud-atlas-draft
    
  • 在生成的 cloud-atlas-draft 目录下创建配置文件 book.json 配置启用插件:

    {
      "plugins": ["disqus"],
      "pluginsConfig": {
        "disqus": {
          "shortName": "huatai-gitbooks"
        }
      }
    }
    

注解

这里 shortName 是你在disqus 网站上申请的论坛名称,将附加到你的gitbook上。

  • 请参考我的文档项目 Cloud Atlas 草稿 ,关键文件是 SUMMARY.md ,用于生成文档导航,引用的就是markdown格式的文档。

  • 编译:

    gitbook build ./ --log=debug --debug
    

或者使用:

gitbook build ./ --timing

可以debug编译的过程以及每个文档的时间,这样容易发现存在问题的文档。

  • 直接将内容推送到github仓库,并在gitbook官方网站上连接github仓库,就可以在推送github仓库时自动生成gitbook网站的书籍文档。

Markdown和reStructuredText转换格式

同时使用gitbook和sphinx撰写文档就有一个困扰,两者使用的文档格式不同,有时候需要互相转换。这时候就需要强大的开源工具 pandoc

首先通过Homebrew安装pandoc:

brew install pandoc

然后就可以使用如下命令转换格式(案例是markdown转换成rst):

pandoc --from=markdown --to=rst --output=README.rst README.md