DOC: README.md: Inline i/o from Example.ipynb

[westurner]

Could the usage examples from Example.ipynb be inlined into the README.md?

• https://github.com/chmp/ipytest/blob/main/Example.ipynb
• The last time I tried to email a nb with output to a mailing list, IIRC it was easiest to pandoc --from=html --to=gfm than to try and save the input and output cells to Markdown with Jupyter nbconvert or jupytext.
  (... Why {base64 output etc} is not included in most non-.ipynb notebook representations:
  • HTML5/RDFa is not XHTML, and inlined HTML should have CDATA and/or must be escaped, which is what nbconvert does when generating HTML from .ipynb JSON.
    From https://stackoverflow.com/questions/3302648/should-i-use-cdata-in-html5 :

    <!--//--><![CDATA[//><!--
        ...
    //--><!]]>
    ``` )

[westurner]

@fperez @Carreau @choldgraf @mwouts
If README.md were MyST-Markdown (e.g. as processed by executablebooks/jupyter-book), it still wouldn't have the cell outputs in the Markdown for the README, AFAIU?

• Hide inputs, include outputs in Markdown format mwouts/jupytext#220

[chmp]

I guess in general the Readme could use a bit of a touch up and reorganization. As the Readme is quite long as-is, I am not really in favor of adding more content, though.

• Do you have any specifc parts of the use example in mid that are missing from the Readme?
• Or any specific information that is hard to find?

Re how to achieve this: I guess writing a custom converter would be easiest (the notebook format is quite easy to parse).

[westurner]

Just that "Extended Usage" is more apidoc (see also sphinx-apidoc & jupyter-book, nbdev) than usage examples.

Maybe just bold the "example notebook" link?

[mwouts]

Hey @westurner , yes you're right in the end we never developed the text notebook format with outputs - sorry about that.

I like seeing this project about making test available in the notebook! BTW Jupyter and Pytest are probably my two favorite tools. In Pytest I write a lot of fixtures (sample data sets), do you plan to make them accessible from Jupyter ? I've always wondered what is the best way to get these data sets in Jupyter for interactive exploration when I work on a new test...

[fperez]

See my note here re. recent discussion about md+outputs, I hope it's useful.

[chmp]

Just that "Extended Usage" is more apidoc (see also sphinx-apidoc & jupyter-book, nbdev) than usage examples.

Maybe just bold the "example notebook" link?

@westurner That's a fair point. I will experiment a bit with rewriting the readme. Getting a bold link to the example notebook, should be doable whatever I come up with :)

I like seeing this project about making test available in the notebook! BTW Jupyter and Pytest are probably my two favorite tools. In Pytest I write a lot of fixtures (sample data sets), do you plan to make them accessible from Jupyter ? I've always wondered what is the best way to get these data sets in Jupyter for interactive exploration when I work on a new test...

@mwouts what are you exact requirements? Fixtures should already work. So far I did not run into any problems, but I guess it depends a bit your usage pattern. Example:

import ipytest
ipytest.autoconfig()

---

%pycat conftest.py

import pytest 

@pytest.fixture
def my_fixture():
    return 21

---

%%ipytest

def test_example(my_fixture):
    assert my_fixture * 2 == 42

.                                                                                            [100%]
1 passed in 0.00s

[chmp]

Work on readme started in #92.

[chmp]

Updated docs: simplified readme with a more prominent link to the example notebook.