jupyter-notebook packaging
--------------------------

The upstream tarball from github is used instead of the pypi tarball, since the
latter does not contain required source (eg, less files) but does contain
bundled JS libraries and minified source which would in any case need removing.

There are two testsuites - one in python testing server responses and one in
javascript using browser emulation to test the web application. The former is
run during build, but the latter requires phantomjs and casperjs (unpackaged)
so is not currently run. (The <nocheck> option is supported, which should
significantly shorten the build-depends).

All javascript except caja (see below) are symlinked from libjs-* packages,
both at build and runtime. In some cases the naming used by jupyter is not a
match to the libjs packages and individual files are symlinked instead of
directories - see d/rules.

caja
----

Jupyter uses the caja HTML and CSS sanitizer to clean potentially hazardous
content from untrusted notebooks. Caja is a large java package with extensive
dependencies (including GWT) which is not packaged for debian.

Jupyter uses caja via a repository [1] apparently set up by the jupyter team
to allow them to install the javascript parts of caja as a bower package, to
fit in with their JS development environment. The "real" upstream is [2]. The
relevant caja source files are included in debian/missing-sources, and
concatenated and minified during build.

Of the files in missing-sources, five are "bona-fide" source files cherry-picked
from upstream (from `src/com/google/caja/plugin` in [2]), but the remaining two
(`html4-defs.js` and `css-defs.js`) are generated by upstream caja. These are
arguably data - they contain lists of HTML and CSS entities along with their
expected properties ultimately extracted from W3C files, but the exact
transformation is performed by java classes from the caja
(`com.google.caja.lang.css.CssPropertyPatterns$Builder` and
`com.google.caja.lang.html.HtmlDefinitions$Builder`). The generated files
are not obfuscated and contain a declaration that they are Apache-licensed.

[1]: https://github.com/minrk/google-caja-bower
[2]: https://github.com/google/caja

dependencies
------------

There is an explicit dependency on python{,3}-terminado which is listed as a
platform-specific requirement in setup.py, which it appears pybuild doesn't
interpret.

Built-Using
-----------

A subset of the libjs-* packages depended upon are combined into a minified
amalgamation at build time (see tools/build-main.js). These are listed in
Built-Using for the relevant binary packages. Note while the javascript is
amalgamated, other resources (eg, CSS) for these packages are still loaded
from separate files.
