Notebook guide enhancements

[eteq]

This makes a substantial set of changes to the notebook style guide. Aside from modification of text to inject @eteq's Opinions in a variety of places, there are a couple substantive structural changes, including:

• Walked back a bit of the "make no assumptions" part. I think there is a place for notebooks that, say, assume a certain level of knowledge of astronomy, but the real point (to me) is that you shouldn't do that unless you mean to. So it's not "make no assumptions" as much as "make no assumptions, unless you've thought hard and decided you really mean to". But of course there's room for discussion there.
• Added a bit about how when describing loaded data: basically, you should try to show the data rather than using text to describe it, and I gave an example of that using an astropy table.
• Moved all the images to an images directory and all relative links. I wasn't sure this would work, but assuming https://github.com/eteq/style-guides/blob/nb-additions/guides/jupyter-notebooks.md is representative of what we'll see in master, it seems github is smart enough to follow the relative links and use the raw version...
• Re-organized things a bit to reduce duplication and include the Prose section as part of the design principles
• Removed the Table of Contents from the recommended structure. I think this is not desirable because 1) If someone later modifies the notebook they have to modify the ToC, and will probably forget 2) Once the automated tools to generate html versions of the notebook are ready, they come with a ToC built into the sidebar. 3) Some notebook extensions now use the header levels to auto-generate ToCs and if you also have a manual ToC it's really confusing: you get two different ToC structures unless the author is exceedingly disciplined
• Added an "optional" section for Exercises. In my experience this is a good idea almost no matter what because it breaks users out of the "just execute every cell until the bottom" mode.

I tried to keep these pieces as fairly atomic commits so can revert them if anyone disagrees with one of them...

cc @arfon @ivastar

[pllim]

Haven't had the chance to catch up on all the reading, so perhaps my two questions below are already answered...

1. Are all imports at the beginning really ideal? I was told by a different source that it is better to import when used.
2. Is it better to add notebooks to repo with outputs cleared or pre-populated?

[arfon]

Responding to @pllim:

Are all imports at the beginning really ideal? I was told by a different source that it is better to import when used.

IMO having them at the top makes it clearer what packages are being used within the notebook so it's preferable from a usability standpoint?

Is it better to add notebooks to repo with outputs cleared or pre-populated?

As mentioned in the guide (but not yet reality), we're planning on compiling these as the Astropy tutorials repo does which means we'd encourage people to read the compiled/executed versions on Readthedocs.

[pllim]

IMO having them at the top makes it clearer what packages are being used within the notebook so it's preferable from a usability standpoint?

Perhaps for static ones. In my experience, when I update a notebook, if all the imports are on top, and I have to add a new import, then I have to scroll all the way up to add it. If I remove a cell, I have to remember to scroll all the way up to delete the import. 🤷‍♀️

[eteq]

Re: @pllim's

Perhaps for static ones. In my experience, when I update a notebook, if all the imports are on top, and I have to add a new import, then I have to scroll all the way up to add it. If I remove a cell, I have to remember to scroll all the way up to delete the import.

I see this point. This guide is generally for "notebooks that are meant to be presented", but it's a valid point that there's a use case of "notebooks that capture an actual real analysis workflow". In that case, it's often a practical choice to do just what @pllim says.

[eteq]

Because I think what's in here is still true for the "presented" case, I think I'm going to merge this - some other folks looking at the guide for some imminent work I think will want to see this content.

But @pllim, do you think you can either make an issue, or better yet a PR, that adds some words along the lines of what you suggested? That way we can have this discussion but not have it hold up the other stuff.

[pllim]

@eteq , I barely do any "real analysis" nowadays. I don't have motivation to follow up on it. Whatever is here is fine. 😄