Tree @HEAD (Download .tar.gz)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 | ################################################## nb2plots - converting between notebooks and sphinx ################################################## See the nb2plots documentation_ for more information. .. shared-text-body ************ What it does ************ ``nb2plots`` converts Jupyter_ notebooks to ReST_ files for Sphinx_, and back again. Nb2plots assumes that the ReST document will become the source for your Sphinx web pages, but also for future versions of the notebook. The notebook may serve as a draft for the polished ReST page, and an output format from the Sphinx build. Why? Read on. **************************************** Why convert Jupyter notebooks to Sphinx? **************************************** Jupyter notebooks are just what the doctor ordered when hacking up a quick tutorial, or preparing a software demo. The problems start when you want to do not-trivial edits to the notebooks, or you need features that notebooks don't have, such as flexible cross-referencing, extensible markup, and so on. Notebooks are also painful to use with version control. These times make you wish your notebook was in a standard extensible text format, such as ReST_. You could convert your notebook to ReST using the standard `nbconvert`_ command, but this gives rather ugly ReST, and you lose all the nice code execution and figure generation that the notebook is good at. Enter Nb2plots. The ``nb2plots`` command converts notebooks to specially formatted ReST pages. Use with:: nb2plots notebook.ipynb > with_plots.rst Nb2plots converts your notebook to not-very-ugly ReST, where the code cells become ``nbplot`` directives in your ReST file. Specifically, a notebook code cell like this:: a = 1 becomes (in the ReST document):: .. nbplot:: >>> a = 1 The ``nbplot`` directives run the contained code when Sphinx builds your ReST files, and embed the results of any plots that your code makes. Actually, ``nbplot`` is an extended and edited version of the `matplotlib plot directive`_. Building your pages runs all the code and regenerates the figures, and you get much of the reproducible goodness of the notebook experience. You can also run the standard Sphinx ``doctest`` extension over your pages to check the doctest output of the code cells. The ReST version of your notebook has many advantages - it is easier to edit in your favorite text editor, and you can extend and configure the execution and display of the code in several different ways. For example, you can hide some code cells (Nbplot directives) if the code is not interesting to your point, but you still want the generated figure. You can configure your Nbplot directives to run different code for different configurations. For these options, see |nbplot-documentation|. But - what do you lose, when going from a notebook to a Nb2plots ReST document? ********************************** I want notebooks and .py files too ********************************** You may also want a version of your document that your users can execute. Perhaps the page build is generating some tricky errors or warnings, and you want to experiment with the code in the page interactively. Perhaps your users are used to notebooks, and prefer the code in that format. Nb2plots also contains Sphinx extensions that cause the Sphinx build to generate Python code files and Jupyter notebooks from the ReST source. When you add the Nb2plots ReST directive ``code-links`` to your ReST page, it will cause the Sphinx build to create a Python code file and notebook versions of your page, and adds download links to these versions:: .. code-links:: See |code-links-documentation| for details. ************************** Show me what it looks like ************************** For a very simple example, see |worked-example|. For a moderate-sized teaching site that makes extensive use of Nb2plots, see https://matthew-brett.github.io/teaching. ************ Installation ************ :: pip install nb2plots You will need Pandoc_ installed and available as the ``pandoc`` command. To install Pandoc on OSX, we recommend homebrew_:: brew install pandoc ************* Configuration ************* Add the following to your Sphinx ``conf.py`` file:: extensions = ["nb2plots"] See |nbplot-documentation| for the various ``conf.py`` configuration settings. **** Code **** See https://github.com/matthew-brett/nb2plots Released under the BSD two-clause license - see the file ``LICENSE`` in the source distribution. `travis-ci <https://travis-ci.org/matthew-brett/nb2plots>`_ kindly tests the code automatically under Python versions 2.7, and 3.5 through 3.8. The latest released version is at https://pypi.python.org/pypi/nb2plots ***** Tests ***** * Install ``nb2plots`` * Install the pytest_ testing framework, the ``mock`` package, and the ``scripttester`` package. pip install pytest mock scripttester * Run the tests with:: py.test --pyargs nb2plots ******* Support ******* Please put up issues on the `nb2plots issue tracker`_. .. standalone-references .. |nbplot-documentation| replace:: `nbplots documentation`_ .. |worked-example| replace:: `worked example`_ .. |code-links-documentation| replace:: `code-links documentation`_ .. _nbplots documentation: https://matthew-brett.github.io/nb2plots/nbplots.html .. _code-links documentation: https://matthew-brett.github.io/nb2plots/code_links.html .. _worked example: https://matthew-brett.github.io/nb2plots/worked_example.html .. _documentation: https://matthew-brett.github.io/nb2plots .. _pandoc: http://pandoc.org .. _jupyter: jupyter.org .. _homebrew: brew.sh .. _sphinx: http://sphinx-doc.org .. _rest: http://docutils.sourceforge.net/rst.html .. _nb2plots issue tracker: https://github.com/matthew-brett/nb2plots/issues .. _matplotlib plot directive: http://matplotlib.org/sampledoc/extensions.html .. _nbconvert: http://nbconvert.readthedocs.org/en/latest/ .. _pytest: https://pytest.readthedocs.io .. _mock: https://github.com/testing-cabal/mock |
Commit History @HEAD
0
»»
- Merge branch 'scrub-obsolete' into 'master' Sandro Tosi 2 years ago
- Remove constraints unnecessary since buster Jenkins 2 years ago
- Merge branch 'lintian-fixes' into 'master' Sandro Tosi 2 years ago
- Update standards version to 4.5.1, no changes needed. Debian Janitor 2 years ago
- Set upstream metadata fields: Bug-Database, Bug-Submit, Repository, Repository-Browse. Debian Janitor 2 years ago
- Bump debhelper from deprecated 9 to 13. Debian Janitor 2 years ago
- Use the new Debian Python Team contact name and address Sandro Tosi 3 years ago
- d/control: Update Vcs-* fields with new Debian Python Team Salsa layout Ondřej Nový 3 years ago
- releasing package nb2plots version 0.6-2 Sandro Tosi 4 years ago
- extrend packaging copyright years Sandro Tosi 4 years ago
- bump Standards-Version to 4.4.1 (no changes needed) Sandro Tosi 4 years ago
- Drop python2 support; Closes: #937116 Sandro Tosi 4 years ago
- Use debhelper-compat instead of debian/compat Ondřej Nový 4 years ago
- Remove trailing whitespaces. Chris Lamb 5 years ago
- add nbformat to depends, needed by the ipython shim module Sandro Tosi 5 years ago
- debian/copyright: Use HTTPS for Source field. Chris Lamb 5 years ago
- debian/control: Use HTTPS for Homepage field. Chris Lamb 5 years ago
- add sphinxtesters, texext to b-d Sandro Tosi 6 years ago
- install scripts only in the py3k package Sandro Tosi 6 years ago
- update copyright Sandro Tosi 6 years ago
- dont run tests for now, they depend on unpackaged modules Sandro Tosi 6 years ago
- Standards-Version: 4.1.4 Sandro Tosi 6 years ago
- build py2 and py3k packages Sandro Tosi 6 years ago
- close ITP Sandro Tosi 6 years ago
- add initial Debian packaging Sandro Tosi 6 years ago
- import nb2plots_0.6.orig.tar.gz Sandro Tosi 6 years ago
0
»»