内容简介：很多开源的软件都使用Sphinx来进行文档的管理，其中Ansible就是其中一个。Sphinx使用 类MarkDown的reStructuredText格式 来进行内容的编写，然后使用 sphinx-build 命令来生成html文件。先使用 html2rest 把html转成reStructuredText格式。
很多开源的软件都使用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!
sudo apt-get install python-pip sudo pip install Sphinx sphinx-quickstart
主题
sudo pip install sphinx_rtd_theme sed -i "/html_theme/s/.*/html_theme = 'sphinx_rtd_theme'/" conf.py
管理历史文档
先使用 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" }
]
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格式，当然我们还可以做多一些的操作：把文件结构也创建出来。
脚本内容如下：
#!/bin/bash
JSON_FILE=~/api/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' )"
cat >>"$foldername.rst" <<EOF
Contents:
.. toctree::
:maxdepth: 3
:titlesonly:
:glob:
$( echo "$names" | sed "s#^# $foldername/#" )
EOF
mkdir -p "$foldername"
pushd "$foldername"
while read cid
do
children $cid
done < <(echo "$ids")
popd
}
#a：为第一级目录的id
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
查看下内容。
最后就是根据具体情况，做一些细微的调整了。
MISC
–END
以上就是本文的全部内容，希望本文的内容对大家的学习或者工作能带来一定的帮助，也希望大家多多支持 码农网
本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。
Compilers
Alfred V. Aho、Monica S. Lam、Ravi Sethi、Jeffrey D. Ullman / Addison Wesley / 2006-9-10 / USD 186.80
This book provides the foundation for understanding the theory and pracitce of compilers. Revised and updated, it reflects the current state of compilation. Every chapter has been completely revised ......一起来看看 《Compilers》 这本书的介绍吧!
