使用Sphinx生成/管理文档

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

内容简介：很多开源的软件都使用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

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

查看所有标签

猜你喜欢:

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

码农书籍

小团队构建大网站：中小研发团队架构实践

张辉清等 / 电子工业出版社 / 2019-1 / 69

《小团队构建大网站：中小研发团队架构实践》结合作者近几年的工作经验，总结了一套可直接落地、基于开源、成本低、可快速搭建的中小研发团队架构实践方法。《小团队构建大网站：中小研发团队架构实践》共5篇22章，开篇是本书的导读；架构篇是设计思想的提升，包括企业总体架构、应用架构设计、统一应用分层等；框架篇主讲中间件和工具的使用，包括消息队列、缓存、Job、集中式日志、应用监控和微服务等；公共应用篇是技术与......一起来看看《小团队构建大网站：中小研发团队架构实践》这本书的介绍吧!

码农工具