使用 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 条评论
登录 后参与评论

相关文章

来自专栏IMWeb前端团队

Nodejs进阶:如何玩转子进程(child_process)

本文作者:IMWeb 陈映平 原文出处:IMWeb社区 未经同意,禁止转载 模块概览 在node中,child_process这个模块非常重要。掌握了...

4628
来自专栏重庆的技术分享区

如何在Ubuntu 16.04上安装和配置Redis集群

Redis集群已经发展成为缓存,队列等的流行工具,因为它具有可扩展性和速度的潜力。本指南旨在使用三个Linode创建一个集群来演示分片。然后,如果发生故障,您将...

1326
来自专栏Albert陈凯

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

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

972
来自专栏backend技术总结

微信小程序demo开发总结

github: https://github.com/tencentyun/wafer-session-server

3774

Web服务器压力测试工具Siege

Siege是一款HTTP压力测试和基准测试的实用工具,可用于在压力条件下对Web服务器的性能进行测量。它的评估依据包括传输数据量、服务器的响应时间、事务处理速率...

2293
来自专栏乐沙弥的世界

Percona XtraDB Cluster GCache和Record-Set缓存

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

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

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

2.7K8
来自专栏容器云生态

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

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

3028
来自专栏大数据实战演练

Ambari自定义服务干货

                    “ ambari自定义服务干货,非常干的那种”

4262
来自专栏L宝宝聊IT

VBR的部署

1845

扫码关注云+社区