sphix

1,466 views

Published on

0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,466
On SlideShare
0
From Embeds
0
Number of Embeds
13
Actions
Shares
0
Downloads
6
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

sphix

  1. 1. 用 Sphinx 编写文档 杜文山 知识淘宝网 软件工程师 电子邮件: [email_address] 2009 年 7 月 25 日
  2. 2. 演讲内容 <ul><li>Sphinx 简介 </li></ul><ul><li>功能 </li></ul><ul><li>文档编排方法 </li></ul><ul><li>内容编写方法 </li></ul><ul><li>例子 </li></ul><ul><li>软件安装和运行 </li></ul><ul><li>实际演示 </li></ul><ul><li>高级技巧 </li></ul>
  3. 3. Sphinx 简介 简介 : Sphinx 是一个用 Python 开发的文档编写工具,能够帮助你编写智能并且美观的文档。编写文档时,只在文本文件中加入一些简单的标记符号 (reStructuredText) ,然后通过调用命令智能处理,最终生成 HTML 网页格式或其它格式文件。 英文发音 : [sfiŋks] ,【希神】斯芬克斯, [ 埃 ] 狮身人面 用途 :编写文档 (C/C++ , Java , Python 等等 ) ,电子图书,生成静态网页,提高编写和维护文档的效率。 网址 : http://sphinx.pocoo.org/ 作者 : Georg Brandl 许可协议 : BSD 典型用户 : Python 官方文档, Django , SQLAlchemy , Zope3 等等
  4. 4. 功能 <ul><li>通过使用 扩展的 reStructuredText 标记实现文档的编写 </li></ul><ul><li>支持多种输出格式: HTML ( 包括 Windows HTML Help) , LaTeX , PDF </li></ul><ul><li>智能的链接引用 函数、类等等程序代码中的信息 </li></ul><ul><li>轻松的定义文档的层次结构,并做出相应的链接,比如:上一页,下一样等等功能。 </li></ul><ul><li>自动生成索引 </li></ul><ul><li>代码自动处理,通过 Pygments 模块,加亮显示程序代码 </li></ul><ul><li>支持多种扩展功能,比如:搜索,模板定制等等 </li></ul>
  5. 5. 文档编排方法 <ul><li>编写多个文本文件,通过使用 toctree 标记,组成整个文档 </li></ul><ul><li>例如:主文件叫做 index.txt ,有三个章,当前目录下分别对应文件 ch1.txt , ch2.txt , ch3.txt ,那么在 index.txt 中加入以下字符,即可显示章节目录: </li></ul>.. toctree:: :numbered: ch1 ch2 ch3
  6. 6. 内容编写方法 <ul><li>采用扩展的 reStructuredText 标记实现,基本上只要按照普通的文本文件编写方式即可。 </li></ul><ul><li>段落之间用空行分开 </li></ul><ul><li>斜体: *text* ,粗体: **text** ,引用: ``text`` </li></ul><ul><li>列表: 空格加上 * 号,或数字符号 </li></ul><ul><li>源代码: 两个冒号,空行分隔缩进 </li></ul><ul><li>链接: `Link text <http://target>`_ </li></ul><ul><li>章节标题: 标题下边加上等长的 # * = - 等符号 </li></ul><ul><li>图片: .. image:: gnu.png </li></ul><ul><li>更多方法,请参考主页文档 </li></ul>
  7. 7. 例子 <ul><li>程序的基本概念 </li></ul><ul><li>============== </li></ul><ul><li>程序和编程语言 </li></ul><ul><li>-------------- </li></ul><ul><li>程序( Program )是一个精确说明如何进行计算的指令序列。 </li></ul><ul><li>.. image:: intro.compile.png </li></ul><ul><li>自然语言和形式语言 </li></ul><ul><li>------------------ </li></ul><ul><li>** 自然语言 ** 就是人类讲的语言,比如汉语、英语和法语。 C 语言例子: </li></ul><ul><li>例 1.1. Hello World </li></ul><ul><li>:: </li></ul><ul><li>#include <stdio.h> </li></ul><ul><li>int main(void) </li></ul><ul><li>{ </li></ul><ul><li>printf(&quot;Hello, world. &quot;); </li></ul><ul><li>return 0; </li></ul><ul><li>} </li></ul>
  8. 8. 软件安装和运行 <ul><li>方法一: easy_install sphinx </li></ul><ul><li>方法二: Windows 用户下载 http://www.baow.com/soft/baow.zip ,其中打包了 Python2.6 和例子,只要解压缩到 c 盘目录下就行了 </li></ul><ul><li>配置文件: conf.py </li></ul><ul><li>例子运行命令: build.bat </li></ul><ul><li>sphinx-build -b html linux_c_src linux_c_html </li></ul>
  9. 9. 实际演示
  10. 10. 高级技巧 <ul><li>演示结合 Firefox 和 VIM 编写文档 </li></ul><ul><li>生成文档 </li></ul><ul><li>VIM 支持 reStructuredText 文本的加亮显示,建议用 VIM 编辑器编辑 </li></ul>
  11. 11. 结 束 <ul><li>杜文山 </li></ul><ul><li>[email_address] </li></ul>

×