cookie icon indicating copy to clipboard operation
cookie copied to clipboard
verified publisher icon scientific-python

Add guide on executable documentation

Open danielballan opened this issue 2 years ago • 3 comments

Following up #136, investigate whether we should recommend:

  • Jupytext
  • the ipython sphinx directive
  • the matplotlib plot directive

I suspect that Jupytext is now the best way to do this, and more compatible with a Markdown-based approach, but I want to educate myself more.

danielballan avatar May 26 '23 23:05 danielballan

I started looking at this more today, aligned with a day-job task. I intend to put up a PR on this in the next week or so.

danielballan avatar Feb 13 '24 01:02 danielballan

Following up here to mention, belatedly, that I have a self-contained demo repo illustrating some nice patterns for interactive documentation:

  • source in Markdown (not ipynb JSON)
  • auto-generated branch with ipynb JSON
  • published HTML with executed code
  • Binder
  • Jupyter Lite (proof of concept)

https://github.com/danielballan/interactive-tutorial-demo

I could imagine promoting this to live in the scientific-python org if there is support and interest.

danielballan avatar Nov 11 '24 15:11 danielballan

Given the range of technologies and use cases, I think it would be too heavy to include in this repository, so I would advocate for linking out. Most major projects have a dedicated "examples" repo separate from the main library to do things like this.

danielballan avatar Nov 11 '24 15:11 danielballan