使用Sphinx生成/管理文档

栏目: 编程工具 · 发布时间: 7年前

内容简介：很多开源的软件都使用Sphinx来进行文档的管理，其中Ansible就是其中一个。Sphinx使用类MarkDown的reStructuredText格式来进行内容的编写，然后使用 sphinx-build 命令来生成html文件。先使用 html2rest 把html转成reStructuredText格式。

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

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

安装、入门

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

以上就是本文的全部内容，希望本文的内容对大家的学习或者工作能带来一定的帮助，也希望大家多多支持码农网

查看所有标签

猜你喜欢:

本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。

码农书籍

Masterminds of Programming

Federico Biancuzzi、Chromatic / O'Reilly Media / 2009-03-27 / USD 39.99

Description Masterminds of Programming features exclusive interviews with the creators of several historic and highly influential programming languages. Think along with Adin D. Falkoff (APL), Jame......一起来看看《Masterminds of Programming》这本书的介绍吧!

码农工具