使用 sphinx 制作简洁而又美观的文档

最近需要将API中的doc生成html给前端工程师参考调用。

于是粗率的学习了下sphinx


Sphinx 是用 Python 编写的,并且最初是为 Python 语言文档而创建,但它并不一定是以语言为中心,在某些情况下,甚至不是以程序员为中心。Sphinx 有许多用处,比如可以用它来编写整本书! 要求

  • 安装: pip install sphinx

语法

  • Sphinx 使用 reStructuredText 标记语法类似与Markdown
  • 具体可查看: http://zh-sphinx-doc.readthedocs.org/en/latest/rest.html

实战

  • 项目结构 # tree -L 1 . ├── bin ├── etc ├── ops ├── setup.py └── example
  • 建立docs目录 # tree -L 1 . # mkdir docs ├── bin ├── docs ├── etc ├── ops ├── setup.py └── example
  • 根据py代码生成rst风格文件,这里我只生成ops/api/contrib下面的py文档 # sphinx-apidoc -F -o docs/ ops/api/contrib Creating file doc/contrib.rst. Creating file docs/conf.py. Creating file docs/index.rst. Creating file docs/Makefile. Creating file docs/make.bat.

sphinx-apidoc具体用法参考:

http://zh-sphinx-doc.readthedocs.org/en/latest/invocation.html#sphinx-apidoc

安装readthedocs主题

# pip install sphinx_rtd_theme

编辑conf.py

    import sphinx_rtd_theme
    html_theme = "sphinx_rtd_theme"
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

在下一步生成html时,会尝试将你的项目导入并运行,因此需要将你的项目添加至python的环境变量中 编辑conf.py

    sys.path.append(os.path.join([os.getcwd(), "../ops/api"]))

根据生成的rst文件生成html

    # cd docs
    # mkdir html
    # sphinx-build . html

sphinx-build具体用户参考:

http://zh-sphinx-doc.readthedocs.org/en/latest/invocation.html

自定义生成文档的类或方法

  • Domain.py源代码: class domains(tornado.web.RequestHandler): def get(self): """ 根据提交的参数类型, 返回匹配到的记录列表 如果没有提交任何参数, 返回所有的域名列表 ip 合法的ipv4或ipv6的值, 返回解析是此IP的记录列表 domain 完整的域名格式(记录 + 域名), 返回此域名下的所有解析列表 domain_id 返回此域名id下的所有记录列表 CLI Example:: curl -X GET http://URL/domain?ip=1.1.1.1 返回参考: * JSON:: [ { "id":"16894439", "name":"@", "line":"\u9ed8\u8ba4", "type":"A", "ttl":"600", "value":"1.1.1.1", "mx":"0", "enabled":"1", "status":"enabled", "monitor_status":"", "remark":"", "updated_on":"2012-11-23 22:17:47" }, ] """ self.write("hello")

生成domains类中get, post, put, delete方法

  • 编辑contrib.rst contrib.Domain module ------------------- .. automodule:: contrib.Domain 从contrib.Domain中生成文档 :undoc-members: 如果没有文档就不显示 .. autoclass:: domains 指定只生成domains类中的文档 :members: get, post, put, delete

指定只生成这几个方法的文档

  • 效果

原文发布于微信公众号 - 马哥Linux运维(magedu-Linux)

原文发表时间:2015-12-10

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏容器云生态

企业网站架构之Nginx+tomcat+memcached集群

nginx+tomcat+memcached应用 系统环境:RHEL6.4  x64   iptables -F   and selinux is disab...

33080
来自专栏程序员互动联盟

【专业技术】8大你不得不知的Android调试工具

1. 查看当前堆栈 1) 功能:在程序中加入代码,使可以在logcat中看到打印出的当前函数调用关系 2) 方法: new Exception(“print ...

709130
来自专栏前端杂货铺

服务端事件EventSource揭秘

服务端推 服务端推,指的是由服务器主动的向客户端发送消息(响应)。在应用层的HTTP协议实现中,“请求-响应”是一个round trip,它的起点来自客户端,因...

34350
来自专栏小樱的经验随笔

【批处理学习笔记】第十一课:常用DOS命令(1)

【 文件夹管理 】 cd 显示当前目录名或改变当前目录。 md 创建目录。 rd 删除一个目录。 dir 显示目录中的文件和子目录列表。 tree 以图形显示驱...

28960
来自专栏Albert陈凯

2018-11-19 Neo4j百万级数据导入只能用neo4j-import

业务需要使用Neo4j出数据关系展示图,数据库里有2张表通过一个字段进行关联,数据量是90万和500万,关系量是150w;

17020
来自专栏xiaoxi666的专栏

阅读Java Native源码前的准备

读java native源代码时,我们一般会去网站下载openjdk8源码http://download.java.net/openjdk/jdk8/promo...

10720
来自专栏乐沙弥的世界

Percona XtraDB Cluster GCache和Record-Set缓存

在Percona XtraDB集群中,有一个GCache和Record-Set缓存(也可称为事务写集缓存)的概念。如果您正在运行长事务,那么使用这两个缓存通常会...

13800
来自专栏IT技术精选文摘

文件句柄与文件描述符

1.概述 在实际工作中会经常遇到一些bug,有些就需要用到文件句柄,文件描述符等概念,比如报错: too many open files, 如果你对相关知识一无...

76370
来自专栏Java帮帮-微信公众号-技术文章全总结

集群间如何实现session共享【面试+工作】

4.2K80
来自专栏L宝宝聊IT

VBR的部署

23050

扫码关注云+社区

领取腾讯云代金券