search

QuantEcon / sphinxcontrib-jupyter

A Sphinx Extension for Generating Jupyter Notebooks
BSD 3-Clause "New" or "Revised" License
77 stars 23 forks source link

Provide a minimal example of jupinx-enabled sphinx project #21

Closed nthiery closed 6 years ago

nthiery commented 6 years ago

Hi, I am going through the process of setting up jupinx for my favorite sphinx documents following the instructions in the README. I am encountering a few undocumented steps (e.g. having to add a jupyter dependency in the Makefile, or a jupyter_headers variable in conf.py), and now a rougher edge:

preparing documents... done
writing output... [  1%] 2009-01-01-SienaTutorials/Worksheet01-GettingHelp                                                                                                                                           
Exception occurred:
  File "/opt/sphinxcontrib-jupyter/sphinxcontrib/jupyter/writers/translate_all.py", line 258, in depart_list_item
    if self.markdown_lines[-1][-1] == "\n":
IndexError: list index out of range
The full traceback has been saved in /tmp/sphinx-err-3ac4qcm9.log, if you want to report the issue to the developers.

To move forward, it would be helpful to have a minimal example of sphinx project with jupinx enabled for testing and comparison.

Thanks in advance!

jstac commented 6 years ago

Hi @nthiery many thanks for your feedback. @NickSifniotis Do you have any time to look at this? @mmcky will be away until early Jan.

mmcky commented 6 years ago

add this to the docs: https://github.com/QuantEcon/sphinxcontrib-jupyter/pull/10

mmcky commented 6 years ago

A minimal example has now been setup in an accompanying repository

https://github.com/QuantEcon/sphinxcontrib-jupyter.minimal

Note: this example currently requires the latest master of the extension as it requires basic RST tables support. The current version on PyPI does not support RST tables. I am waiting for credentials to be transferred to make a new release.

nthiery commented 6 years ago

A minimal example has now been setup in an accompanying repository

Excellent, thanks! I am going to try it out very soon.

cc: @ocayrol

nthiery commented 6 years ago

Quick feedback: it work smoothly!

Just one tiny caveat: the table of content of index.ipynb was not rendered properly due to missing new lines in the markdown:

Contents:- [Simple Notebook Example](simple_notebook.ipynb#)- [Math](simple_notebook.ipynb#math)- [Tables](simple_notebook.ipynb#tables)