[yt-dev] Issue #712: Use notebook and notebook-cell all over the docs (yt_analysis/yt)

[Nathan Goldbaum]

New issue 712: Use notebook and notebook-cell all over the docs
https://bitbucket.org/yt_analysis/yt/issue/712/use-notebook-and-notebook-cell-all-over

Nathan Goldbaum:

We should have dynamically evaluated code snippets in more places in the docs.

You can replace whole blocks of text with notebooks, so long as there aren't any sphinx cross-references (sphinx `:ref:` directives).  If you'd like to keep sphinx formatting and functionality, you can replace inline python or bash `code-block` cells with `notebook-cell` (using the %bash magic in the latter case).  This will produce an embedded one-cell mini notebook with the code in the docs source evaluated and all output captured by the notebook at runtime.

Having both the input and output embedded in the docs makes the code snippets more meaningful and therefore easier to understand.

Doing so also increases our test coverage, since changes in the docs build will likely be due to regressions.  Having comprehensive docs therefore also helps us maintain the user-facing code, some of which may not be used very often or is not well tested.