无法呈现 python reST 格式文档字符串答案

【问题标题】：Can't render python reST format docstring无法呈现 python reST 格式文档字符串
【发布时间】：2017-02-01 07:20:14
【问题描述】：

我正在研究一个python框架，scrapy，我了解到它使用如下的文档字符串样式

class CrawlerRunner(__builtin__.object)
 |  This is a convenient helper class that keeps track of, manages and runs
 |  crawlers inside an already setup Twisted `reactor`_.
 |  
 |  The CrawlerRunner object must be instantiated with a
 |  :class:`~scrapy.settings.Settings` object.
 |  
 |  __init__(self, settings=None)
 |  
 |  crawl(self, crawler_or_spidercls, *args, **kwargs)
 |      Run a crawler with the provided arguments.
 |      
 |      It will call the given Crawler's :meth:`~Crawler.crawl` method, while
 |      keeping track of it so it can be stopped later.

我想知道所有这些特殊字符的作用或含义。我遇到了this article，对什么是 reST 格式有点模糊。我想知道这个文档字符串应该如何呈现，所以尝试了这个online renderer，但它没有正确呈现文档字符串。似乎它不支持诸如 :class: 和 :meth: 之类的东西：

我的问题是

为什么我不能渲染文档字符串。不是有效的 reST 格式吗？
难道不应该渲染这种风格的文档字符串吗？或者
应该以纯文本形式阅读吗？
如果可以，我该如何渲染它？
是否可以在交互式 python shell 中呈现文档字符串？

【问题讨论】：

标签： python format restructuredtext docstring

【解决方案1】：

为什么我不能渲染文档字符串。不是有效的 reST 格式吗？

reST 是有效的，但它包含不属于“标准 reST”的标记，这是 http://rst.ninjs.org/ 渲染器支持的（usesrst2html.py，由 Docutils 提供）。

:class: 和 :meth: 是 Sphinx 文档生成器可以理解的标准 reST 的添加示例。请参阅http://www.sphinx-doc.org/en/stable/markup/index.html 和http://www.sphinx-doc.org/en/stable/domains.html。

以下标记，

:class:`~scrapy.settings.Settings`

呈现为scrapy.settings.Settings 类文档的超链接。见https://doc.scrapy.org/en/1.3/topics/api.html#scrapy.crawler.CrawlerRunner。

这种风格的文档字符串不应该被渲染吗？还是应该将其读取为纯文本？

如果可以，我该如何渲染？

文档字符串应该由 Sphinx 处理。

是否可以在交互式 python shell 中呈现文档字符串？

我想可以实现一些使控制台输出更好的东西，但我不知道有什么工具或库可以做到这一点。

【讨论】：