Lack of homepage example

[jameshfisher]

The homepage starts out by asking, "Have you always wished Jupyter notebooks were plain text documents?" Yes! A great start.

My natural next question was: Does Jupytext deliver on the claim that it lets me write notebooks in "plain text"? Or is it a false promise, more like "JSON with some Markdown mixed in"?

To answer that, I wanted an extended example of what a Jupytext file looks like. But that was surprisingly hard to find. I clicked through every page of the docs, and looked at the Github README. I found nothing.

I then went to close the page, but thought you might appreciate feedback on my experience. IMO you'd benefit a lot by adding an extensive example to the homepage.

[mwouts]

Hey @jameshfisher , thanks for your feedback.

Well there are several formats and it would be a bit too long to document all of them in the readme.

Nevertheless we have this section about which format we recommend depending on your use case:
https://github.com/mwouts/jupytext#which-text-format (with links to the docs)

You can also have a look at the examples directly: https://github.com/mwouts/jupytext/tree/main/demo

[mnhrdt]

I concur with @jamesfisher. A minimal "hello world" example in the landing page would be an extremely powerful case for jupytext. As the main jupytext advocate in my lab, I find the homepage a bit lackluster when I point my colleagues to it. Of course there are several formats, but just show the simplest possible one. Like this:

# hello.py
# This is a complete jupytext notebook.
# Comments are markdown cells, verbatim code are code cells.

print("you can run this python program or open it with your browser as a notebook")

print ("a blank line separates cells")

# A markdown cell with some LaTeX: $\sum_{n=1}^\infty \frac1{n^2} = \frac{\pi^2}6$

And then show a screenshot of the browser showing this as a notebook:

[jameshfisher]

Ha - I feel like I just learned more from @mnhrdt 's small example than I did when I was browsing the docs!

[mwouts]

😄 thanks for challenging me, actually I think you're right. I'll update the README hopefully later today.

[mwouts]

Well, it took me a bit longer than expected, but at least it finally happened... let me know what you think of the new README.md!

[jameshfisher]

This looks much better! ❤️

[mnhrdt]

Looks great! (though I have a preference for the light format, which is easier to sell to people who prefer to edit notebooks with a text editor)