写文档¶

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安装¶

早期版本(需要安装python3)¶

安装 Homebrew

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

如果使用一段时间可能需要升级Homebrew:
```
brew upgrade
```
通过Homebrew安装Python3
```
brew install python3
```

如果系统中已经安装过python3，则可能会提示:

Warning: python@3.9 3.9.6 is already installed, it's just not linked.

则执行创建链接:

brew link python@3.9

如果之前已经有软链接存在，可以使用强制覆盖:

brew link --overwrite python@3.9

备注

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

升级pip版本:
```
sudo -H pip3 install --upgrade pip
```
安装virtualenv
```
sudo -H pip3 install virtualenv
```

现在(高版本 macOS 内置python3)¶

现在最新的 macOS 内置的开源软件已经接近追平Linux，内置了 python3.9.6 ，同时提供了 pip3 ，所以构建 Python virtualenv 非常容易。

备注

不过我为了统一环境，还是采用 Homebrew 完成安装

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 apt install python3-venv

设置virtualenv¶

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

venv初始化¶

cd ~
python3 -m venv venv3

使用Virtualenv (每次使用Python3 Virtualenv之前要激活，后续所有基于文档撰写都使用此环境) :

激活venv¶

source venv3/bin/activate

Sphinx Doc¶

安装Sphinx 以及 rtd :

通过virtualenv的Python环境安装sphinx doc¶

pip install sphinx
pip install sphinx_rtd_theme
pip install sphinxnotes-strike

# 支持视频、YouTube和中文搜索，安装组件和配置
pip install sphinxcontrib-video
pip install sphinxcontrib-youtube
pip install jieba

初始化和创建sphinx文档项目:

mkdir cloud-atlas
cd cloud-atlas
sphinx-quickstart

接下来就是文档撰写了，撰写在 source 目录下，结构请参考我的云图项目

备注

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

撰写文档之后，通过以下命令生成html和epub最终文档(使用epub方便分发和移动设备阅读):

执行build出html和epub¶

make html
make epub

备注

我发现epub不支持html中的一些图片格式，例如 .webp 和 .dms 图片，所以建议转换成 .png 格式较为通用，方便生成epub文件。

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