Python文档字符串到Github README.md

Question

如何将python doc字符串转码为Github readme.md？

虽然看起来似乎每个人都做了,我似乎无法得到一个像样的解决方案,我认为它应该很容易,所以似乎人们不太可能抛出两个转换器......

我试过了什么

pydoc 其实很简单.pydoc的输出是联机帮助页(UNIX系统的groff格式).这是一个死胡同,因为男人对md不是一件事.通过HTML,pydoc3 -w+ pandoc,完全将文档字符串转换为位.

自定义代码似乎有很多简短的自定义代码,但对于少数我尝试过的输出似乎不如pydoc那样好,它有一个摘要,添加了继承的方法并列出了一些属性.

mkdocs.有人建议在某处.它只会污染我的文件夹,因为它是一个误导性的名称,因为它不是docstrings> md转换器,而是md> html.

狮身人面像+潘多克.在解决了UTF-8问题之后,我放弃了Sphinx,因为我有一个要转换的py脚本,并且快速启动的autodoc设置没有解析我的脚本.我尝试用Python导入sphinx.ext.autodoc但TBH的文档太长了,我放弃了.

NB

有一个[一年前未解答的SO问题](从Python Docstrings自动生成GitHub Wiki文档)关于这个主题,但我希望通过提供更多细节我会得到答案.

Answer 1

其他答案都很棒。但我认为我（OP）应该分享我这些天（在提出问题后一两年）所做的事情。

我使用 Sphinx 及其 Markdown 扩展。请执行下列操作：

Sphinx-markdown-builder

您需要 sphinx-markdown-builder python 模块。

 pip install sphinx sphinx-markdown-builder;

运行狮身人面像

不是的autodoc，对apidoc！

sphinx-apidoc -o Sphinx-docs . sphinx-apidoc --full -A 'Matteo Ferla'; cd Sphinx-docs;

配置

修复conf.py文件，通过遵循以下或只是懒惰地复制粘贴下面的 echo 命令。

手动的

首先取消注释行。这些都被注释掉了。

import os
import sys
sys.path.insert(0, os.path.abspath('../'))

注意更改为 ../

一个奇怪的是魔术方法被忽略了。要覆盖它，请在任何地方添加：

def skip(app, what, name, obj, would_skip, options):
    if name in ( '__init__',):
        return False
    return would_skip
def setup(app):
    app.connect('autodoc-skip-member', skip)

需要注意的一点：文档字符串应该用重组文本 (RST) 编写。如果它们在 Markdown 中，您需要添加一个 mod - 请参阅此. 两者相似，但又不同。例如，Markdown 中的 <code> 需要一个反引号，而 RST 需要两个反引号。如果有疑问，几篇博客文章讨论了 RST 文档相对于 Markdown 的优点。

打字提示

RST 类型提示 ( :type variable: List) 已过时，def foo(variable: Optional[List[int]]=None) -> Dict[str,int]:因为自 3.6 以来引入了正确的类型提示。为了使这些工作：

 pip install sphinx-autodoc-typehints

并添加'sphinx_autodoc_typehints'到extensions列表的末尾。请注意，包有连字符，而模块有下划线。

TL; 博士

复制粘贴这个：

echo " import os
import sys
sys.path.insert(0,os.path.abspath('../'))
def skip(app, what, name, obj,would_skip, options):
    if name in ( '__init__',):
        return False
    return would_skip
def setup(app):
    app.connect('autodoc-skip-member', skip)
extensions.append('sphinx_autodoc_typehints')
 " >> conf.py;

开演时间

然后是放映时间。

make markdown;

复制文件并按照您的喜好进行清理。

mv _build/markdown/* ../; rm -r Sphinx-docs;

重复

需要注意的是，当添加新文件时，apidoc需要重复该命令。尽管如此，我强烈建议中途生成文档，因为我意识到我做错了什么。

Answer 2

我发现pydoc-markdown非常容易使用。第一个命令将安装该库，第二个命令将从名为 的模块创建自述文件MY_MODULE：

pip install pydoc-markdown
pydoc-markdown -m MY_MODULE -I $(pwd) > README.md

Answer 3

我找到了一些其他选项来执行此操作：

https://github.com/coldfix/doc2md

从模块或类中提取文档字符串并将其转换为 GitHub Flavored Markdown 的小便利工具。其目的是为小型项目快速生成README.md文件。

https://github.com/freeman-lab/myopts

该模块提供了一个命令行工具，用于解析 Python 文件并使用函数定义生成美观的 Markdown。这是非常固执和僵化的！而且也非常容易使用。