sphinx生成python文档

最新推荐文章于 2024-06-27 18:30:24 发布

荷西·H

最新推荐文章于 2024-06-27 18:30:24 发布

阅读量611

点赞数

本文链接：https://blog.csdn.net/Hesy_H/article/details/103815067

版权

python 专栏收录该内容

25 篇文章 0 订阅

订阅专栏

等待阅读 : 基础入门

reference

还有官方文档里面老是说的source directory , actually 我根本分不清他们都是谁好不好…

主题修改以及advance

默认主题like this ， alabaster

大家常用的主题 readthedoc（rtd）

就是前提要安装下这个主题哈，博主似乎忘了说了
主题汇总

基本流程

可以按照reference 2进行项目构建

# 进入repository
mkdir docs
cd docs
sphinx-quickstart

vim conf.py

我的顺序一般是

--doc
	-- conf.py
	-- index.rst
	-- _template
	-- _static
	-- make.bat
	-- MakeFIle
--codes
--infoFiles

注意点

生成的时候问要不要seperate，就按照默认的不要比较好（n）
sphnix-apidoc
- sphnix-apidoc -o xx xxx
xx就是代码文档所在的目录(默认也就是conf.py所在的，如果移动了conf文件可以用-c参数指定)，会把rst文件生成到这里，xxx就是源代码所在的位置了。
- 最好加上 -f 命令强制覆盖已经生成过的rst文件，否则就会被skip掉
sphinx-apidoc -o ./source …/ -f && make html
目前有点bug 还没有彻底摸清
- 目前看到一个解决方案
关于分支的影响
大意就是主文件里面运行的代码要放到if __name __=="__main __" 里面去
- 另一个bug就是”make html“的时候主代码的文件包(codes/main-codes)并列的还有一个py文件(codes/xx.py)，首先会报错：import这个py文件居然报错说失败，其次，这一层失败以后后续的层都不会再继续编译下去了… ？？？

基本命令

$ sphinx-
sphinx-apidoc sphinx-autogen sphinx-build sphinx-quickstart

sphinx-quickstart 进行配置
sphinx-apidoc 提取文件信息生成rst文件(或者你自己设定的后缀名)
sphinx-build -b xxx = make xxx ，编译生成rst生成目标格式(一般是pdf或者html) ，前者还需要指明位置信息，所以一般就用第二步加上make的命令
sphinx-autogen还不是很清楚，目前也没有用到

配置说明

语言 en 、zh_CN
比较全的配置说明
官网：常用的扩展说明
参考配置
可以一次性配好config.py然后保存，下次直接覆盖，简单修改下ProjectName就可以。

注释代码的几种风格 ( 按照使用率降序排序 )

refer @ 几种注释的风格sample

vscode在python函数下面打"""，默认的docstring snippet是这种google风格

google风格

#coding=UTF-8
class Demo1():
    """类的功能说明 """
	
    def add(self,a,b):
        """两个数字相加，并返回结果"""
        return a+b

    def google_style(arg1, arg2):
        """函数功能.

        函数功能说明.

        Args:
            arg1 (int): arg1的参数说明
            arg2 (str): arg2的参数说明

        Returns:
            bool: 返回值说明

        """
        return True

numpy风格

    def numpy_style(arg1, arg2):
        """函数功能.

        函数功能说明.

        Parameters
        ----------
        arg1 : int
            arg1的参数说明
        arg2 : str
            arg2的参数说明

        Returns
        -------
        bool
            返回值说明

        """
        return True

numpy风格的还可以在注释文件里面写python交互式的内容(测试和使用样例
进一步的还可以结合别的库一起进行代码测试( 详见廖雪峰的博客 )

rst风格

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 train(model, dataset, para, writer, device ):
  """训练模型
  上帝是多少

  Args:
    model (int):
      要训练的模型
    dataset (int):
      train_dataset(还没有装载进torch的Dataset类)
    para ( ParaList ):
      记录参数设置以及存储文件相关信息
    writer (file handler):
      torchboard的file handler
    device (torch device):
      数据和模型所在位置
  Returns:
    void : 
      过程中会输出和记录相关信息 
  """
  pass

这种格式下

相当于每换一个行会自动帮我们加粗上一个标题（生成一个子标题）
参数的类型不要写的太拥挤你打多少空格 html上就会显示多少空格
事实证明不同的section之间(e.g.args和returns)确实不需要空行，最后一个section结束的时候 ‘’’ 要另起一行，但是也不需要再多空一行，但是第一个section和函数的说明文字之间是要空行的