转换项目：

Question

我已经编写了epytext到reST标记转换器，现在我想将整个库中的所有文档字符串从epytext转换为reST格式。

是否有一种智能方法可以读取模块中的所有文档字符串并回写替换内容？

ps：ast模块也许？

Answer 1

Pyment是一个可以转换Python文档字符串并创建缺失字符串的工具。它可以管理 Google ， Epydoc （javadoc样式）， Numpydoc ， reStructuredText （reST，Sphinx默认）docstring格式

它接受单个文件或文件夹（也可以浏览子文件夹）。对于每个文件，它将识别每个文档字符串格式并将其转换为所需的格式。最后，将生成一个补丁以应用于该文件。

转换项目：

安装Pyment

键入以下内容（您可以使用virtualenv）：

$ git clone https://github.com/dadadel/pyment.git
$ cd pyment
$ python setup.py install

从Epydoc转换为Sphinx

您可以通过执行以下操作将项目转换为Sphinx格式（reST），这是默认的输出格式：

$ pyment /my/folder/project

修改

使用 pip 安装：

$ pip install git+https://github.com/dadadel/pyment.git

Answer 2

对于这种简单的用法可能有点过分，但我会考虑使用 2to3 的机制进行编辑。您只需要编写自定义修复程序。它没有详细记录，但 Python 3.0开发人员指南：Python 2.6和从2迁移到3：More about 2to3和Implement Custom Fixers 提供了足够的细节来开始... < / p>

Epydoc似乎包含一个to_rst()方法，可以帮助您实际翻译文档字符串。不知道它是否有用......

Answer 3

可能最简单的就是以老式的方式做到这一点。这里有一些初步的代码可以帮助你。它可能更漂亮，但应该给出基本的想法：

def is_docstr_bound(line):
    return "'''" in line or  '"""' in line

# XXX: output using the same name to some other folder
output = open('output.py', 'w')

docstr_found = False
docstr = list()
with open('input.py') as f:
    for line in f.readlines():
        if docstr_found:
            if is_docstr_bound(line):
                # XXX: do conversion now
                # ...

                # and write to output
                output.write(''.join(docstr))

                output.write(line)

                docstr = list()
                docstr_found = False
            else:
                docstr.append(line)
        else:
            if is_docstr_bound(line):
                docstr_found = True

            output.write(line)

output.close()

要使其真正起作用，您需要将其与文件查找器连接起来并将文件输出到其他目录。查看os.path模块以供参考。

我知道文档字符串绑定检查可能非常弱。这可能是个好主意（剥离线并检查它是否以docstring绑定开始或结束）。

希望这能让我们知道如何继续进行。也许有更优雅的方式来处理这个问题。：）

Answer 4

我想知道内省和源处理的结合。这是一些未经测试的伪代码：

import foo #where foo is your module

with open('foo.py',r) as f:
    src = f.readlines()

for pything in dir(foo):  #probably better ways to do this...
    try:
       docstring = pything.__doc__
    except AttributeError:
       #no docstring here
       pass

    #modify the docstring
    new_docstring = my_format_changer(docstring)

    #now replace it in the source
    src = src.replace(docstring, new_docstring)

#When done, write it out
with open('new_foo.py','w') as fout:
    fout.write(src)

显然，你必须在遍历模块的代码中加入一些聪明的东西来寻找具有文档字符串的对象，以便它能够递归，但这给了你一般的想法。

替换python docstrings

4 个答案:

转换项目：

使用 pip 安装：