[IPython-dev] Ipython notebook + nbipy + sphinx = aweome documentation
scopatz at gmail.com
Wed Feb 26 20:17:25 EST 2014
My problem is basically the same as Nathan's :) I'd love to see an
official solution to it.
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:
> Click through to the subsections to see the converted notebooks.
> The extension that makes this possible is here:
> 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.
> 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,
> > In short, what I am trying to do is to build run-time documentation that
> > shows deviations between my package and the reference (proprietary)
> > REFPROP. Embedding iPython notebooks directly in webpages is pretty ugly
> > (more work could be done here). One of my biggest complaints is the
> > 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
> > to develop a template for nbconvert based on the input hiding template,
> > 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
> > 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
> > of the conversion.
> > It works pretty much great. But there are a couple of issues. When
> > 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()
> > # 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
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the IPython-dev