我有一个项目,我使用epydoc记录。现在我试图切换到狮身人面像。我使用B {},L {}等来为粗体,链接等使用@param,@return,@raise等来解释输入,输出,异常和类似内容,从而格式化了所有的epydocs文档。从epydoc的文档字符串格式切换到狮身人面像文档字符串格式的自动方式?
所以,现在我切换到狮身人面像它失去了所有这些功能。有没有一种自动的方式来转换为epydoc格式化的docstrings格式为狮身人面像文档?
我有一个项目,我使用epydoc记录。现在我试图切换到狮身人面像。我使用B {},L {}等来为粗体,链接等使用@param,@return,@raise等来解释输入,输出,异常和类似内容,从而格式化了所有的epydocs文档。从epydoc的文档字符串格式切换到狮身人面像文档字符串格式的自动方式?
所以,现在我切换到狮身人面像它失去了所有这些功能。有没有一种自动的方式来转换为epydoc格式化的docstrings格式为狮身人面像文档?
要扩展Kevin Horn的答案,可以在由autodoc-process-docstring事件触发的事件处理程序中动态翻译文档字符串。
下面是一个小型演示(尝试将代码添加到conf.py)。它用一些常见的Epytext fields中的@
字符替换为:
,该字符在相应的Sphinx fields中使用。
import re
re_field = re.compile('@(param|type|rtype|return)')
def fix_docstring(app, what, name, obj, options, lines):
for i in xrange(len(lines)):
lines[i] = re_field.sub(r':\1', lines[i])
def setup(app):
app.connect('autodoc-process-docstring', fix_docstring)
更新:** sphinx-epytext **扩展提供基本的Epytext支持。请参阅https://pypi.python.org/pypi/sphinx-epytext。 – mzjn 2015-05-02 19:20:48
从理论上讲,你可以编写一个Sphinx扩展,它可以在读取文档字符串(source_read
,也许?)时捕获所有触发的事件并即时翻译文档字符串。
我从理论上说,这是因为:
你也可以尝试可能只是一个类似的翻译更换所有的文档字符串代码中的狮身人面像之外,或许使用ast
模块或类似的东西。
Pyment是一个工具,可以转换Python文档和创建缺少的骨架。它可以管理谷歌,epydoc的(javadoc的风格),Numpydoc,reStructuredText的(休息,狮身人面像默认值)文档字符串格式。
它接受单个文件或文件夹(也浏览子文件夹)。对于每个文件,它将识别每个文档字符串格式并将其转换为所需的格式。最后,将生成一个补丁以应用于该文件。
键入以下内容(可以使用的virtualenv):
$ git clone https://github.com/dadadel/pyment.git
$ cd pyment
$ python setup.py install
你可以做你的项目转换为狮身人面像格式(REST),这是默认的输出格式,:
$ pyment /my/folder/project
我给了这个镜头,但创建的补丁不包含'__doc__'字符串,像'B {一些粗体文本}一样的Epydoc标记保留在.patch文件中。这是预期的吗? – Epu 2014-09-24 17:56:33
@Epu你是什么意思的“不包括__doc__字符串”?关于Pyment,它关注的是标签而不是喜欢的标签。但是你可以打开一个问题来管理它。 – daouzli 2014-09-25 13:45:50
啊,所以来自http://epydoc.sourceforge.net/epytext.html 2.6的字段会被转换,但不是任何内联的(从3到3.4)? – Epu 2014-09-26 05:12:09
见http://stackoverflow.com/questions/2477909/replacing-python -docstrings。人们希望用户tomaz提供了关于他的转换器的更多细节。也许这里是同一个人:http://www.mail-archive.com/[email protected]/msg03159.html。 – mzjn 2012-04-10 13:30:36