Python 自定义“sphinx apidoc”的模板`

我最近尝试使用from帮助从Python项目的API生成特定于Sphinx的reStructuredText

然而，我得到的结果是：

斯芬克斯apiresult“>

有人知道我是否可以自定义sphinx api用于其输出的模板吗？具体来说，我想：

• 去掉所有的“子模块”、“子包”和“模块内容”标题，以及
• 让我的

  \uuuu init\uuuuu.py

  文件中的docstring结果直接显示在包的下面，这样，如果我单击一个包名，我看到的第一件事就是包文档。目前，该文档被放在每个包部分末尾有点奇怪的“模块内容”标题下

我认为“子模块”和“子包”标题是多余的，因为包/模块的正常标题是“xxx.yyy包”和“xxx.yyy.zzz模块”

我希望上面这个小例子的结构是

• orexplore.components包
  • orexplore.components.mbg120模块
• orexplore.simulators包
  • orexplore.simulators.test包
    • orexplore.simulators.test.mbg120模块
  • orexplore.simulators.mbg120模块

在单击包的地方，我在页面上看到的第一件事就是包文档

或者干脆

• orexplore.components
  • orexplore.components.mbg120
• orexplore.simulators
  • orexplore.simulators.test
    • orexplore.simulators.test.mbg120
• orexplore.simulators.mbg120

---

如果有某种方法可以在视觉上区分包装/模块（颜色？标志？），而不是冗长的“包装”和“模块”“

斯芬克斯apidoc脚本使用该模块。我无法提供详细的说明，但为了删除标题或自定义输出，您必须编写自己版本的本模块。没有其他“模板”

请注意，如果API和模块结构稳定，则无需重复运行sphinx apidoc。您可以根据自己的喜好对生成的rst文件进行一次后处理，然后将其置于版本控制之下。另见

更新

---

Sphinx2.2.0中，Sphinxapidoc支持模板。请参阅。

FWIW，这里有一个完整的脚本，可以在每个“filename.rst”旁边的“filename.rst.new”文件中进行所需的更改，这也是我所需的更改：

#/usr/bin/env python
'''
重新排列sphinx apidoc生成的.rst文件中的内容。
*将“模块内容”部分移至顶部。
*删除“模块内容”、“子模块”和“子包”的标题，
包括下划线和以下空行。
'''
导入argparse
导入glob
导入操作系统
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
def参数_解析器（）：
'''
定义命令行参数。
'''
parser=argparse.ArgumentParser(
描述=“”
重新排列sphinx apidoc生成的.rst文件中的内容。
'''
)
parser.add_参数(
'-v'，'-verbose'，
dest='verbose'，
默认值=False，
action='store_true'，
help=”“”
显示更多输出。
"""
)
parser.add_参数(
“输入文件”，
metavar=“输入文件”，
nargs='+'，
help=”“”
文件
"""
)
返回解析器
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
def main（）：
'''
主程序入口点。
'''
全局args
parser=参数_parser（）
args=parser.parse_args（）
filenames=[glob.glob（x）表示args.input\u文件中的x]
如果len（文件名）>0：
filenames=reduce（λx，y:x+y，文件名）
对于集合中的文件名（文件名）：
#行_num将用于一些一致性检查，从来没有
#已实施但未到位。
找到={
“Subpackages”：{“contents”：False，“line_num”：None}，
'Submodules'：{'contents'：False，'line_num'：None}，
'Module contents'：{'contents'：True，'line_num'：None}，
}
模块中的内容=错误
行数=0
重新排序=[]
模块内容=[]
new_filename='.'.join（[filename，'new']）
打开（文件名为“r”）作为fptr：
对于fptr中的行：
line=line.rstrip（）
放弃=错误
行数+=1
如果(
模块中的内容
而len（line）>0
第[0]行不在['，'-'，''中
)：#pylint:disable=错误的继续
模块中的内容=错误
对于查找到的文件：
如果line.find（sequed）==0：
找到[sequed]['line_num']=line_num
如果找到[查找]['contents']：
模块中的内容=真
放弃=真
#丢弃下划线和空行
_=fptr.next（）
_=fptr.next（）
如果在模块内容中且未放弃：
模块内容追加（第行）
如果不放弃：
重新排序。追加（行）
#print'{:I implemented，一个补丁版本的
sphinx-apidoc
脚本，它添加了对模板的完全支持

它添加了一个
-t/--template
选项，允许传递
必须包含模板文件
package.rst
和
module.rst
。
看见
和
例如，这些渲染到。
.
谢谢@mzjn。我有点怀疑没有办法定制它。有点像s
#!/usr/bin/env python

'''
Rearrange content in sphinx-apidoc generated .rst files.

* Move "Module Contents" section to the top.
* Remove headers for "Module Contents", "Submodules" and "Subpackages",
  including their underlines and the following blank line.
'''


import argparse
import glob
import os


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
def argument_parser():
    '''
    Define command line arguments.
    '''

    parser = argparse.ArgumentParser(
        description='''
        Rearrange content in sphinx-apidoc generated .rst files.
        '''
        )

    parser.add_argument(
        '-v', '--verbose',
        dest='verbose',
        default=False,
        action='store_true',
        help="""
            show more output.
            """
        )

    parser.add_argument(
        'input_file',
        metavar="INPUT_FILE",
        nargs='+',
        help="""
            file.
            """
        )

    return parser


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
def main():
    '''
    Main program entry point.
    '''

    global args
    parser = argument_parser()
    args = parser.parse_args()

    filenames = [glob.glob(x) for x in args.input_file]
    if len(filenames) > 0:
        filenames = reduce(lambda x, y: x + y, filenames)

    for filename in set(filenames):

        # line_num was going to be for some consistency checks, never
        # implemented but left in place.
        found = {
            'Subpackages': {'contents': False, 'line_num': None},
            'Submodules': {'contents': False, 'line_num': None},
            'Module contents': {'contents': True, 'line_num': None},
            }

        in_module_contents = False
        line_num = 0
        reordered = []
        module_contents = []

        new_filename = '.'.join([filename, 'new'])

        with open(filename, 'r') as fptr:

            for line in fptr:
                line = line.rstrip()
                discard = False

                line_num += 1

                if (
                        in_module_contents
                        and len(line) > 0
                        and line[0] not in ['.', '-', ' ']
                        ):  # pylint: disable=bad-continuation
                    in_module_contents = False

                for sought in found:

                    if line.find(sought) == 0:

                        found[sought]['line_num'] = line_num
                        if found[sought]['contents']:
                            in_module_contents = True

                        discard = True
                        # discard the underlines and a blank line too
                        _ = fptr.next()
                        _ = fptr.next()

                if in_module_contents and not discard:
                    module_contents.append(line)

                elif not discard:
                    reordered.append(line)

                # print '{:<6}|{}'.format(len(line), line)

        with open(new_filename, 'w') as fptr:
            fptr.write('\n'.join(reordered[:3]))
            fptr.write('\n')
            if module_contents:
                fptr.write('\n'.join(module_contents))
                fptr.write('\n')
                if len(module_contents[-1]) > 0:
                    fptr.write('\n')
            if reordered[3:]:
                fptr.write('\n'.join(reordered[3:]))
                fptr.write('\n')


if __name__ == "__main__":
    main()