QuantEcon Python programming example

[jstac]

I've requested that @najuzilu help us by converting this source material

https://github.com/QuantEcon/lecture-python-programming/tree/master/source/rst

into myst-based source and then generating html output via the new jupyter-book CLI.

The idea is to implement a non-trivial example with a substantial amount of source material. Currently it includes embedded code + outputs, cross-refs across pages, footnotes and maths.

@najuzilu, if I remember correctly, the objective is to have this done by 30th this month. Please coordinate

• with @AakashGfude and @choldgraf regarding addition of execution layer and embedded outputs
• with @choldgraf about the documentation for the CLI and how it could be improved
• with me (@jstac) regarding content -- I want us to add in a few citations as well
• with @mtiley as required --- I think he's willing to lend a hand.

Please supply feedback as you go along and update us in this issue.

If you have time, please also investigate PDF output direct from the html. @phaustin mentions some options in https://github.com/ExecutableBookProject/meta/issues/44#issuecomment-602678986

[mtiley]

@najuzilu @jstac yep I can help if needed.

[jstac]

What might also be useful is if @mtiley and @najuzilu write a short blog post called "Writing lectures with MyST source files via Jupyter Book" that describes what they've done, how they've done it and how others can replicate. It could, for example, be posted here: https://quantecon.org/news/

[phaustin]

@najuzilu, @jstac, @choldgraf et al. I've added a page (https://eoas-ubc.github.io/paged_trio) that shows rendered comparisons for one of our quiz notebooks, with notes on problems with github, nbconvert_classic and paged_trio.

tldr -- neither nbconvert or the pagedown mathjax code I borrowed is able to make the second pass required to render equation numbers. I'm assuming this isn't the case with jupyter book?

As far as pagedjs goes, the single best resource for seeing how to make a latex replacement are the comprehensive examples at https://print-css.rocks/lessons. As chrome-headless implements the css3 standard we should be able to relax the polyfill requirement, but for now it's giving me what I need (page numbers in the header and hard pagebreaks)

[jstac]

Thanks @phaustin.

I think numbered eqs are working fine in myst-nb, since they work in myst-parser (https://myst-parser.readthedocs.io/en/latest/examples/wealth_dynamics_md.html#a-model-of-wealth-dynamics). But I don't see any in the docs. Perhaps @mtiley might be able to confirm and if so add an example to the myst-nb docs?

[phaustin]

That's helpful, thanks. Looks like you're adding the mathjax link in the header with an explicit async keyword -- I'll play around with that.

<title>Wealth Distribution Dynamics in MyST &#8212; MyST Parser  documentation</title>
--
...
  | <script src="https://assets.readthedocs.org/static/javascript/readthedocs-doc-embed.js"></script>
  | <script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>

[mtiley]

@jstac yes, equation numbering seems to be working in myst-nb. There is an example in the docs in the glue section here but it's not very visible.

I think it's a good idea to add an example to the An example Jupyter Notebook page (basic.html) to indicate that MyST features (that work in myst-parser) should also work with MyST-NB.

I'll make a PR for the docs shortly

[najuzilu]

Hi all, I just want to give a quick update.

Thanks @choldgraf, @AakashGfude, and @chrisjsewell for your hard work and for putting up with all my issues! :-)

The book example is currently live - you can access it here. It is still work in progress, so I would appreciate any feedback.

@jstac made a list in #46 which I have used as a guideline for this project. Our example includes the following features - they're linked with specific examples:

• Code: inputs and outputs
• Inline and displayed maths
• [Citations]()
• Footnotes
• Cross-refs within and between pages including numbered equations
  • Cross-ref between pages
  • Cross-ref within page
  • Cross-ref within page including numbered eq
  • Glue functionality in MyST-NB

Next, I'll be working on the following features and will provide an update soon:

• Figures with captions and cross-refs

[chrisjsewell]

Looking good 👌

[choldgraf]

niiiice! It looks great! I noticed a few design niggles in there that I can try to fix in the book theme 👍

[choldgraf]

ah actually I wonder if the CSS differences are because you're using jupyter-sphinx instead of the myst-nb execution stuff?

[najuzilu]

I updated from {execute} to {jupyter-execute} and still getting the same CS rendering... And I made sure to update myst-nb, sphinx-book-theme, and cli.

[choldgraf]

@najuzilu that's to be expected, you're still using the same underlying function, it's just called jupyter-execute instead of execute now. The real test will be once https://github.com/ExecutableBookProject/MyST-NB/pull/116 gets merged, which is a proper "myst markdown to notebook conversion" functionality.

So when that gets merged - to use myst-nb instead of jupyter-sphinx, you'll need to convert these cells to {code-cell} and make sure there's the proper jupytext metadata at the top (which @chrisjsewell laid out in some documentation so comments on that would be helpful too!)

[jstac]

The real test will be once ExecutableBookProject/MyST-NB#116 gets merged

Which is now merged! Amazing how quickly this is coming together. Very excited to see how this works for your @najuzilu :-)

[jstac]

Hi @najuzilu, I think we can just about close this issue thanks to your hard work.

(I'm just pushing some small changes now to tidy up some loose ends.)

Is there anything else you wanted to achieve with this example? We mentioned figure captions above but they're not really crucial. Anything else?

@choldgraf, is there anything else you wanted to show off? If not please go ahead and close the issue.

[choldgraf]

Oops, dunno how I missed this one, but it looks good to me. How does this example fit in with the broader quantecon one that we we planning to use for the getting started guide?

[jstac]

This is the longer example, with more bells and whistles. The shorter, broader one is the mini one here.