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

[Anthony Scopatz]

My problem is basically the same as Nathan's :)  I'd love to see an
official solution to it.

Be Well
Anthony


On Wed, Feb 26, 2014 at 7:13 PM, Nathan Goldbaum <nathan12343 at gmail.com>wrote:

> 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
> >
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20140226/023eed89/attachment.html>