阿哥论坛

 找回密码
 立即注册

QQ登录

只需一步,快速开始

新浪微博账号登陆

只需一步,快速开始

搜索
查看: 772|回复: 0

使用sphinx记笔记-it论坛

[复制链接]

2019

主题

1

好友

1万

积分

管理员

Rank: 9Rank: 9Rank: 9

优秀会员 助人为乐 辛勤工作 技术精英 多才多艺 优秀班竹 灌水天才 星球管理 宣传大使 灌水之王 财富勋章 版主勋章 动漫勋章 勤奋会员 论坛精英 PS高手 心 8 闪游皮肤 双鱼座 8★8➹ 志愿者 乖

发表于 2013-12-27 12:46:40 |显示全部楼层
使用sphinx记笔记-it论坛
sphinx简介 简单来说,这是一个基于ReStructuredText的文档生成工具。方便易用,功能强大。
有很多开源工程都采用sphinx作为文档生成系统,最有名的就是 python官方文档 。 在 sphinx官方 网站 上也列出使用sphinx的项目,有将近90个左右,其中不乏大名鼎鼎的开源项目。
一些中文的翻译项目也采用了sphinx,如 pymotwcn

安装 it论坛
1. 安装Python
2. 要确认已经安装了setuptools
  • 如果已经安装,你在python安装路径下的Scripts文件夹下会找到一个easy_install.exe。
  • setuptools下载
3. 在命令行输入easy_install sphinx it论坛

  • easy_install可以自动下载并安装sphinx以及它所依赖的其他模块。

  建立sphinx工程 建议使用sphinx自带的配置工具sphinx-quickstart。 - 建立一个工程目录,比如D\:Note。 - 在该目录启动命令行,输入sphinx-quickstart
D:\Note>sphinx-quickstart
  • 程序会提示输入一些选项,如输入根目录
    [url=][/url]
    Welcome to the Sphinx quickstart utility.

    Please enter values
    for the following settings (just press Enter to
    accept a
    default value, if one is given in brackets).

    Enter the root path
    for documentation.
    > Root path for the documentation [.]:

    [url=][/url]

    大部分使用默认选项,直接按回车即可。
  • 需要指定的选项
    • 分离source和build目录,方便管理
      > Separate source and build directories (y/N) [n]: y


    • 指定工程名、作者名、版本号
      [url=][/url]
      The project name will occur in several places in the built documentation.
      > Project name: Note
      > Author name(s): LK

      Sphinx has the notion of a
      "version" and a "release" for the
      software. Each version can have multiple releases.
      For example, for
      Python the version is something like
      2.5 or 3.0, while the release is
      something like
      2.5.1 or 3.0a1.  If you don't need this dual structure,
      just set both to the same value.
      > Project version: 0.1
      > Project release [0.1]:

      [url=][/url]


    • 文档文件的后缀名,默认是.rst,个人认为用.txt更方便些。
      The file name suffix for source files. Commonly, this is either ".txt"
      or
      ".rst".  Only files with this suffix are considered documents.
      > Source file suffix [.rst]: .txt



  • 完成后,可以看到Note目录下有以下目录和文件
    • build目录 运行make命令后,生成的文件都在这个目录里面
    • source目录 放置文档的源文件
    • make.bat 批处理命令
    • makefile
  • 基本完成了,使用make html命令就可以生成html形式的文档了。


配置(conf.py)conf.py文件包含了sphinx工程的所有配置选项,包括一些无法在sphinx-quickstart中进行设置的。
分为三部分:
  • General configuration(一般选项)
  • Options for HTML output(HTML输出选项)
  • Options for LaTeX output(Latex输出选项)
下面是一些常用的选项:
  • language (语言) 对应于sphinx的locale目录下的文件夹,里面是本地化配置。
    官方版本只支持繁体中文(zh_TW),可以下载 sphinx简体中文包JavaEye topman制作)
    下载后放到locale目录下,然后language选项修改为zh_CN即可
  • html_theme (输出html的主题):
    # The theme to use for HTML and HTML Help pages.  Major themes that come with
    #
    Sphinx are currently 'default' and 'sphinxdoc'.
    html_theme = 'sphinxdoc'





常用的文档格式符号下面只是列出了一些常用的格式符号,以供大家参考,详细的教程可以参照《reStructuredText 简明教程》 (以下基本上是从该教程直接引用过来的)。
标题ReStructuredText会根据下划线读取文档的标题,并且可以自动组织索引
[url=][/url]
=====================
文档标题
=====================

--------
子标题
--------

章节标题
========

...

[url=][/url]


列表列表中,相同的层级使用相同的缩进。
列表中同一层级不需要空行分隔。不同层级起始处必须有空行。
[url=][/url]
列表:
  
- 条目
  
- 条目

      
- 条目
      
- 条目
  
- 条目
[url=][/url]


超链接
独立链接 ,自动将网址转换为链接。
例如 http://www.ubuntu.org.cn/

http://www.ubuntu.org.cn/


命名链接 ,为链接命名,有助记忆和减少空间占用。
在正文中使用 <链接名>_ ,注释中使用 _<链接名>: [链接目标]
例如 Ubuntu
Ubuntu_

.. _Ubuntu:  http:
//www.ubuntu.org.cn/



代码sphinx对嵌入程序代码的支持很好(本来就是为了编写python文档而开发的工具)。
在段落的结尾添加符号 :: ,则表明下面的段落为代码段落。代码段落相对之前的段落要缩进一次。

文本只要没有空行,不管换多少次行,都会处理为一行。 建议您将每行的内容控制在50个汉字或者100个字母之内, 尽量在标点符号处手动换行,以增加源文件的可读性。


其他暂时没有发现支持ReStructuredText的Blog,不知道大家有没有知道的。如果能直接用ReStructuredText写Blog 就太好了。

参考教程A ReStructuredText Primer


摘自:http://www.cnblogs.com/Lvkun/archive/2010/04/01/1702245.html

该会员没有填写今日想说内容.
您需要登录后才可以回帖 登录 | 立即注册 新浪微博账号登陆

回顶部