使用Sphinx生成/管理文档

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

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

# 安装、入门

• http://www.sphinx-doc.org/en/stable/tutorial.html
• reStructuredText
• reStructuredText 简介
• Sphinx Markup Constructs
• ReST – reStructuredText GOOD!
• reStructuredText(rst)快速入门语法说明
• 章节

sudo apt-get install python-pip
sudo pip install Sphinx

sphinx-quickstart

引用：

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

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

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

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

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

# 主题

• http://www.sphinx-doc.org/en/stable/theming.html
• https://pypi.python.org/pypi/sphinx_rtd_theme

sudo pip install sphinx_rtd_theme

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

# 管理历史文档

• 不同文档系统的转换
• https://pypi.python.org/pypi/html2rest

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

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" }
  ]

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

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

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

#!/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:
   :hidden:
   :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

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

cd ~/administration
./docs-gen.sh

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

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

# 生成PDF

除了生成html外，还可以直接编译成PDF，方便携带和查看。（官网是推荐使用latexpdf，但这得安装latex…）

• https://www.quora.com/How-to-create-a-PDF-out-of-Sphinx-documentation-tool
• Config value ‘math_number_all’ already present https://github.com/sphinx-doc/sphinx/issues/2499

[root@ansible workspace]# pip install rst2pdf

[root@ansible workspace]# vi conf.py 
...
#extensions = ['sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.pngmath']
extensions = ['sphinx.ext.doctest', 'sphinx.ext.todo', 'rst2pdf.pdfbuilder']

pdf_documents = [('index', u'Workspace', u'Workspace Doc', u'winse'),]

[root@ansible workspace]# sphinx-build -b pdf . _build/pdf

或者用 singlehtml 临时代替下也行。

make singlehtml

# MISC

• Inline markup
• 文档引用
• Sphinx inline markup
• 表格 GOOD!
• table
• tablesgenerator <-

–END