Sphinx 的高级用法

Sphinx 的高级用法:
    1,Sphinx 的配置文件 conf.py, 在这里你可以配置Sphinx各个方面，使Sphinx按照你的要求读取源文件并创建文档.
    2,Sphinx 主要功能是使用 reStructuredText, 把许多文件组织成一份结构合理的文档.
一，在index.html增加索引目录
    index.rst 同级目录下的 .rst 结尾文件 去掉文件后缀名
    maxdepth 表示最大二级目录

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   exmple
   exmple1
   exmple2
   exmple3

二，为'.py'文件自动生成 html 文档
    在 conf.py 文件之中配置,相对于 当前 conf.py 文件的 '.py'文件

   import os
   import sys 
   sys.path.insert(0, os.path.abspath('..'))

在指定要显示的 .rst 文件之中， run.py 就是要生成文档的'.py'文件

.. automodule:: run
   :members:

三,为生成的文档配置主题

    # Sphinx 提供三个主题 默认主题 alabaster
    # 安装 sphinx_rtd_theme 主题
    # pip install sphinx_rtd_theme

    # 在 conf.py 之中更改主题
    html_theme = 'sphinx_rtd_theme'

四, 增加 logo 图片 自带了一个logo 位置

    # 在 conf.py 之中指定 logo 图片 ,相对于 conf.py 的文件路径
    html_logo = './_static/logo.jpg'

五, 函数在文档之中展示
    1, 一般只需要使用 '::' 就可以(不加函数说明), 或者'::' 前面加上文字表明 函数说明
    2, 也可以使用 code-block 增加 其他功能 比如语法高亮
    3, 定义与 函数之间是像段落的关系 注意加上空格

::

    def say():
        print('hello world!')

source code again

Can add extra features when use code-block

.. code-block::
    :linenos:
    :emphasize-lines: 3,6

    is_directory()
       {
          DIR_NAME=$1
          if [ ! -d $DIR_NAME ]; then
             return 1
          else
             return 0
          fi
       }

六,引用和脚注
    1,在语句之中 使用 '[文字]_' 可以使用 '..[文字]' 为文字添加修饰 
    2, #f1 以 # 开头显示的是数字 数字实现自动增长

It is methioned by [Ref]_ that python is good.

.. [Ref] 《talk is good》

orem ipsum [#f1]_  dolor sit amet ... [#f2]_

Footnotes

.. [#f1] Text of the first footnote.
.. [#f2] Text of the second footnote.

七,替换
    1,在正文中使用'|文字|'这样标签，然后可以设定使用其他文本或者图片来代替'文字'这个占位符

I like eat |apple| very much.

.. |apple| replace:: orange

八, 生成类的文档:
    1, 可以按照以下格式定义 你可以紧挨着也可以 另起一行对齐
    2, ' py:decorator:: ' 指的是装饰器 另起一行 对一个类之中的装饰器进行说明

.. py:class:: Foo(object):
   .. py:method:: quux()
   .. py:attribute:: name
   .. py:staticmethod:: name(signature)
   .. py:classmethod:: name(signature)

.. py:decorator:: removename

   Remove name of the decorated function.

.. py:decorator:: setnewname(name)

   Set name of the decorated function to *name*.

 

九,通常将有用的命令或者代码 进行阴影化

Code emphasis ::

   # ls -l
   # find . -perm -7 -print | xargs chmod o-w
   # ls -l

项目具体使用参考 githup

# 以上代码存放位置
https://github.com/shiqilouyang/sphinx_doc

# 一个项目文档参考
https://github.com/me115/linuxtools_rst