如何将 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关于这个话题，但我希望通过提供更多详细信息，我会得到答案。
最佳答案
其他答案很棒。但我认为我(OP)应该分享我这些天(问题后一两年)所做的事情。
我使用 Sphinx 及其 Markdown 扩展。执行以下操作:
TL;DR:见 Gist snippet .
你需要 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 类型提示 ( 并添加 复制粘贴: 接下来就是表演时间了。 复制文件并根据需要进行清理。 需要注意的是，当添加新文件时， 简单地说，apidoc 将为每个文件添加一个 还有命令 应该说有一种趋势，即没有在 GitHub 中但在 Read the docs 中的文档。 .我的猜测是因为: 尽管如此，由于模块要求，它需要进行一些设置。在 another SO post是一长串陷阱和技巧——简单地说，像我这样的 IMO 用户会犯三个错误: 但是，如果有人在 GitHub 中编写了 markdown 文档，也可以导入这些文档，在 需要一个反引号，而 RST 需要两个。如果有疑问，几篇博客文章讨论了 RST 文档相对于 Markdown 的优点。类型提示
: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命令需要重复。不过，我强烈建议在中途生成文档，因为当我看到文档时，我经常意识到自己做错了。automodule命令，因此可以手动添加甚至扩展:.. automodule:: my_module
:members:
:inherited-members:
:undoc-members:
:show-inheritance:
autoclass , autofunction , autoexception , 针对特定情况。在 autoclass 的情况下如果该类继承了单独文件中的许多基类以正确地将文件大小保持在 250 行以下，则属性 :inherited-members:是一个很好的补充——因此避免了描述私有(private)基类。阅读文档:常用方法
sphinx.ext.autodoc扩展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) .
关于Python 文档字符串到 GitHub README.md，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/36237477/
总的来说，我对ruby还比较陌生，我正在为我正在创建的对象编写一些rspec测试用例。许多测试用例都非常基础，我只是想确保正确填充和返回值。我想知道是否有办法使用循环结构来执行此操作。不必为我要测试的每个方法都设置一个assertEquals。例如:describeitem,"TestingtheItem"doit"willhaveanullvaluetostart"doitem=Item.new#HereIcoulddotheitem.name.shouldbe_nil#thenIcoulddoitem.category.shouldbe_nilendend但我想要一些方法来使用
我有一个字符串input="maybe(thisis|thatwas)some((nice|ugly)(day|night)|(strange(weather|time)))"Ruby中解析该字符串的最佳方法是什么？我的意思是脚本应该能够像这样构建句子:maybethisissomeuglynightmaybethatwassomenicenightmaybethiswassomestrangetime等等，你明白了......我应该一个字符一个字符地读取字符串并构建一个带有堆栈的状态机来存储括号值以供以后计算，还是有更好的方法？也许为此目的准备了一个开箱即用的库？
我的目标是转换表单输入，例如“100兆字节”或“1GB”，并将其转换为我可以存储在数据库中的文件大小(以千字节为单位)。目前，我有这个:defquota_convert@regex=/([0-9]+)(.*)s/@sizes=%w{kilobytemegabytegigabyte}m=self.quota.match(@regex)if@sizes.include?m[2]eval("self.quota=#{m[1]}.#{m[2]}")endend这有效，但前提是输入是倍数(“gigabytes”，而不是“gigabyte”)并且由于使用了eval看起来疯狂不安全。所以，功能正常，
在我的Rails(2.3，Ruby1.8.7)应用程序中，我需要将字符串截断到一定长度。该字符串是unicode，在控制台中运行测试时，例如'א'.length，我意识到返回了双倍长度。我想要一个与编码无关的长度，以便对unicode字符串或latin1编码字符串进行相同的截断。我已经了解了Ruby的大部分unicode资料，但仍然有些一头雾水。应该如何解决这个问题？ 最佳答案 Rails有一个返回多字节字符的mb_chars方法。试试unicode_string.mb_chars.slice(0,50)
关闭。这个问题是opinion-based.它目前不接受答案。想要改进这个问题？更新问题，以便editingthispost可以用事实和引用来回答它.关闭4年前。Improvethisquestion我想在固定时间创建一系列低音和高音调的哔哔声。例如:在150毫秒时发出高音调的蜂鸣声在151毫秒时发出低音调的蜂鸣声200毫秒时发出低音调的蜂鸣声250毫秒的高音调蜂鸣声有没有办法在Ruby或Python中做到这一点？我真的不在乎输出编码是什么(.wav、.mp3、.ogg等等)，但我确实想创建一个输出文件。
对于具有离线功能的智能手机应用程序，我正在为Xml文件创建单向文本同步。我希望我的服务器将增量/差异(例如GNU差异补丁)发送到目标设备。这是计划:Time=0Server:hasversion_1ofXmlfile(~800kiB)Client:hasversion_1ofXmlfile(~800kiB)Time=1Server:hasversion_1andversion_2ofXmlfile(each~800kiB)computesdeltaoftheseversions(=patch)(~10kiB)sendspatchtoClient(~10kiBtransferred)Cl
大约一年前，我决定确保每个包含非唯一文本的Flash通知都将从模块中的方法中获取文本。我这样做的最初原因是为了避免一遍又一遍地输入相同的字符串。如果我想更改措辞，我可以在一个地方轻松完成，而且一遍又一遍地重复同一件事而出现拼写错误的可能性也会降低。我最终得到的是这样的:moduleMessagesdefformat_error_messages(errors)errors.map{|attribute,message|"Error:#{attribute.to_s.titleize}#{message}."}enddeferror_message_could_not_find(obje
我试图获取一个长度在1到10之间的字符串，并输出将字符串分解为大小为1、2或3的连续子字符串的所有可能方式。例如:输入:123456将整数分割成单个字符，然后继续查找组合。该代码将返回以下所有数组。[1,2,3,4,5,6][12,3,4,5,6][1,23,4,5,6][1,2,34,5,6][1,2,3,45,6][1,2,3,4,56][12,34,5,6][12,3,45,6][12,3,4,56][1,23,45,6][1,2,34,56][1,23,4,56][12,34,56][123,4,5,6][1,234,5,6][1,2,345,6][1,2,3,456][123
我正在使用的第三方API的文档状态:"[O]urAPIonlyacceptspaddedBase64encodedstrings."什么是“填充的Base64编码字符串”以及如何在Ruby中生成它们。下面的代码是我第一次尝试创建转换为Base64的JSON格式数据。xa=Base64.encode64(a.to_json) 最佳答案 他们说的padding其实就是Base64本身的一部分。它是末尾的“=”和“==”。Base64将3个字节的数据包编码为4个编码字符。所以如果你的输入数据有长度n和n%3=1=>"=="末尾用于填充n%
我有一大串格式化数据(例如JSON)，我想使用Psychinruby同时保留格式转储到YAML。基本上，我希望JSON使用literalstyle出现在YAML中:---json:|{"page":1,"results":["item","another"],"total_pages":0}但是，当我使用YAML.dump时，它不使用文字样式。我得到这样的东西:---json:!"{\n\"page\":1,\n\"results\":[\n\"item\",\"another\"\n],\n\"total_pages\":0\n}\n"我如何告诉Psych以想要的样式转储标量？解