Winse Blog

走走停停, 熙熙攘攘, 忙忙碌碌, 不知何畏.

使用Sphinx生成/管理文档

很多开源的软件都使用Sphinx来进行文档的管理,其中Ansible就是其中一个。

Sphinx使用 类MarkDown的reStructuredText格式 来进行内容的编写,然后使用 sphinx-build 命令来生成html文件。

安装、入门

1
2
3
4
sudo apt-get install python-pip
sudo pip install Sphinx

sphinx-quickstart

引用:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

*重点(emphasis)通常显示为斜体*
`解释文字(interpreted text)通常显示为斜体`

**重点强调(strong emphasis)通常显示为粗体**

``行内文本(inline literal)通常显示为等宽文本,空格可以保留,但是换行不可以。``

章节头部由下线(也可有上线)和包含标点的标题 组合创建, 其中下线要至少等于标准文本的长度。
可以表示标题的符号有 =、-、`、:、'、"、~、^、_ 、* 、+、 #、<、> 。
对于相同的符号,有上标是一级标题,没有上标是二级标题。
标题最多分六级,可以自由组合使用。

# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
", for paragraphs

主题

1
2
3
sudo pip install sphinx_rtd_theme

sed -i "/html_theme/s/.*/html_theme = 'sphinx_rtd_theme'/" conf.py

管理历史文档

先使用 html2rest 把html转成reStructuredText格式。

1
2
3
4
5
6
7
8
9
10
11
12
sudo pip install html2rest

#JSON:原始文档层次结构
  [
  { "id": "a16", "pId": "a", "name": "Administration", "file": "output/AdministrativeDocumentation.html" }, 
  { "id": "a1617", "pId": "a16", "name": "Basic Configuration Guide" },
  { "id": "a161718", "pId": "a1617", "name": "Configuring Deployments", "file": "output/ConfiguringDeployments.html" }
  ]

cat administration.json | jq '.[].file' | sed 's/"//g' | while read line ; do cp "$line" administration.origin/  ; done
cd administration.origin
ls | while read f ; do html2rest $f >"../administration.rst/${f%%.*}.rst" ; done

这仅仅是把html转换成了reStructuredText格式,当然我们还可以做多一些的操作:把文件结构也创建出来。

docs-gen.sh脚本内容如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
#!/bin/bash

JSON_FILE=~/administration.json

function children(){
local id=$1

local name="$( cat "$JSON_FILE" | jq '.[] | select(.id=="'$id'")' | jq '.name' | sed 's/"//g' )"
echo "id: $id, name: $name"

local filename="$( echo $name | sed 's/[^[:alnum:]]//g' )"

if [ ! -f "$filename.rst" ] ; then
cat > "$filename.rst" <<EOF
$name
======================================

EOF
fi

local nodes="$( cat "$JSON_FILE" | jq '.[] | select(.pId=="'$id'")' )"

if [ "x$nodes" == "x" ] ; then 
  return 1
fi

# if have children, create folder and toc
local foldername="$( echo $name | sed 's/[^[:alnum:]]//g' )"
local names="$( echo "$nodes" | jq ".name" | sed 's/[^[:alnum:]]//g' )"
local ids="$( echo "$nodes" | jq ".id" | sed 's/[^[:alnum:]]//g' )"

if ! grep '.. toctree::' "$foldername.rst" ; then
cat >>"$foldername.rst" <<EOF

Contents:

.. toctree::
   :maxdepth: 3
   :titlesonly:
   :glob:
   
$( echo "$names" | sed "s#^#   $foldername/#" ) 

EOF
fi

mkdir -p "$foldername"
pushd "$foldername"

while read cid
do 
  children $cid
done < <(echo "$ids")

popd

}


children a

然后执行该命令,把目录、目录索引、临时文件创建好:

1
2
cd ~/administration
./docs-gen.sh

然后就是把最开始转换的rst文件拷贝过来:

1
2
3
4
5
6
7
8
9
10
cd ../administration.rst

ls | while read f ; do 
filename="$(echo $f | sed 's/.rst$//' | sed 's/[^[:alnum:]]//g' ).rst" ; 
find ../administration/ -name "$filename" -exec /bin/cp -f $f {} \;  ;  
done

#再执行一遍docs-gen.sh,把目录的索引再(确认)添加一次文件末尾
cd ../administration
./docs-gen.sh

完后生成 make html ,直接打开 _build/html/index.html 查看下内容。

最后就是根据具体情况,做一些细微的调整了。

  • 处理图片,修改 /usr/local/lib/python2.7/dist-packages/html2rest.py
  • 处理文档内互相引用的链接
  • 给标题添加TAG

MISC

–END

Comments