Python 文档字符串到 GitHub README.md

Question

如何将 Python 文档字符串转码为 GitHub readme.md文件？

尽管这似乎是每个人都在做的事情，但我似乎无法找到一个像样的解决方案，而且我认为这应该很容易，所以人们似乎不太可能扔掉两个转换器……

我试过的

pydoc其实很简单。 pydoc的output是manpages（groff format for Unix systems）。 这是一个死胡同，因为 man to md 不是一回事。 通过 HTML， pydoc3 -w + pandoc，将文档字符串完全压缩成位。

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

制作文档。 有人在某处建议。 它只是污染了我的文件夹，因为它是一个误导性的名称，不是 docstrings > md 转换器，而是 md > html。

狮身人面像+潘多克。 修复 UTF-8 问题后，我放弃了 Sphinx，因为我有一个要转换的 single.py 脚本，而且快速入门的 autodoc 设置没有解析我的脚本。 我尝试在 Python 中导入sphinx.ext.autodoc ，但是 TBH 文档太长了，我放弃了。

注意事项

有一个关于该主题的未回答的 Stack Overflow 问题已有一年之久，但我希望通过提供更多详细信息，我会得到答案。

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提示（ :type variable: List ）已过时，因为正确的类型提示def foo(variable: Optional[List[int]]=None) -> Dict[str,int]:从 3.6 开始引入。 为了使这些工作：

 pip install sphinx-autodoc-typehints

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

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

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

https://github.com/coldfix/doc2md

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

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

该模块提供了一个命令行工具，用于解析 Python 文件并使用您的函数定义生成漂亮的 Markdown。 这是非常自以为是和僵化的！ 但也非常容易使用。

Answer 3

我有一些代码可用于从项目生成索引文件。 这不完全是您要查找的内容，但是稍微动一下，您就可以为 py 文件添加 if 语句（我只有 html 和 png）并获取doc = "your DocStrings." ... https:// gist.github.com/Krewn/6e9acdadddb4bf2a56c0

# WARNING RUNNING THIS FILE WILL OVERIDE EXISTING readme.md FILE IN CWD

import os

class indexer:
    path = "~"
    username = "" # !!! Enter your github username in the provided quotes.
    site = "http://"+username+".github.io"
    proj = ""     # !!! Enter your repository name in provided quotes.
    prod = []
    loc=[]

    def __init__(self,p):
        self.path=p
    def fprep(self,name):
        name.replace(".","")
        name.replace("\\","/")
        return(name)
    def refPrep(self):
        ref = self.site+"/"+self.proj
        for qw in self.loc:
            ref+="/"+qw
        return(ref)
    def HtmlFrek(self,adir):
        self.loc.append(adir)
        os.chdir(adir)
        pys = [f for f in os.listdir('.') if os.path.isfile(f) and f.split(".")[len(f.split("."))-1]=="py"]
        for i in pys:
            Open the file i get the __doc__ string and append it to ret
        for k in folders:
            if(k.__contains__(".")):
                continue
            ret+=self.HtmlFrek(k)
        os.chdir("..")
        del self.loc[len(self.loc)-1]
        return(ret)

    def HtmlProd(self):
        ret = ""
        pys = [f for f in os.listdir('.') if os.path.isfile(f) and f.split(".")[len(f.split("."))-1]=="py"]
        for i in pys:
            Open the file i get the __doc__ string and append it to ret
        folders = [f for f in os.listdir(".") if not os.path.isfile(f)]
        for k in folders:
            if(k.__contains__(".")):
                continue
            ret+=self.HtmlFrek(k)
        self.prod = ret
        return(ret)

i = indexer(".")
q=i.HtmlProd()
#print i.prod

w = open("readme.md","w")
w.write(q)
w.close()

Answer 4

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

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