记录-Sphinx自动生成Python项目文档

Pre:

try一下Sphinx这个自动生成Python项目文档的工具

---

安装与简介:

sphinx简介:

sphinx是一种基于Python的文档工具，它可以令人轻松的撰写出清晰且优美的文档，由Georg Brandl在BSD许可证下开发。

新版的Python3文档就是由sphinx生成的，并且它已成为Python项目首选的文档工具，同时它对C/C++项目也有很好的支持。

安装:

# 安装Sphinx
pip3 install Sphinx -i https://mirrors.aliyun.com/pypi/simple/

---

建一个测试项目:

其中1.py代码:

# -*-coding:utf-8-*-

class Test1():
    '''
    我是测试类，负责测试
    '''
    def hello(self):
        '''
        负责打印Hello， 人人可以学Python
        :return: 
        '''
        print("人人可以学Python")
    def renren(self):
        '''
        测试Sphinx自动生成文档
       
        :return: 
        '''
        print("自动生成文档")
class Test2():

    def test_2(self):
        '''
        我也不知道写什么好，反正我们这里是用来写文档的
        :return: 
        '''
        print("文档自动生成测试2")
    def renren_2(self):
        '''
        所以我们开发的时候就应该在这里写好文档，然后用Sphinx自动生成

        :return: 
        '''
        print("自动生成文档2")

2.py代码:

# -*-coding:utf-8-*-

def init_test():
    '''
    用于初始化项目测试，不需要任何参数
    :return: 
    '''
    print("初始化项目")


def start():
    '''
    启动项目入口，
    :return: 
    '''
    test(3)

def test(v):
    '''
    项目运行主要函数，需要传入一个参数\n
    v:<int>
    :return: 
    '''

    print(v)

---

使用Python-Sphinx doc:

选择配置

# 创建一个doc目录
mkdir doc

# 初始化sphinx项目
[root@localhost doc]# sphinx-quickstart

如果找不到命令的话:

[root@localhost doc]# sphinx-quickstart
-bash: sphinx-quickstart: command not found

建立一个软链接或直接使用绝对路径

# 1.建立软链接:
[root@localhost doc]# ln -s /usr/local/python3/bin/sphinx-quickstart /usr/bin/sphinx-quickstart

# 2.使用绝对路径
[root@localhost doc]# /usr/local/python3/bin/sphinx-quickstart

除了以下项目外，其他的我都使用了默认值：

[root@localhost doc]# /usr/local/python3/bin/sphinx-quickstart
Welcome to the Sphinx 3.1.2 quickstart utility.

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

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.
> Project name: auto_try
> Author name(s): fatboy
> Project release []: 1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: zh_cn

Creating file /jscan/tools_/auto_doc_try/doc/source/conf.py.
Creating file /jscan/tools_/auto_doc_try/doc/source/index.rst.
Creating file /jscan/tools_/auto_doc_try/doc/Makefile.
Creating file /jscan/tools_/auto_doc_try/doc/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /jscan/tools_/auto_doc_try/doc/source/index.rst and create other do
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

配置conf.py

在source/conf.py文件中加入如下代码， 导入自己的项目路径

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

这里要配好,不然待会生成文档的时候会报找不到模块的错

WARNING: autodoc: failed to import module '1'; the following exception was raised:
No module named '1'
WARNING: autodoc: failed to import module '2'; the following exception was raised:
No module named '2'
WARNING: autodoc: failed to import module 'doc'; the following exception was raised:
No module named 'doc'

---

生成rst文件

注意:-o 后面跟的是保存rst文件的路径， 你的index.rst在哪个目录，那你就指定哪个目录。然后在后面的是你的项目(代码)路径

[root@localhost doc]# /usr/local/python3/bin/sphinx-apidoc -o ./source/ ../../auto_doc_try/
Creating file ./source/1.rst.
Creating file ./source/2.rst.
Creating file ./source/doc.rst.
Creating file ./source/modules.rst.

---

生成html文件

[root@localhost doc]# make html

报错1:

/jscan/tools_/auto_doc_try/doc/source/1.rst:4: WARNING: Unknown directive type "automodule".

.. automodule:: 1
   :members:
   :undoc-members:
   :show-inheritance:
/jscan/tools_/auto_doc_try/doc/source/2.rst:4: WARNING: Unknown directive type "automodule".

.. automodule:: 2
   :members:
   :undoc-members:
   :show-inheritance:
/jscan/tools_/auto_doc_try/doc/source/doc.rst:7: WARNING: Unknown directive type "automodule".

.. automodule:: doc
   :members:
   :undoc-members:
   :show-inheritance:

在conf.py中加入

extensions = [
        'sphinx.ext.autodoc'
]

执行成功:

[root@localhost doc]# make html
Running Sphinx v3.1.2
loading translations [zh_cn]... done
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
no targets are out of date.
build succeeded.

The HTML pages are in build/html.

---

用浏览器打开doc/build/html/index.html：

---

安装主题:

# 命令安装
pip3 install sphinx_rtd_theme -i https://mirrors.aliyun.com/pypi/simple/

配置：编辑我们的source/conf.py
导入模块：

import sphinx_rtd_theme

将 html_theme = "alabaster"改成如下，在加上html_theme_path

html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

最后我们再执行一次：

make clean
make html

---

注释风格Google风格:

Google风格

"""
This is a groups style docs.

Parameters:
  param1 - this is the first param
  param2 - this is a second param

Returns:
  This is a description of what is returned

Raises:
  KeyError - raises an exception
"""

配置:

conf.py中加入

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon'
]

---

支持以下关键字:

• Args （参数别名）

• Arguments （参数别名）

• Attention

• Attributes

• Caution

• Danger

• Error

• Example

• Examples

• Hint

• Important

• Keyword Args （关键字参数的别名）

• Keyword Arguments

• Methods

• Note

• Notes

• Other Parameters

• Parameters

• Return （返回别名）

• Returns

• Raise (alias of Raises)

• Raises

• References

• See Also

• Tip

• Todo

• Warning

• Warnings （警告别名）

• Warn (alias of Warns)

• Warns

• Yield （产量别名）

• Yields

效果:

嘿嘿,还可以

---

Debug:

sphinx会执行代码:

refs:

• Does sphinx run my code on executing ‘make html’?

• python Sphinx “the module executes module level statement and it might call sys.exit().”

把被执行的那几个文件改成函数即可。

def main():

    print('hello world')

if __name__ == '__main__':
    main()

找不到路径\模块:

conf.py内多配置一下路径

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

---

refs:

• 自动生成Python项目文档

• python - python sphinx生成失败autodoc无法导入/查找模块

• Python Sphinx使用踩坑记录

• 使用sphinx快速为你python注释生成API文档

• 如何优雅得编写python注释

• 支持numpy和google风格的docstrings

• Python中的多行注释文档编写风格汇总