Question

如何将python doc字符串转码为Github pydoc3 -w？

即使看起来像每个人都做的事情，我似乎无法得到一个像样的解决方案而且我认为它应该很容易，所以似乎人们不太可能会抛出两个转换器......

我尝试了什么

pydoc 其实很简单。 pydoc的输出是联机帮助页（UNIX系统的groff格式）。这是一个死胡同，因为男人对md不是一件事。通过HTML，sphinx.ext.autodoc + pandoc，完全将文档字符串用于比特。

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

mkdocs 即可。有人建议在某处。它只会污染我的文件夹，因为它是一个误导性的名称，因为它不是文档字符串＆gt; md转换器，但是md> HTML。

Sphinx + Pandoc。修复UTF-8问题后，我放弃了Sphinx，因为我有一个要转换的py脚本，并且快速启动的autodoc设置没有解析我的脚本。我尝试在Python中导入List<MvcApplication1.Models.Country> cntry = db.Countries.ToList(); SelectListItem sss = new SelectListItem(); List<SelectListItem> sltst = new List<SelectListItem>(); sss.Text = "Select"; sss.Value = "0"; sltst.Add(sss); foreach (MvcApplication1.Models.Country s in cntry){ SelectListItem s1 = new SelectListItem(); s1.Text = s.Country1; s1.Value = Convert.ToString(s.Id); sltst.Add(s1);} @Html.DropDownList("country", sltst, new { @id = "country" })但TBH的文档太长了，我放弃了。

NB

关于这个主题，有一个[未经过回答的SO问题]（Automatically Generate GitHub Wiki Documentation from Python Docstrings），但我希望通过提供更多详细信息，我会得到答案。

Answer 1

我找到了其他一些选项：

https://github.com/coldfix/doc2md

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

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

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

Answer 2

我有一些代码用于从项目生成索引文件。它并不完全是您正在寻找的东西，但稍微摆动一下，您可以为py文件添加if语句（我只有html和png）并获取 doc =＆＃34;你的DocStrings。＆＃34; ... 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 3

其他答案很好。但是我认为我（OP）应该分享我最近几天（Q之后的一两年）所做的事情。

我使用Sphinx及其markdown扩展名。执行以下操作：

Sphinx-markdown-builder

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

 pip install sphinx sphinx-markdown-builder;

运行Sphinx

不是自动文档！！ apidoc！

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

Conf

通过遵循以下内容来修复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)

注意事项。文档字符串应以重组文本编写。如果他们处于降价促销中，则需要添加一个mod，请参见this。

TL; DR

复制粘贴以下内容：

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)  
 " >> conf.py;

放映时间

然后是放映时间。

make markdown;

复制文件并按您的意愿清理。

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

Python文档字符串到Github README.md