Python 文档字符串到 GitHub README.md

Question

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

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

我尝试过的

pydoc 其实很简单。 pydoc 的输出是联机帮助页(Unix 系统的 groff 格式)。这是一个死胡同，因为 man 对 md 不是一回事。通过 HTML，pydoc3 -w + pandoc，将文档字符串完全压缩成比特。

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

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

Sphinx + Pandoc。 修复 UTF-8 问题后，我放弃了 Sphinx，因为我有一个要转换的 .py 脚本，并且快速入门的自动文档设置没有解析我的脚本。我尝试在 Python 中导入 sphinx.ext.autodoc，但是 TBH 文档太长，我放弃了。

注意

有一个year-old unanswered Stack Overflow question关于这个话题，但我希望通过提供更多详细信息，我会得到答案。

Answer 1

其他答案很棒。但我认为我(OP)应该分享我这些天(问题后一两年)所做的事情。

我使用 Sphinx 及其 Markdown 扩展。执行以下操作:

TL;DR:见 Gist snippet .

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 - 见 this .两者相似，但又不同。例如，Markdown 中的 需要一个反引号，而 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;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;

对新文件重复 Apdoc

需要注意的是，当添加新文件时，apidoc命令需要重复。不过，我强烈建议在中途生成文档，因为当我看到文档时，我经常意识到自己做错了。

简单地说，apidoc 将为每个文件添加一个 automodule命令，因此可以手动添加甚至扩展:

.. automodule:: my_module
   :members:
   :inherited-members:
   :undoc-members:
   :show-inheritance:

还有命令autoclass , autofunction , autoexception , 针对特定情况。在 autoclass 的情况下如果该类继承了单独文件中的许多基类以正确地将文件大小保持在 250 行以下，则属性 :inherited-members:是一个很好的补充——因此避免了描述私有(private)基类。

阅读文档:常用方法

应该说有一种趋势，即没有在 GitHub 中但在 Read the docs 中的文档。 .我的猜测是因为:

• 避免这种 docstrings-to-markdown 业务
• 一些用户对 GitHub 感到困惑
• 看起来更好
• 其他人做

尽管如此，由于模块要求，它需要进行一些设置。在 another SO post是一长串陷阱和技巧——简单地说，像我这样的 IMO 用户会犯三个错误:

1. 缺少模块或目标模块
2. 忘记硬刷新浏览器
3. 启用 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是重组文本转换器的 Markdown ，但由于不同模块中的更改已被放弃并损坏:r2r2修复它。一个问题是可能需要检查链接，特别是如果文件移动或相对于基本 URL(斜杠前缀)，例如。 [Foo](/md_docs/foo) .