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?

• https://github.com/mwouts/jupytext/issues/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:

```python import ipytest ipytest.autoconfig() ``` --- ```python %pycat conftest.py ``` ```python import pytest @pytest.fixture def my_fixture(): return 21 ``` --- ```python %%ipytest def test_example(my_fixture): assert my_fixture * 2 == 42 ``` ```text . [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.