Need a Designers Changelog for nbconvert HTML changes

[brandon-rhodes]

Would the IPython project welcome a pull request that adds a Designers Guide to the IPython Notebook documentation?

With the release of IPython 2.0, nbconvert suddenly starting producing different HTML for exactly the same input notebooks as before. Since people are now publishing IPython notebooks on their own web sites, any change to the output of nbconvert can break a web site’s styling and require their designers to jump in and re-write their CSS.

As one example, Markdown cells used to stand alone. Now, they are accompanied by an empty input <div>:

<div class="prompt input_prompt">
</div>

Another example is that the vbox class suddenly disappeared from normal input cells and was replaced by rendered. From a diff on my own build process:

-<div class="cell border-box-sizing code_cell vbox">
-<div class="input hbox">
...
+<div class="cell border-box-sizing code_cell rendered">
+<div class="input">

This raises two problems.

First, the documentation does not seem to provide designers with any guidance as to which HTML classes to aim their CSS at. If they targeted these cells with vbox rules before, that CSS is now broken until they switch to one of the new classes. There should be, at any point in time, at least a brief guide to the HTML layout suggesting which classes are the “important ones” (or most-likely-to-remain-stable ones?) that designers ought to be targeting.

The second problem is that the project seems to lack a “Designer’s Changelog” showing how the HTML has changed over time — “vbox has gone away” — “there is now a rendered class” — so that the CSS rules they have developed can be updated accordingly.

Would the project welcome a pull request that begins to rough out what such documentation might look like?

[Carreau]

Before forgetting, .vbox is not removed, it is now part of .cell to allow to overwrite with css,
and I am one that pushed to have that.

---

I suppose such a pull request would be accepted, though we probably need someone to update the state of such a document. It is though not a secret that the css and html classes will be cleaned up and refactor, and even if we do our best not to break the css, I do not think we committed to keep backward compatibility.

the rest is my personal opinion and might not reflect the feeling of the all team.

---

In my humble opinion a document describing the change would only be worth it once the css/html structure are stabilized.

Of course people do nice things and prefer to rewrite by hand the css template we provide whereas we do our best to provide a way to recompile our css by just changing already existing variable.

I expressed many times [citation needed] the fact that nbviewer should support theme as part of notebook metadata (I even had a prototype), and that I had concern that changing html could break notebook that inject their own css. But people still prefer the old approach than helping to patch the current codebase to bring new feature.

I also feel that a document describing the changes would be counterproductive conveying the feeling that :

1. We commit not to break user theme.
2. We are confortable enough with css and html theming.
3. It push people away from contributing to core.

I would much rather have a document that state something along :

We do our best to keep theming of the notebook possible, though, because of the lack of manpower we reserve the right to break the html and css structure of the generated notebook at any time. If you are interested in having a more stable structure we welcome contribution on the main IPython repository, once we feel that the structure is stable enough and have people to maintain a feature, we can commit not to break it and provide documented changes.

Such contribution would include but are not be limited to:

• decouple css from js
• get css class name that do not conflict when embedding.
• document how we build our css (yes we have a special css for embedding)
• write how nbconvert works.

eg, I (try to) maintain a build of the js doc, can give access to the app on demand.

Lastly, I believe that such a thing would be nice on IPython wiki were it is editable by everyone.

Hope that make sens and that this message does not feel too angry, it is more supposed to convey a sens of despair.

(also relevant, things like #5556)

[ellisonbg]

• I agree with @brandon-rhodes that we need designer focus documentation for the live notebook and nbconvert.
• I also agree with @Carreau that our current HTML/CSS is completely unstable and until it becomes more stable that the above mentioned documentation would be a waste of time. Much better to spend time focusing on improving the actual code.
• I also agree with @Carreau that we should move towards CSS themes for the notebook, but again, only after the HTML/CSS becomes stable.

@Carreau sorry you feel despair - maybe too much time working on your thesis ;-)

[brandon-rhodes]

Don’t despair, @Carreau! Your response makes a great deal of sense, and I think that I can try writing up a page of documentation that will offer designers the insights that you are sharing, so that they know where the project is at design-wise and how best to be along for the ride with their own IPython Notebook powered efforts. Look for a pull request from me this weekend.