13

Is there a way to have IPython fully render reStructuredText (for Sphinx) docstrings when you type the following:

help foo

or:

foo?

I find it super distracting to try to read help docs in IPython when it shows the raw markup. reST is great for Sphinx documentation, but really clutters up simple help lookups. I can't be alone on this one...?

Google has been no help on this one.

mzjn
  • 48,958
  • 13
  • 128
  • 248
jkmacc
  • 6,125
  • 3
  • 30
  • 27
  • As far as I know, not yet. Contributions are welcome - ask on mailing lists or IRC about where to start. – Thomas K Jan 24 '12 at 20:53
  • One way you could add the feature is to render the docstring to HTML and then parse and colorize (or just print the text) the output. – Ed L Mar 04 '12 at 20:21
  • There's also a text builder for Sphinx, that might be easier than using HTML. – Kevin Horn Mar 21 '12 at 17:03
  • 1
    I agree, viewing sphinx docstrings in ipython is not really human readable. I have tried using "Consolidated Fields" as a compromise: viewing docstrings in interpreter is better, but some of Sphinx's nice features are lost. – Mark Mikofski Jul 29 '13 at 18:54
  • It has been discussed: http://python.6.x6.nabble.com/IPython-User-Pretty-rendering-of-docstrings-td5003265.html but nothing has been implemented AFAIK. – Wilfred Hughes May 19 '14 at 10:28
  • 1
    Thank you for the link- very encouraging. I think Brian Granger said it best: "Personally, if the notebook became able to handle markdown+latex docstrings, I would never user reST for any new project." I'm already using Markdown in docstrings instead of Sphinx, as I see a few projects aiming to build API documentation from docstrings. This, I think, is the only thing for which I currently need Sphinx. – jkmacc May 19 '14 at 17:20

1 Answers1

2

I don't think it is possible in IPython, but have a look at Spyder: You can open an IPython console from within the IDE. Docstrings are rendered as HTML.

bmu
  • 35,119
  • 13
  • 91
  • 108