Python中文档Sphinx的使用

安装软件包

$ pip install Sphinx

生成模板

# 大部分默认即可
$ sphinx-quickstart

此时可以看到生成的文件为：

➜  docs git:(master) ✗ ls 

_build    _static   Makefile                                         
_templates   conf.py  index.rst

此时查看index.rst文件

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


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

输出文件

# 生成html文件
$ make html
# 生成pdf文件
$ make latexpdf

新增文件

此时新增一个文档和图片

touch hello.rst
cp test.png _static/test.png

更新index.rst文件，注意缩进

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

   hello.rst
   
.. image:: _static/test.png

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

更新模板

可以通过修改_static/default.css和_templates/layout.html来修改和定制网站的外观。

多语种支持

安装软件

$pip3 install sphinx-intl

增加下列信息到conf.py，

locale_dirs = ['locale/']
gettext_compact = False

生成pot文件

make gettext

生成po文件

$ sphinx-intl update -p _build/gettext -l en

此时就能看到在文件locale/en/LC_MESSAGES中的信息

构建翻译的文档

$ make -e SPHINXOPTS="-D language='en'" html

Be sure to say yes to autodoc

More information can refer [http://www.matplotlib.org/sampledoc]