Can't render python reST format docstring

Question

I was studying a python framework, scrapy and I learned that it uses a style of docstring as below

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.

I wondered what all those special characters do or mean. I came upon this article and kinda had vague idea of what reST format is. I wanted to know how this docstring is supposed to be rendered so tried this online renderer but it didn't render the doctstring properly. seemed like it didn't support things such as :class: and :meth:

My questions are

Why couldn't I render the docstring. Isn't it valid reST format?
Isn't this style of docstring supposed to be rendered at all? Or
should it be read as plain text?
How can I render this if I can?
Is it possible to have rendered docstring in interactive python shell?

score 0 · Accepted Answer · edited Jun 20 '20 at 09:12

Why couldn't I render the docstring. Isn't it valid reST format?

The reST is valid but it contains markup that is not part of "standard reST", which is what the http://rst.ninjs.org/ renderer supports (it uses rst2html.py, provided by Docutils).

:class: and :meth: are examples of additions to standard reST that are understood by the Sphinx documentation generator. See http://www.sphinx-doc.org/en/stable/markup/index.html and http://www.sphinx-doc.org/en/stable/domains.html.

The following markup,

:class:`~scrapy.settings.Settings`

is rendered as a hyperlink to the documentation of the scrapy.settings.Settings class. See https://doc.scrapy.org/en/1.3/topics/api.html#scrapy.crawler.CrawlerRunner.

Isn't this style of docstring supposed to be rendered at all? Or should it be read as plain text?

How can I render this if I can?

The docstring is supposed to be processed by Sphinx.

Is it possible to have rendered docstring in interactive python shell?

I suppose that it is possible to implement something that makes the console output nicer, but I don't know any tool or library that does this.

Can't render python reST format docstring

1 Answers1