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

[Nathan Goldbaum]

Hi Ian,

I've spent a bit of time thinking about how to include the output from
nbconvert into a sphinx document.

My problem was a little bit different.  I wanted to include the
notebook as a unit, including input cells, so that contributors could
write documentation inside of the notebook and have it be included in
more or less the same format in our final docs build.

An example of the results is here:
http://ngoldbaum.net/docs_build/analyzing/units/index.html

Click through to the subsections to see the converted notebooks.

The extension that makes this possible is here:
https://bitbucket.org/ngoldbaum/yt-mattfork/src/1923fae835fe1d1bf8145c46b6062ca9e9523f44/doc/extensions/notebook_sphinxext.py?at=yt-3.0

With this approach the notebook is stored inside the docs repository
in an unevaluated state.  As part of the build, the notebook is
evaluated by runipy and then converted to HTML with nbconvert.  The
HTML/CSS is then sanitized to not conflict with styles defined by the
sphinx theme (in an ad-hoc totally not nice way).

Not sure if this is where you're going with what you're describing,
but you may find some of the code I've come up with useful.

Cheers,

Nathan

On Wed, Feb 26, 2014 at 3:58 PM, Ian Bell <ian.h.bell at gmail.com> wrote:
> 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
>
> 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
> * 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 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, 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
>
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
>