[Python] 开源的很多文档都是用Sphinx做的,很不错

博客首页 » Python 开源的很多文档都是用Sphinx做的,很不错

发布于 26 Sep 2015 11:35
标签 blog
现Python开源的很多文档都是用Sphinx做的,很不错,像WIKI。

这里有一片介绍Sphinx的文章。

sphinx-quickstart 
 
tree .
.
├── Makefile
├── _build
├── _static
├── conf.py
└── index.rst
  • Makefile:编译过代码的开发人员应该非常熟悉这个文件,如果不熟悉,那么可以将它看作是一个包含指令的文件,在使用 make 命令时,可以使用这些指令来构建文档输出。
  • _build:这是触发特定输出后用来存放所生成的文件的目录。

_static:所有不属于源代码(如图像)一部分的文件均存放于此处,稍后会在构建目录中将它们链接在一起。

  • conf.py:这是一个 Python 文件,用于存放 Sphinx 的配置值,包括在终端执行 sphinx-quickstart 时选中的那些值。
  • index.rst:文档项目的 root 目录。如果将文档划分为其他文件,该目录会连接这些文件。

下面,编辑这个example.rst
example.rst

This is a Title
===============
That has a paragraph about a main subject and is set when the '='
is at least the same length of the title itself.
 
Subject Subtitle
----------------
Subtitles are set with '-' and are required to have the same length 
of the subtitle itself, just like titles.
 
Lists can be unnumbered like:
 
 * Item Foo
 * Item Bar
 
Or automatically numbered:
 
 #. Item 1
 #. Item 2
 
Inline Markup
-------------
Words can have *emphasis in italics* or be **bold** and you can define
code samples with back quotes, like when you talk about a command: ``sudo`` 
gives you super user powers!

添加到index.rst中,并且编译。

echo example >>> index.rst
 
make html 
 
firefox _build/HTML/index.html

这样就可以看到下面这样的HTML了。

figure001.jpg

Reference:
http://www.ibm.com/developerworks/cn/opensource/os-sphinx-documentation/


本页面的文字允许在知识共享 署名-相同方式共享 3.0协议和GNU自由文档许可证下修改和再使用,仅有一个特殊要求,请用链接方式注明文章引用出处及作者。请协助维护作者合法权益。


系列文章

文章列表

  • Python 开源的很多文档都是用Sphinx做的,很不错

这篇文章对你有帮助吗,投个票吧?

rating: 0+x

留下你的评论

Add a New Comment