Python 文档字符串到 GitHub README.md
Python docstrings to GitHub README.md
如何将 Python 文档字符串转码为 GitHub readme.md 文件？
尽管这似乎是每个人都在做的事情，但我似乎无法找到一个像样的解决方案，我认为这应该很容易，所以人们似乎不太可能扔掉两个转换器……
我试过的
pydoc 其实很简单。 pydoc 的输出是联机帮助页（Unix 系统的 groff 格式）。这是一个死胡同，因为 man to md 不是一回事。通过 HTML、pydoc3 -w + pandoc，将文档字符串完全压缩成位。
自定义代码 似乎有很多简短的自定义代码，但对于我尝试的少数几个，输出似乎不如那个有摘要的pydoc , 添加继承的方法并列出一些属性。
mkdocs。有人在某处建议。它只是污染了我的文件夹，因为它是一个误导性的名称，不是 docstrings > md 转换器，而是 md > html.
Sphinx + Pandoc. 在修复了一个 UTF-8 问题后，我放弃了 Sphinx，因为我只有一个 .py 脚本要转换，而快速入门的 autodoc 设置确实如此不解析我的脚本。我尝试在 Python 中导入 sphinx.ext.autodoc，但事实上文档太长了，我放弃了。
注意
关于这个话题有一个year-old unanswered Stack Overflow question，但我希望通过提供更多细节我会得到答案。
我有一些代码可用于从项目生成索引文件。这不完全是你要找的东西，但稍微摆动一下，你可以为 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()
我找到了一些其他的选择：
https://github.com/coldfix/doc2md
Little convenience tool to extract docstrings from a module or class and convert them to GitHub Flavoured Markdown. Its purpose is to quickly generate README.md files for small projects.
https://github.com/freeman-lab/myopts
This module provides a command line tool for parsing a Python file and generating nice looking markdown with your function definitions. It's extremely opinionated and rigid! But also extremely easy to use.
其他答案都很棒。但我认为我（OP）应该分享我这些天所做的事情（问题后一两年）。
我使用 Sphinx 及其 Markdown 扩展。执行以下操作：
TL;DR：参见 Gist snippet。
Sphinx-markdown-builder
你需要 sphinx-markdown-builder python module.
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 - 请参阅 this。两者相似，但又不同。例如，Markdown 中的 需要一个反引号，而 RST 需要两个反引号。如果有疑问，一些博客文章讨论了 RST 文档相对于 Markdown 的优点。</p>
<h2>类型提示</h2>
<p>RST 类型提示 (<code>:type variable: List) 已过时，因为从 3.6 开始引入了正确的类型提示 def foo(variable: Optional[List[int]]=None) -> Dict[str,int]:。要使这些工作：
pip install sphinx-autodoc-typehints
并在 extensions 列表末尾添加 'sphinx_autodoc_typehints'。注意包有连字符，而 module 有下划线。
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)
extensions.append('sphinx_autodoc_typehints')
" >> conf.py;
演出时间
接下来是表演时间。
make markdown;
复制文件并按照您喜欢的方式清理。
mv _build/markdown/* ../; rm -r Sphinx-docs;
为新文件重复 Apidoc
需要注意的是，添加新文件时，需要重复apidoc命令。不过，我强烈建议中途生成文档，因为我经常在看到文档时意识到自己做错了什么。
但简而言之，apidoc 将为每个文件添加一个 automodule 命令，因此可以手动添加甚至扩展：
.. automodule:: my_module
:members:
:inherited-members:
:undoc-members:
:show-inheritance:
还有针对特定情况的命令 autoclass、autofunction、autoexception。在 autoclass 的情况下，如果 class 在单独的文件中继承了许多基础 classes 以正确地将文件大小保持在 250 行以下，那么 属性 :inherited-members: 是一个不错的选择除此之外——从而避免必须描述私人基地 classes.
阅读文档：常用方法
应该说不是有文档在GitHub而是在Read the docs有文档的趋势。我的猜测是因为：
- 避免这种 docstrings-to-markdown 业务
- 一些用户对 GitHub
感到困惑
- 更好看
- 别人做
尽管如此，由于 module 要求，它需要一些设置。在 another SO post 中有一长串陷阱和技巧——简而言之，像我这样的 IMO 用户会犯三个错误：
- 缺少 mod 规则或目标 mod 规则
- 忘记硬刷新浏览器
- 启用
sphinx.ext.autodoc 扩展程序
但是，如果有人在 GitHub 中编写了 markdown 文档，也可以导入这些文档，在 docs/source/config.py 文件中使用一个简单的解决方法：
from m2r2 import parse_from_file # noqa
for markdown_filename, srt_filename in {'../../README.md': 'introduction.rst', '../../otherfile.md': 'side_note.rst'}.items():
with open(srt_filename, 'w') as fh:
fh.write(parse_from_file(markdown_filename))
config.py 中的工作路径是它的文件夹，而不是 repo 的基本文件夹。 m2r 是重组文本转换器的降价，但由于不同 module 的更改，它已被放弃并被破坏：r2r2 修复了它。一个问题是可能需要检查链接，尤其是当文件四处移动或相对于基础 URL（斜杠前缀）时，例如。 [Foo](/md_docs/foo).
如何将 Python 文档字符串转码为 GitHub readme.md 文件？
尽管这似乎是每个人都在做的事情，但我似乎无法找到一个像样的解决方案，我认为这应该很容易，所以人们似乎不太可能扔掉两个转换器……
我试过的
pydoc 其实很简单。 pydoc 的输出是联机帮助页（Unix 系统的 groff 格式）。这是一个死胡同，因为 man to md 不是一回事。通过 HTML、pydoc3 -w + pandoc，将文档字符串完全压缩成位。
自定义代码 似乎有很多简短的自定义代码，但对于我尝试的少数几个，输出似乎不如那个有摘要的pydoc , 添加继承的方法并列出一些属性。
mkdocs。有人在某处建议。它只是污染了我的文件夹，因为它是一个误导性的名称，不是 docstrings > md 转换器，而是 md > html.
Sphinx + Pandoc. 在修复了一个 UTF-8 问题后，我放弃了 Sphinx，因为我只有一个 .py 脚本要转换，而快速入门的 autodoc 设置确实如此不解析我的脚本。我尝试在 Python 中导入 sphinx.ext.autodoc，但事实上文档太长了，我放弃了。
注意
关于这个话题有一个year-old unanswered Stack Overflow question，但我希望通过提供更多细节我会得到答案。
我有一些代码可用于从项目生成索引文件。这不完全是你要找的东西，但稍微摆动一下，你可以为 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()
我找到了一些其他的选择：
https://github.com/coldfix/doc2md
Little convenience tool to extract docstrings from a module or class and convert them to GitHub Flavoured Markdown. Its purpose is to quickly generate README.md files for small projects.
https://github.com/freeman-lab/myopts
This module provides a command line tool for parsing a Python file and generating nice looking markdown with your function definitions. It's extremely opinionated and rigid! But also extremely easy to use.
其他答案都很棒。但我认为我（OP）应该分享我这些天所做的事情（问题后一两年）。
我使用 Sphinx 及其 Markdown 扩展。执行以下操作：
TL;DR：参见 Gist snippet。
Sphinx-markdown-builder
你需要 sphinx-markdown-builder python module.
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 - 请参阅 this。两者相似，但又不同。例如，Markdown 中的 需要一个反引号，而 RST 需要两个反引号。如果有疑问，一些博客文章讨论了 RST 文档相对于 Markdown 的优点。</p>
<h2>类型提示</h2>
<p>RST 类型提示 (<code>:type variable: List) 已过时，因为从 3.6 开始引入了正确的类型提示 def foo(variable: Optional[List[int]]=None) -> Dict[str,int]:。要使这些工作：
pip install sphinx-autodoc-typehints
并在 extensions 列表末尾添加 'sphinx_autodoc_typehints'。注意包有连字符，而 module 有下划线。
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)
extensions.append('sphinx_autodoc_typehints')
" >> conf.py;
演出时间
接下来是表演时间。
make markdown;
复制文件并按照您喜欢的方式清理。
mv _build/markdown/* ../; rm -r Sphinx-docs;
为新文件重复 Apidoc
需要注意的是，添加新文件时，需要重复apidoc命令。不过，我强烈建议中途生成文档，因为我经常在看到文档时意识到自己做错了什么。
但简而言之，apidoc 将为每个文件添加一个 automodule 命令，因此可以手动添加甚至扩展：
.. automodule:: my_module
:members:
:inherited-members:
:undoc-members:
:show-inheritance:
还有针对特定情况的命令 autoclass、autofunction、autoexception。在 autoclass 的情况下，如果 class 在单独的文件中继承了许多基础 classes 以正确地将文件大小保持在 250 行以下，那么 属性 :inherited-members: 是一个不错的选择除此之外——从而避免必须描述私人基地 classes.
阅读文档：常用方法
应该说不是有文档在GitHub而是在Read the docs有文档的趋势。我的猜测是因为：
- 避免这种 docstrings-to-markdown 业务
- 一些用户对 GitHub 感到困惑
- 更好看
- 别人做
尽管如此，由于 module 要求，它需要一些设置。在 another SO post 中有一长串陷阱和技巧——简而言之，像我这样的 IMO 用户会犯三个错误：
- 缺少 mod 规则或目标 mod 规则
- 忘记硬刷新浏览器
- 启用
sphinx.ext.autodoc扩展程序
但是，如果有人在 GitHub 中编写了 markdown 文档，也可以导入这些文档，在 docs/source/config.py 文件中使用一个简单的解决方法：
from m2r2 import parse_from_file # noqa
for markdown_filename, srt_filename in {'../../README.md': 'introduction.rst', '../../otherfile.md': 'side_note.rst'}.items():
with open(srt_filename, 'w') as fh:
fh.write(parse_from_file(markdown_filename))
config.py 中的工作路径是它的文件夹，而不是 repo 的基本文件夹。 m2r 是重组文本转换器的降价，但由于不同 module 的更改，它已被放弃并被破坏：r2r2 修复了它。一个问题是可能需要检查链接，尤其是当文件四处移动或相对于基础 URL（斜杠前缀）时，例如。 [Foo](/md_docs/foo).