Pyment is a tool that can convert Python docstrings and create missing ones skeletons. It can manage Google, Epydoc (javadoc style), Numpydoc, reStructuredText (reST, Sphinx default) docstring formats.
It accepts a single file or a folder (exploring also sub-folders). For each file, it will recognize each docstring format and convert it to the desired one. At the end, a patch will be generated to apply to the file.
It might be an overkill for this simple usage, but I'd look into using the machinery of 2to3 to do the editing. You just need to write a custom fixer. It's not well-documented, but Developer's Guide to Python 3.0: Python 2.6 and Migrating From 2 to 3: More about 2to3 and Implement Custom Fixers gives enough detail to get started...
Epydoc seems to contain a to_rst() method which might help you actually translate the docstrings. Don't know if it's any good...
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()
Probably the most straightforward just to do it the old-fashioned way. Here's some initial code to get you going. It probably could be prettier but should give the basic idea:
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()
To make it truly functional you need to hook it up with a file finder and output the files to some other directory. Check out the os.path module for reference.
I know the docstring bound check is potentially really weak. It's probably a good idea to beef it up a bit (strip line and check if it begins or ends with a docstring bound).
Hopefully that gives some idea how to possibly proceed. Perhaps there's a more elegant way to handle the problem. :)
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)
I wonder about a combination of introspection and source processing. Here's some untested pseudocode:
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)
Clearly you'd have to put some cleverness in the code that traverses the module looking for objects that have docstrings so it would recurse, but this gives you the general idea.
发布评论
评论（4）
Pyment 是一个可以转换 Python 文档字符串并创建缺失框架的工具。它可以管理 Google、Epydoc（javadoc 样式）、Numpydoc、reStructuredText（reST、Sphinx 默认）文档字符串格式。
它接受单个文件或文件夹（也探索子文件夹）。对于每个文件，它将识别每种文档字符串格式并将其转换为所需的格式。最后，将生成一个补丁以应用于该文件。
要转换您的项目：
输入以下内容（您可以使用 virtualenv）：
您可以将项目转换为 Sphinx 格式 (reST)，该格式是默认输出格式，方法是：
编辑：
使用pip安装：
Pyment is a tool that can convert Python docstrings and create missing ones skeletons. It can manage Google, Epydoc (javadoc style), Numpydoc, reStructuredText (reST, Sphinx default) docstring formats.
It accepts a single file or a folder (exploring also sub-folders). For each file, it will recognize each docstring format and convert it to the desired one. At the end, a patch will be generated to apply to the file.
To convert your project:
Type the following (you can use a virtualenv):
You can convert your project to Sphinx format (reST), which is the default output format, by doing:
EDIT:
Install using pip:
对于这种简单的用法来说可能有点大材小用，但我会考虑使用 2to3 机制来进行编辑。您只需要编写一个自定义修复程序。它没有详细记录，但是Python 3.0 开发人员指南：Python 2.6 和从 2 迁移到 3：更多关于 2to3 和 实现自定义修复程序提供了足够的详细信息来开始...
Epydoc似乎包含一个
to_rst()方法可能会帮助您实际翻译文档字符串。不知道好不好用...It might be an overkill for this simple usage, but I'd look into using the machinery of 2to3 to do the editing. You just need to write a custom fixer. It's not well-documented, but Developer's Guide to Python 3.0: Python 2.6 and Migrating From 2 to 3: More about 2to3 and Implement Custom Fixers gives enough detail to get started...
Epydoc seems to contain a
to_rst()method which might help you actually translate the docstrings. Don't know if it's any good...用老式的方法可能是最直接的。这是一些帮助您继续前进的初始代码。它可能会更漂亮，但应该给出基本的想法：
要使其真正发挥作用，您需要将其与文件查找器连接并将文件输出到其他目录。查看 os.path 模块以供参考。
我知道文档字符串绑定检查可能非常弱。稍微加强它可能是一个好主意（剥离线并检查它是否以文档字符串绑定开始或结束）。
希望这能提供一些如何继续进行的想法。也许有一种更优雅的方法来处理这个问题。 :)
Probably the most straightforward just to do it the old-fashioned way. Here's some initial code to get you going. It probably could be prettier but should give the basic idea:
To make it truly functional you need to hook it up with a file finder and output the files to some other directory. Check out the os.path module for reference.
I know the docstring bound check is potentially really weak. It's probably a good idea to beef it up a bit (strip line and check if it begins or ends with a docstring bound).
Hopefully that gives some idea how to possibly proceed. Perhaps there's a more elegant way to handle the problem. :)
我想知道内省和源处理的结合。这是一些未经测试的伪代码：
显然，您必须在遍历模块寻找具有文档字符串的对象的代码中加入一些技巧，以便它会递归，但这给了您总体思路。
I wonder about a combination of introspection and source processing. Here's some untested pseudocode:
Clearly you'd have to put some cleverness in the code that traverses the module looking for objects that have docstrings so it would recurse, but this gives you the general idea.