sphinx使用学习笔记

1.

去Python官方网站下载安装python

https://www.python.org/downloads/

2.

安装完成后，在python的scripts目录下，可以看到一个叫做easy_install sphinx的可执行文件或是easy_install-3.4，在命令行里执行它

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

执行过程时间较长，可能出现easy_install sphnix the read operation timed out

这个可能是网络问题也可能是由于没有安装setuptools工具导致的

setuptool下载

https://pypi.python.org/pypi/setuptools#downloads 

拖到最后有三个附件，下载最后一个setuptools-28.3.0.zip (md5）

 下载后解压到Python安装目录下即可

3.

easy_install sphinx执行完成后

命令行会提示Finished Processing dependencies for shinx，说明配置成功。

4.

此时在命令行输入sphinx-build,看看是否会出来说明信息

如果在安装python时，没有设置环境变量，可能会弹出sphinx-build不是内部或者外部命令。

需要在计算机的属性-高级系统设置-高级中 添加系统环境变量path路径是python目录下的scripts。

再次执行会有相关信息，说明完成了。

5.

完成后可以使用sphinx自带的配置工具建立sphinx工程

在d盘新建一个工程文件如demo

命令行进入demo 在demo下输入sphinx-quickstart

出现欢迎信息，大部分配置使用默认即可 ，即一直回车即可

分离source和build目录，输入y  方便管理，

输入工程名、作者名、版本号等,其余回车

完成后可以看到demo目录下有以下文件：make.bat  文件makefile、文件夹source、文件夹build 

^在demo目录命令行下输入make html， 生成html。源文件是rst格式 在source下，生成的HTML在build下

 ^在demo目录命令行下输入make latex，生成tex格式文件在build中的latex下，将tex格式文件用TeXworks软件打开，使用

XeLateX或pdfTex可以生成pdf文件

6.

rst源文件中，文档编辑的常见符号有

文档标题
========

一级标题

--------------

一个星号  *text*为重点 （斜体）

两个星号 **text**强调 (加粗)

\ **text** \ 加粗后去掉空格 \和*之间有一个空格

反引号 ``text`` 代码样本

* 标题

要点

二级标题

~~~~~~~~~~~~~~~

三级标题

``````````````````````````

线块

|这个是线块

|是保留换行符的一种方式

插入文本框注解

.. note:: 内容

导航

在开头处:

* 第 21 页，:ref:`简介_jj`

在导航位置的文章内容前：

.. _简介_jj:

插入表格

.. list-table:: 
   :widths: 15,25,20
   :header-rows: 1

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

插入图片

.. image:: _static/4-2/1.png

图片保存在source中的_static中

目录树

.. toctree::
   :maxdepth: 2

  4.1总体介绍.rst
  4.2可用性.rst
  4.3数据服务.rst

maxdepth表示目录的层数，index文件是第三层，是主目录

这是第二层，属于主目录第四章的目录

7.

conf.py配置

封面

latex_documents = [
   # (master_doc, 'h.tex', 'h Documentation',
   #  'xinrf1', 'manual'),
    ('index', 'h1000.tex', u'{产品测试报告}',
   u'\\unexpanded{ 公司 }', 'manual'),
]
latex_logo = '_static/lenovoimagemovement.jpg'

修改字体格式 字号等

latex_elements = {
    'papersize': 'a4paper',
    'pointsize': '11pt',
    'fncychap' : u'\\usepackage[Sonny]{fncychap}',
    'releasename':  u'版本',
    'indexname': u'索引',
    'preamble' : u'''
\\usepackage{fontspec,xltxtra,xunicode}
\\usepackage{xeCJK}
\\xeCJKsetup{LocalConfig=false}
\\xeCJKsetup{AutoFallBack=true}
\\xeCJKsetup{AutoFakeBold=true}
\\xeCJKsetup{AutoFakeSlant=true}
\\xeCJKsetup{CheckFullRight=true}
\\setCJKmainfont[AutoFakeBold,AutoFakeSlant]{方正书宋简体}
\\setCJKsansfont[AutoFakeBold,AutoFakeSlant]{方正黑体简体}
\\setCJKmonofont[AutoFakeBold,AutoFakeSlant]{方正楷体简体}
\\defaultfontfeatures{Scale=MatchLowercase}
\\setmainfont[Mapping=tex-text]{Gotham}
\\setsansfont[Mapping=tex-text]{Gotham} 
\\setmonofont{Courier}
\\addto\\captionsenglish{
    \\renewcommand{\\contentsname}{目录}
    \\renewcommand{\\listfigurename}{插图目录}
    \\renewcommand{\\listtablename}{表格目录}
    \\renewcommand{\\refname}{参考文献}
    \\renewcommand{\\abstractname}{摘要}
    \\renewcommand{\\indexname}{索引}
    \\renewcommand{\\tablename}{表}
    \\renewcommand{\\figurename}{图}
}
'''
}