阿小信大人的头像
做你说过的,说你能做的 阿小信大人

Sphinx笔记2014-12-22 18:17

安装:

sudo pip install Sphinx

创建文档模板结构:

sphinx-quickstart

按照需求回答一些问题后会生成模板结构,然后进入你的source目录,编辑自己的.rst文件后加到index.rsttoctree下。

完成后如果你选择了生成makefile直接运行: make html可以生成网页。

没有makefile则运行:

sphinx-build -b html source build

toctree

自定义toctree元素显示的名字(针对html有效,pdf测试失败)

.. toctree::

   tt <tutorial>
   bd <http://www.baidu.com>

这样会显示成前面的字链接到文件,直接给url时,必须加http://

maxdepth是toctree的层数,即如果为2,则intro.rst中还有toctree的话也会显示在index.rst中。默认为全部层数

除了maxdepth外,还有其他设置,比如

  • :numbered:是给tree元素显示数字标号
  • :glob:可以使用通配符匹配文件名
  • :hidden:生成链接但是不显示
  • :includehidden:显示为被隐藏的链接

使用LaTeX和CJK自带字体生成PDF

修改conf.pylatex_elements

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    'preamble': '''
        \\hypersetup{unicode=true}
        \\usepackage{CJKutf8}
        \\AtBeginDocument{\\begin{CJK}{UTF8}{gbsn}}
        \\AtEndDocument{\\end{CJK}}
        \\usepackage{indentfirst}
        \\setlength{\parindent}{2em}
    '''
}

然后执行:

make latexpdf

如果报错也许是需要安装一下依赖:

sudo apt-get install texlive-full

自带字体中,gbsn是简体宋体、gkai是简体楷体、bsmi是繁体明体、bkai是繁体楷体

段落级标记

.rst文件内容如下:

.. note::

  【.. note::】的效果

note::

  【note::】的效果,【::】前面的字符可随意替换

.. warning::

  【.. warning::】的效果

.. versionadded:: 1.0.0

  【.. versionadded:: 1.0.0】的效果

.. versionchanged:: 1.0.0

  【.. versionchanged:: 1.0.0】的效果

.. deprecated:: 1.0.0

  【.. deprecated:: 1.0.0】的效果

.. seealso::

  【.. seealso::】的效果

.. glossary::

   term 1
      【.. glossary::】的效果,一面的文字以缩进作为分级
         的标题

   term 2
      Definition of both terms.

.. _my-reference-label:

   标题1
   ============================

   文字。。。。

   标题上方必须有_开头的引用标签+空行 【`.. _my-reference-label:`】

   任意位置交叉引用 ref 【``:ref:`my-reference-label```,不要``_``】 :ref:`my-reference-label`.这样会根据标题内容生成一个链接

下载文件

【`:download:`this example script <test.py>``】

:download:`this example script <test.py>`.

链接一个doc:

【``:doc:`ch1```】 :doc:`ch1`

:fieldname: Field content 【``:fieldname: Field content``】
:testname: testname

其生成的html效果如图:

显示代码

.. code-block:: <LANG> 指定代码类型,none表示不高亮,guess你懂得

.. literalinclude:: <FILE>引入文件内容

.. code-block:: python
   :linenos:

   def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one is not...'
       print '...but this one is.'

.. literalinclude:: test.py
   :language: python
   :linenos:
   :encoding: utf-8
   :lines: 1,3,5-10,20-
  • linenos:显示行号
  • language:高亮语法
  • encoding:文件编码
  • lines:显示指定行的代码,以上为显示第一行,第三行,第五到十行,第二十行至结尾

通过在Python代码中用sphinx的python domain语法写docstring后可以使用

 sphinx-apidoc -o ./docs ./json2xls

会为json2xls下的每个模块生成docstring的rst文档,进入docs文件夹后make html可以生成对应的网页。

rtd

使用https://readthedocs.org可以根据你设置的仓库地址自动的更新docstring生成在线文档,cool。

生成docstring的rst文档后,先注册帐号,然后授权github什么的,然后从github引入项目,点击create,填写信息就ok了。

看我生成的:http://json2xls.readthedocs.org/en/latest/

如果您觉得从我的分享中得到了帮助,并且希望我的博客持续发展下去,请点击支付宝捐赠,谢谢!

若非特别声明,文章均为阿小信的个人笔记,转载请注明出处。文章如有侵权内容,请联系我,我会及时删除。

#Linux/Mac#  
分享到:
阅读[1446] 评论[0]

你可能也感兴趣的文章推荐

本文最近访客

发表评论