[IPython-dev] Ipython notebook + nbipy + sphinx = aweome documentation

[Ian Bell]

Hello everyone,

I've been hacking away with the documentation of an open-source
thermophysical property library that I am the primary developer of,
CoolProp<http://coolprop.sf.net>

In short, what I am trying to do is to build run-time documentation that
shows deviations between my package and the reference (proprietary) package
REFPROP.  Embedding iPython notebooks directly in webpages is pretty ugly
(more work could be done here).  One of my biggest complaints is the
showing of the input cells in the output.  I understand the use case here -
It's quite clear. But sometimes you don't want that behavior.  So what I
did was to develop a template for nbconvert based on the input hiding
template, but modified it for my purposes.

The basic workflow is this:
* Start with a IPython notebook template file
Fluidtemplate.ipynb<https://github.com/ibell/coolprop/blob/master/Web/FluidTemplate.ipynb>
* In a batch file, inject the fluid name into the template (seems this is
also possible using runipy, though I haven't played with this) and convert
to HTML.  We use this nbconvert
template<https://github.com/ibell/coolprop/blob/master/Web/output_toggle.tpl>file
to view the inputs when you click on the figures generated. This
script generates html files using runipy that are then raw imported into
the RST files for sphinx.
* Then if you pick one of the fluids, lets say
water<http://coolprop.sourceforge.net/Fluids/Water.html>,
you can see the output of the conversion.

It works pretty much great.  But there are a couple of issues.  When
running runipy, I found I had to comment out like in

def parse_date(s):
    """parse an ISO8601 date string

    If it is None or not a valid ISO8601 timestamp,
    it will be returned unmodified.
    Otherwise, it will return a datetime object.
    """
    if s is None:
        return s
    m = ISO8601_PAT.match(s)
#     if m:
#         # FIXME: add actual timezone support
#         # this just drops the timezone info
#         notz = m.groups()[0]
#         return datetime.strptime(notz, ISO8601)
    return s

in order to avoid errors like

File "C:\Python27\lib\site-
packages\ipython-2.0.0_dev-py2.7.egg\IPython\utils\jsonutil.py", line 79,
in parse_date
    return datetime.strptime(notz, ISO8601)
AttributeError: _strptime

This is a weird error since the call is to datetime.strptime not
datetime._strptime. Anyway...

Also, I can't figure out how to make the paragraph marker not be always
visible, rather visible on hover-over like in normal sphinx.

In any case, I'm pretty pleased, though I would be happy for any
thoughts/recommendations.

Ian
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20140227/6d213586/attachment.html>