Quantcast

notebook idea: reST rendering of docstrings?

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

notebook idea: reST rendering of docstrings?

Hans Meine
Hi,

when looking at complex docstrings, e.g. typing 'subprocess?' in the ipython
notebook, I would like to get a beatiful HTML rendering of the reST code.

Just posting as an idea (should I file a GH issue?)…

Best,
  Hans

_______________________________________________
IPython-dev mailing list
[hidden email]
http://mail.scipy.org/mailman/listinfo/ipython-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: notebook idea: reST rendering of docstrings?

Hans Meine
Hi again,

along similar lines, when I call 'help(subprocess)', the output contains a
docs.python.org URL.  It would be desirable to be able to click on it.

In general, I could imagine making URLs in the output clickable.
(http, https, mailto:, maybe also plain email addresses and other protocols
like ftp, …)

After all, it feels quite ridiculous to copy URLs from HTML in the browser
into the address bar…

I am not sure which way would be better:
1) using JS to parse the output cells and add markup, or
2) formatting the output in python.

I would obviously prefer Python coding over JS, but maybe 2) would be more
feasible given the current architecture (JSON, notebook storage, …).

Best,
  Hans
_______________________________________________
IPython-dev mailing list
[hidden email]
http://mail.scipy.org/mailman/listinfo/ipython-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: notebook idea: reST rendering of docstrings?

Hans Meine
Am Freitag, 27. Januar 2012, 10:40:51 schrieb Hans Meine:
> I am not sure which way would be better:
> 1) using JS to parse the output cells and add markup, or
> 2) formatting the output in python.
>
> I would obviously prefer Python coding over JS, but maybe 2) would be more
> feasible given the current architecture (JSON, notebook storage, …).

Obviously, I meant "maybe 1) [JS] would be more feasible…".
_______________________________________________
IPython-dev mailing list
[hidden email]
http://mail.scipy.org/mailman/listinfo/ipython-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: notebook idea: reST rendering of docstrings?

Thomas Kluyver-2
In reply to this post by Hans Meine
On 27 January 2012 09:31, Hans Meine <[hidden email]> wrote:
when looking at complex docstrings, e.g. typing 'subprocess?' in the ipython
notebook, I would like to get a beatiful HTML rendering of the reST code.

This came up just the other day on the ipython-user mailing list, in fact. Yes, it should be possible to turn reST into HTML on the Python side. Here's the discussion:

http://comments.gmane.org/gmane.comp.python.ipython.user/7445

CCing Jonathan, who proposed it there - perhaps you can collaborate on it.

Thomas

_______________________________________________
IPython-dev mailing list
[hidden email]
http://mail.scipy.org/mailman/listinfo/ipython-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Status of printing in the notebook

Mark Voorhies-2
In reply to this post by Hans Meine
I just started using the notebook yesterday (following an upgrade to Firefox 9)
and it's awesome -- so much so that I'm switching to it for everyday work and
am planning to teach from it in April.  

One thing I would like to hack on is an equivalent to the qtconsole's "export
with inlined images" (xhtml+svg / html+inlined png) function (so that I can
save/e-mail finished work as a single file with no dependencies).

The print window circa a50ac36bd554 looks like the right starting point (it
would just need inlining of the css and images), but it looks like this version
was scrapped when the wijmo menus were added and that there now may be
different ideas for printing (https://github.com/ipython/ipython/issues/1292).

So -- is this a good time to start working on this sort of inlining (and, if so,
which code should I be looking at) or would it be better to wait for the next
print window revision (and is there an issue/PR that I should be watching
for this)?

Thanks,

Mark

_______________________________________________
IPython-dev mailing list
[hidden email]
http://mail.scipy.org/mailman/listinfo/ipython-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Status of printing in the notebook

Fernando Perez
On Sat, Jan 28, 2012 at 6:22 PM, Mark Voorhies <[hidden email]> wrote:
> The print window circa a50ac36bd554 looks like the right starting point (it
> would just need inlining of the css and images), but it looks like this version
> was scrapped when the wijmo menus were added and that there now may be
> different ideas for printing (https://github.com/ipython/ipython/issues/1292).

Mmh, actually I think the complete loss of printing currently is a
regression.  I hadn't noticed this, and it is a problem (I need it for
some lectures on Monday...).  I've opened a ticket for it:

https://github.com/ipython/ipython/issues/1339

Now, on the larger question I'll let Brian respond, b/c I'm not sure
right now what pieces of the code he's working on, and he may have
some plans regarding printing as well.

Cheers,

f
_______________________________________________
IPython-dev mailing list
[hidden email]
http://mail.scipy.org/mailman/listinfo/ipython-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Status of printing in the notebook

Brian Granger-3
In reply to this post by Mark Voorhies-2
Mark,

Sorry it has taken a few days to get back to you about this.  There is
a lot of activity on the notebook right now and I am having a tough
time keeping up (even though I am working on it full time!).

First, I will fix the notebook printing hopefully today, maybe early tomorrow.

On Sat, Jan 28, 2012 at 6:22 PM, Mark Voorhies <[hidden email]> wrote:
> I just started using the notebook yesterday (following an upgrade to Firefox 9)
> and it's awesome -- so much so that I'm switching to it for everyday work and
> am planning to teach from it in April.
>
> One thing I would like to hack on is an equivalent to the qtconsole's "export
> with inlined images" (xhtml+svg / html+inlined png) function (so that I can
> save/e-mail finished work as a single file with no dependencies).

Yes, we *really* would like to have this capability and are more than
willing to help you get started.  Here is a few points:

* The IPython.nbformat.v3 subpackage has an infrastructure for
notebook readers/writers.  We currently have one for .json and .py
files.  This is the place to create one for exporting to HTML.
* Exporting to raw HTML is not quite possible.  The reason for this is
that we use a couple of Javascript libraries:  MathJax for rendering
latex embedded in the HTML, CodeMirror for formatting the code areas
with syntax highlighting, and A Markdown parser that converts Markdown
to HTML.  We will have to figure out substitutes for these JS
libraries in the HTML export.
* There are two possible ways of generating raw HTML:

1) First export to reST and then use rst2html to get to the HTML.
Some benefits to this, but the downside is that raw Markdown/HTML
cells would get lost in the process (although I think that reST
suports raw HTML inclusion.  Also, this would make it more difficult
to control exactly what the HMTL looks like (IOW use our current CSS
styling).
2) Use a templating library to export directly to HTML.  I think this
is very worth pursuing as a first line of attack.  The would allow you
to simply recreate the right HTML structure with the proper id/classes
and then inline our CSS.  It would give you exactly the same look as
we have now.  We would still need to figure out how to handle MathJax,
CodeMirror and Markdown though.

I imagine that in the long run we will support both of these routes.
Once we have the writers in place in IPython.nbformat.v3, it will be a
simple matter of incorporating them into the notebook server.

Here is a github issue where we should continue this discussion:

https://github.com/ipython/ipython/issues/860

Fernando even has a draft reST exporter implemented.  Let us know if
you have questions.

Cheers,

Brian

> The print window circa a50ac36bd554 looks like the right starting point (it
> would just need inlining of the css and images), but it looks like this version
> was scrapped when the wijmo menus were added and that there now may be
> different ideas for printing (https://github.com/ipython/ipython/issues/1292).
>
> So -- is this a good time to start working on this sort of inlining (and, if so,
> which code should I be looking at) or would it be better to wait for the next
> print window revision (and is there an issue/PR that I should be watching
> for this)?
>
> Thanks,
>
> Mark
>
> _______________________________________________
> IPython-dev mailing list
> [hidden email]
> http://mail.scipy.org/mailman/listinfo/ipython-dev



--
Brian E. Granger
Cal Poly State University, San Luis Obispo
[hidden email] and [hidden email]
_______________________________________________
IPython-dev mailing list
[hidden email]
http://mail.scipy.org/mailman/listinfo/ipython-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Status of printing in the notebook

Mark Voorhies-2
On Tuesday, January 31, 2012 01:09:03 pm Brian Granger wrote:

> Mark,
>
> Sorry it has taken a few days to get back to you about this.  There is
> a lot of activity on the notebook right now and I am having a tough
> time keeping up (even though I am working on it full time!).
>
> First, I will fix the notebook printing hopefully today, maybe early tomorrow.
>
> On Sat, Jan 28, 2012 at 6:22 PM, Mark Voorhies <[hidden email]> wrote:
> > I just started using the notebook yesterday (following an upgrade to Firefox 9)
> > and it's awesome -- so much so that I'm switching to it for everyday work and
> > am planning to teach from it in April.
> >
> > One thing I would like to hack on is an equivalent to the qtconsole's "export
> > with inlined images" (xhtml+svg / html+inlined png) function (so that I can
> > save/e-mail finished work as a single file with no dependencies).
>
> Yes, we *really* would like to have this capability and are more than
> willing to help you get started.  Here is a few points:
>
> * The IPython.nbformat.v3 subpackage has an infrastructure for
> notebook readers/writers.  We currently have one for .json and .py
> files.  This is the place to create one for exporting to HTML.
> * Exporting to raw HTML is not quite possible.  The reason for this is
> that we use a couple of Javascript libraries:  MathJax for rendering
> latex embedded in the HTML, CodeMirror for formatting the code areas
> with syntax highlighting, and A Markdown parser that converts Markdown
> to HTML.  We will have to figure out substitutes for these JS
> libraries in the HTML export.
> * There are two possible ways of generating raw HTML:
>
> 1) First export to reST and then use rst2html to get to the HTML.
> Some benefits to this, but the downside is that raw Markdown/HTML
> cells would get lost in the process (although I think that reST
> suports raw HTML inclusion.  Also, this would make it more difficult
> to control exactly what the HMTL looks like (IOW use our current CSS
> styling).
> 2) Use a templating library to export directly to HTML.  I think this
> is very worth pursuing as a first line of attack.  The would allow you
> to simply recreate the right HTML structure with the proper id/classes
> and then inline our CSS.  It would give you exactly the same look as
> we have now.  We would still need to figure out how to handle MathJax,
> CodeMirror and Markdown though.
>
> I imagine that in the long run we will support both of these routes.
> Once we have the writers in place in IPython.nbformat.v3, it will be a
> simple matter of incorporating them into the notebook server.
>
> Here is a github issue where we should continue this discussion:
>
> https://github.com/ipython/ipython/issues/860
>
> Fernando even has a draft reST exporter implemented.  Let us know if
> you have questions.

Thanks!  I'll watch for the notebook printing commit and chime in on
the issue once I have time to start outlining/hacking -- probably this
weekend.

--Mark

>
> Cheers,
>
> Brian
>
> > The print window circa a50ac36bd554 looks like the right starting point (it
> > would just need inlining of the css and images), but it looks like this version
> > was scrapped when the wijmo menus were added and that there now may be
> > different ideas for printing (https://github.com/ipython/ipython/issues/1292).
> >
> > So -- is this a good time to start working on this sort of inlining (and, if so,
> > which code should I be looking at) or would it be better to wait for the next
> > print window revision (and is there an issue/PR that I should be watching
> > for this)?
> >
> > Thanks,
> >
> > Mark
> >
> > _______________________________________________
> > IPython-dev mailing list
> > [hidden email]
> > http://mail.scipy.org/mailman/listinfo/ipython-dev
>
>
>
>

_______________________________________________
IPython-dev mailing list
[hidden email]
http://mail.scipy.org/mailman/listinfo/ipython-dev
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Status of printing in the notebook

Brian Granger-3
The notebook printing bug turned out to be quite subtle and its fix is
leading to the refactoring of a lot of code.  It may take a big longer
than I thought, but hopefully in the next few days.

On Tue, Jan 31, 2012 at 7:34 PM, Mark Voorhies <[hidden email]> wrote:

> On Tuesday, January 31, 2012 01:09:03 pm Brian Granger wrote:
>> Mark,
>>
>> Sorry it has taken a few days to get back to you about this.  There is
>> a lot of activity on the notebook right now and I am having a tough
>> time keeping up (even though I am working on it full time!).
>>
>> First, I will fix the notebook printing hopefully today, maybe early tomorrow.
>>
>> On Sat, Jan 28, 2012 at 6:22 PM, Mark Voorhies <[hidden email]> wrote:
>> > I just started using the notebook yesterday (following an upgrade to Firefox 9)
>> > and it's awesome -- so much so that I'm switching to it for everyday work and
>> > am planning to teach from it in April.
>> >
>> > One thing I would like to hack on is an equivalent to the qtconsole's "export
>> > with inlined images" (xhtml+svg / html+inlined png) function (so that I can
>> > save/e-mail finished work as a single file with no dependencies).
>>
>> Yes, we *really* would like to have this capability and are more than
>> willing to help you get started.  Here is a few points:
>>
>> * The IPython.nbformat.v3 subpackage has an infrastructure for
>> notebook readers/writers.  We currently have one for .json and .py
>> files.  This is the place to create one for exporting to HTML.
>> * Exporting to raw HTML is not quite possible.  The reason for this is
>> that we use a couple of Javascript libraries:  MathJax for rendering
>> latex embedded in the HTML, CodeMirror for formatting the code areas
>> with syntax highlighting, and A Markdown parser that converts Markdown
>> to HTML.  We will have to figure out substitutes for these JS
>> libraries in the HTML export.
>> * There are two possible ways of generating raw HTML:
>>
>> 1) First export to reST and then use rst2html to get to the HTML.
>> Some benefits to this, but the downside is that raw Markdown/HTML
>> cells would get lost in the process (although I think that reST
>> suports raw HTML inclusion.  Also, this would make it more difficult
>> to control exactly what the HMTL looks like (IOW use our current CSS
>> styling).
>> 2) Use a templating library to export directly to HTML.  I think this
>> is very worth pursuing as a first line of attack.  The would allow you
>> to simply recreate the right HTML structure with the proper id/classes
>> and then inline our CSS.  It would give you exactly the same look as
>> we have now.  We would still need to figure out how to handle MathJax,
>> CodeMirror and Markdown though.
>>
>> I imagine that in the long run we will support both of these routes.
>> Once we have the writers in place in IPython.nbformat.v3, it will be a
>> simple matter of incorporating them into the notebook server.
>>
>> Here is a github issue where we should continue this discussion:
>>
>> https://github.com/ipython/ipython/issues/860
>>
>> Fernando even has a draft reST exporter implemented.  Let us know if
>> you have questions.
>
> Thanks!  I'll watch for the notebook printing commit and chime in on
> the issue once I have time to start outlining/hacking -- probably this
> weekend.
>
> --Mark
>
>>
>> Cheers,
>>
>> Brian
>>
>> > The print window circa a50ac36bd554 looks like the right starting point (it
>> > would just need inlining of the css and images), but it looks like this version
>> > was scrapped when the wijmo menus were added and that there now may be
>> > different ideas for printing (https://github.com/ipython/ipython/issues/1292).
>> >
>> > So -- is this a good time to start working on this sort of inlining (and, if so,
>> > which code should I be looking at) or would it be better to wait for the next
>> > print window revision (and is there an issue/PR that I should be watching
>> > for this)?
>> >
>> > Thanks,
>> >
>> > Mark
>> >
>> > _______________________________________________
>> > IPython-dev mailing list
>> > [hidden email]
>> > http://mail.scipy.org/mailman/listinfo/ipython-dev
>>
>>
>>
>>
>
> _______________________________________________
> IPython-dev mailing list
> [hidden email]
> http://mail.scipy.org/mailman/listinfo/ipython-dev



--
Brian E. Granger
Cal Poly State University, San Luis Obispo
[hidden email] and [hidden email]
_______________________________________________
IPython-dev mailing list
[hidden email]
http://mail.scipy.org/mailman/listinfo/ipython-dev
Loading...