Complete rewrite of IPython Notebook documentation: docs/source/interactive/htmlnotebook.txt

[dpsanders]

This is a complete rewrite of the main entry point to the documentation of the IPython Notebook.

It takes as a base the previous version and turns it into a comprehensive narrative description of the parts and operation of the IPython Notebook 1.0. The necessity of a narrative description was pointed out by @Carreau.

@Carreau also pointed out, in a blog post, that there is a great deal of nomenclatural confusion, since the word "notebook" is used to refer variously to (using the more specific terms that I have introduced in the documentation in this Pull Request):

• the IPython Notebook web application
• the "notebook space", which is the virtual computational space depicted in the web browser
• the notebook document, which is a one-to-one copy of the notebook space (i.e. they are "isomorphic")
• the JSON .ipynb notebook format
• the combination of all of the above, also known as... "the IPython Notebook" !

I have tried very hard to keep all this straight in the documentation. In particular, I always refer to the (IPython) Notebook app with capital 'N', and notebook document files or notebooks with small 'n'. I suggest that this is a simple typographic convenience which goes a long way to disambiguating things. It also has the subtle property of treating the Notebook as a proper noun, i.e. as a living thing ;)

I have tried to keep the informal "you can do this" style from the original document, but sometimes I reverted back to the "this can be done" style -- something to watch out for when reading over it, so we can uniformize the more informal style.

The style of the documentation is to introduce new terms by putting their names in italics, like this, with an informal description first, followed by a more detailed discussion.

Currently the documentation is a monolithic enormous file with too little structure, designed as a drop-in replacement for the previous file in order to have the text written and worry about formatting later.

In reality, this page obviously needs to be split up into several sub-pages, together with figures illustrating what is being discussed, cross-references, web links to the tools mentioned, etc, but perhaps it makes sense to do this after the monolithic version is merged for better atomicity.

A basic division should be made between a basic discussion for users, probably avoiding much mention of servers and kernels in particular, and a more advanced discussion containing all the details of those parts. I am unable to write that part due to my lack of knowledge, but am happy to review it for style, grammar, etc. But we definitely do need a detailed explanation of the kernel--server model, ZeroMQ, tornado, etc., as part of the documentation for IPython Notebook 1.0

Please let me have your frank comments on this PR.

[minrk]

There are a few minor formatting issues, but the text is really excellent, great work! Do you want to finish up cleaning the formatting before we merge?

[jakobgager]

instead

[jakobgager]

@dpsanders: finally, I finished reading through your PR. I really like it!
I've added a bunch of comments - a separate PR against your would have been possible, but I was to lazy to do so 😅

A basic, but fundamental, issue is the splitting of the content into several individual parts. You have already mentioned that. In this context it is IMO important to decide which significance the Notebook App will get within the whole IPython world. If it will be the number one feature everybody is advised to use, than "all" of the IPython features could be introduced based on their Notebook appearance. If it is "just" one of several frontends, it might be a bit trickier to split the information into general parts (related to all IPython products) and frontend specific. In the latter case, the current PR might need some excessive rework.

[jakobgager]

Should we add the config option to use SVG instead of PNG?
%config InlineBackend.figure_format = 'svg'

[minrk]

%pylab should be excluded from this doc.

[dpsanders]

@jakobgager Many thanks for your great effort!

I think it is actually probably harder to review docs than to write them:
A maths professor I once took classes with (W.W. Sawyer, author of some moderately well-known maths pedagogy books, such as Mathematician's Delight) used to talk about "reconstructing the examiner" in an exam, to try and work out what they wanted you to write.

Here it is the same, you have to work out what they had in their head, what they actually wrote down, and then how to bridge the enormous chasm between the two ;)

Let me take a break from this today and make the changes tomorrow.
Of course I agree with you about adding links etc -- this just interrupts the writing process, and is a completely automatic, tedious thing (indeed, should be automated).

Thanks again and looking forward to the next one! Or maybe it's your turn to write and mine to parse...

[minrk]

Thanks to both of your for the review - let's get the mechanical issues resolved here, and get it merged. We can discuss reorganization later.

[jdfreder]

Wow! I haven't read this yet @dpsanders, but it looks like a lot of great work!

[dpsanders]

Thanks! but do reserve judgment until after you've read it :P

On Sun, Jul 21, 2013 at 12:16 AM, Jonathan Frederic <
notifications@github.com> wrote:

Wow! I haven't read this yet @dpsanders https://github.com/dpsanders,
but it looks like a lot of great work!

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/3705#issuecomment-21305335
.

Dr. David P. Sanders

Profesor Titular "A" / Associate Professor
Departamento de Física, Facultad de Ciencias
Universidad Nacional Autónoma de México (UNAM)

dpsanders@gmail.com
http://sistemas.fciencias.unam.mx/~dsanders

Cubículo / office: #414, 4o. piso del Depto. de Física

Tel.: +52 55 5622 4965

[dpsanders]

I have made a branch called notebook-docs-rendered; if you clone it, you should hopefully be able to see the version of the docs rendered by sphinx. Let me know if there's any problem (missing CSS and all that jazz).

I will go over @jakobgager 's great list of corrections tomorrow and add a commit.
It will then be ready for merging.

However... I have just had a revelation. And not of the good kind.

This is a document about the IPython Notebook. Should the documentation not be written in the form of... an IPython notebook? [Note the capitalization ;) ]

Actually, due to the nature of the text, it's not so clear to me. Thoughts? Obviously this would be for after the PR in any case, and sphinx does a very nice job of rendering the HTML.

In fact, is there an easy way of incorporating output of nbconvert into the sphinx workflow?

[minrk]

This is a document about the IPython Notebook. Should the documentation not be written in the form of... an IPython notebook? [Note the capitalization ;) ]

Yes, eventually. Not at this point. We plan to write all of our narrative docs in notebooks, but simple reference docs still belong in plain sphinx. As time goes on, we expect docs written for sphinx to shrink, and notebook docs to grow. However, part of that is actually sphinx exporters for nbconvert, so that we can write notebooks that actually get rendered along with everything else in the sphinx build.

In fact, is there an easy way of incorporating output of nbconvert into the sphinx workflow?

Not yet, that's one of the things we will be working on. NbConvert has to finish existing first.

[minrk]

s/text cells/rich text/

[dpsanders]

I think you are looking at an older version?

[dpsanders]

NbConvert has to finish existing first.

:-)

[dpsanders]

@jakobgager I have implemented all of your corrections, except the one giving LaTeX installation instructions, and
not including splitting the page into subpages, which is desperately needed as a next step after this PR is merged!

Ready to merge.

[minrk]

Thanks, I'll go ahead and merge and cut the alpha when I get home this afternoon.

[jakobgager]

Great to hear! Looking forward to the new docs!
Really great work @dpsanders 👏