内容简介：很多开源的软件都使用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
以上就是本文的全部内容，希望本文的内容对大家的学习或者工作能带来一定的帮助，也希望大家多多支持 码农网
猜你喜欢:
- 在 Laravel 中集成 API 文档生成器扩展包为 Dingo API 接口生成文档
- Java 生成 PDF 文档
- 文档生成器 mkdocs
- Doxygen 3 发布，文档生成工具
- 如何使用 sphinx 来生成代码文档
- Python 文档生成器 mkdocs
本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。
