zakandrewking · zakandrewking · Mar 14, 2019 · Jun 26, 2018 · Jun 26, 2018 · Jun 26, 2018
diff --git a/.gitignore b/.gitignore
@@ -21,7 +21,6 @@ dist/
 js/src/inline.js
 coverage/
 .nyc_output/
-py/escher/package.json
 
 # site files
 1-0-0
@@ -32,3 +31,5 @@ package-lock.json
 node_modules/
 .yarnclean
 .mypy_cache/
+/TODO.txt
+/py/escher/package.json
diff --git a/README.md b/README.md
@@ -5,8 +5,7 @@
 [![Travis](https://img.shields.io/travis/zakandrewking/escher/master.svg)](https://travis-ci.org/zakandrewking/escher)
 [![Coverage Status](https://img.shields.io/coveralls/zakandrewking/escher/master.svg)](https://coveralls.io/github/zakandrewking/escher?branch=master)
 
-Escher
-======
+# Escher
 
 Escher is a web-based tool to build, view, share, and embed metabolic maps. The
 easiest way to use Escher is to browse or build maps on the
@@ -33,7 +32,116 @@ building, sharing, and embedding data-rich visualizations of biological
 pathways*, PLOS Computational Biology 11(8):
 e1004321. doi:[10.1371/journal.pcbi.1004321](http://dx.doi.org/10.1371/journal.pcbi.1004321)
 
-Built at SBRG
-=============
+Escher was developed at [SBRG](http://systemsbiology.ucsd.edu/). Funding was
+provided by [The National Science Foundation Graduate Research Fellowship](https://www.nsfgrfp.org)
+under Grant no. DGE-1144086, The European Commission as part of a Marie Curie
+International Outgoing Fellowship within the EU 7th Framework Program for
+Research and Technological Development ([EU project AMBiCon, 332020](http://ec.europa.eu/research/mariecurieactions/node_en)),
+and [The Novo Nordisk Foundation](http://novonordiskfonden.dk/)
+through [The Center for Biosustainability](https://www.biosustain.dtu.dk/)
+at the Technical University of Denmark (NNF10CC1016517)
 
-[![SBRG](https://raw.githubusercontent.com/zakandrewking/escher/master/py/escher/static/img/sbrg-logo.png)](http://systemsbiology.ucsd.edu/)
+# Building and testing Escher
+
+## JavaScript
+
+First, install dependencies with [npm](https://www.npmjs.com) (or you can use
+[yarn](https://yarnpkg.com)):
+
+```
+npm install
+```
+
+Escher uses webpack to manage the build process. To run typical build steps, just run:
+
+```
+npm run build
+```
+
+You can run a development server with:
+
+```
+npm run start
+# or for live updates when the source code changes:
+npm run watch
+```
+
+To test the JavaScript files, run:
+
+```
+npm run test
+```
+
+## Python
+
+Escher has a Python package for generating Escher visualizations from within a
+Python data anlaysis session. To learn more about using the features of the
+Python package, check out the documentation:
+
+https://escher.readthedocs.io/en/latest/escher-python.html
+
+For development of the Python package, first build the JavaScript package and
+copy it over to the `py` directory with these commands in the Escher root:
+
+```
+npm install
+npm run build
+npm run copy
+```
+
+Then in the `py` directory, install the Python package:
+
+```
+cd py
+pip install -e . # installs escher in develop mode and dependencies
+```
+
+For Python testing, run this in the `py` directory:
+
+```
+cd py
+pytest
+```
+
+## Jupyter extensions
+
+To develop the Jupyter notebook and Jupyter Lab extensions, you will need
+install them with symlinks (the typical installation is describe in the
+[docs](https://escher.readthedocs.io/en/latest/escher-python.html)).
+
+First, install the Python package for development as described above.
+
+For the Jupyter notebooks, run:
+
+```
+cd py
+jupyter nbextension install --py --symlink --sys-prefix escher
+jupyter nbextension enable --py --sys-prefix escher
+```
+
+When you make changes, you will need to `yarn copy` and refresh notebook browser
+tab.
+
+For Jupyter Lab, run (in the root directory):
+
+```
+yarn watch # keep this running as a separate process
+jupyter labextension install @jupyter-widgets/jupyterlab-manager
+jupyter labextension link
+jupyter lab --watch
+```
+
+If you don't see changes when you edit the code, try refreshing or restarting
+`jupyter lab --watch`.
+
+## Docs
+
+Build and run the docs::
+
+```
+cd docs
+make html
+cd _build/html
+python -m SimpleHTTPServer # python 2
+python -m http.server # python 3
+```
diff --git a/docs/contribute_maps.rst b/docs/contribute_maps.rst
@@ -34,28 +34,6 @@ Once you have a COBRA model, you can follow these steps:
 
     iMM904.Amino acid biosynthesis.json
 
-5. (Optional) Once you have a set of subsystem maps, you can set up a local
-   Escher server so that subsystem maps appear in the "quick jump" menu in the
-   bottom right corner of the screen (as seen here_ for iJO1366). To set this
-   up, you will need to start a local server as describe in
-   :ref:`local-server`. Next, find your local cache directory by running this
-   command in a terminal::
-
-    python -c "import escher; print(escher.get_cache_dir(name='maps'))"
-
-   This will print the location of the local maps cache. Add your new subsystem
-   maps to cache folder. Now, when you run the server (described in
-   :ref:`local-server`), you should see that quick jump menu appear.
-
-   NOTE: The cache directory is organized into folders for organisms. You can
-   use these folder for filtering by organism on the local launch page, or you
-   can place the maps in the top directory.
-
-   NOTE 2: A similar approach can be used to access your models from the local
-   launch page. Place maps in the folder indicated by::
-
-    python -c "import escher; print(escher.get_cache_dir(name='models'))"
-
 
 Building from an existing map for a similar organism
 ----------------------------------------------------

diff --git a/docs/development.rst b/docs/development.rst
@@ -1,9 +1,15 @@
 Developing with Escher
 ----------------------
 
-If you are interested in developing Escher or just want to try out the source
-code, this is the place to start.  You might also want to check out the the
-`Gitter chat room`_ and the `Development Roadmap`_.
+If you are interested in developing software using Escher as a dependency, this
+is the place to start. If want contribute to development of Escher, then check
+out the GitHub repository (instruction for building and testing the project are
+in the README):
+
+https://github.com/zakandrewking/escher
+
+You might also want to check out the the `Gitter chat room`_ and the
+`Development Roadmap`_.
 
 Using the static JavaScript and CSS files
 =========================================
@@ -49,41 +55,6 @@ If you are using JavaScript ES6 import syntax, the default export is Builder::
   import * as escher from 'escher'
   console.log(Builder, escher.Builder, escher.libs.preact)
 
-Building and testing Escher
-===========================
-
-First, install dependencies with npm::
-
-  npm install
-
-Escher uses grunt to manage the build process. To run typical build steps, just run::
-
-  npm run compile
-
-To test the JavaScript files, run::
-
-  npm run test
-
-For Python testing, run this in the ``py`` directory::
-
-  python setup.py test
-
-Build the static website::
-
-  python setup.py build_gh
-
-Clear static website files::
-
-  python setup.py clean
-
-Build and run the docs::
-
-  cd docs
-  make html
-  cd _build/html
-  python -m SimpleHTTPServer # python 2
-  python -m http.server # python 3
-
 Generating and reading Escher and COBRA files
 =============================================
 

diff --git a/docs/escher-python.rst b/docs/escher-python.rst
@@ -16,6 +16,15 @@ directly::
 
   python setup.py install
 
+To install the Jupyter notebook extension::
+
+  jupyter nbextension enable --py --sys-prefix escher # can be skipped for notebook 5.3 and above
+
+To install the Jupyter Lab extension::
+
+  jupyter labextension install @jupyter-widgets/jupyterlab-manager
+  jupyter labextension install escher
+
 Dependencies should install automatically, but they are:
 
 - `Jinja2`_
@@ -58,20 +67,6 @@ Here are example notebooks to get started with:
 - `JavaScript development and offline maps`_
 - `Generate JSON models in COBRApy`_
 
-.. _`local-server`:
-
-Running the local server
-========================
-
-You can run your own local server if you want to use Escher offline or explore
-your own maps with the homepage browser. To get started, install the Python
-package and run from any directory by calling::
-
-  python -m escher.server
-
-This starts a server at http://localhost:7778. You can also choose another port::
-
-  python -m escher.server --port=8005
 
 
 .. _`source files`: https://github.com/zakandrewking/escher/releases

diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -7,39 +7,6 @@ Introduction
 **Escher** is here to help you visualize pathway maps. But, if you have never
 heard of a pathway map, you might appreciate a quick introduction.
 
-What are pathway maps?
-^^^^^^^^^^^^^^^^^^^^^^
-
-To understand pathway maps, it is useful to think about the general organization
-of a cell. At the smallest level, molecules in a cell are arranged in
-three-dimensional structures, and these structures determine many of the
-functions that take place in a cell. For example, the 3D structure of an enzyme
-determines the biochemical reactions that it can catalyze. These structures can
-be visualized in 3D using tools like `Jmol`_ (as in this `example structure`_).
-
-The DNA sequence is a second fundamental level of biological organization. DNA
-sequences are the blueprints for all the machinery of the cell, and they can be
-visualized as a one-dimensional series of bases (ATCG) using tools like the
-`UCSC genome browser`_.
-
-To use a football analogy, the 3D molecular structures are akin to the players
-on the field, and the information in the DNA sequence is like the playbook on
-the sidelines. But, football would not be very interesting if the players never
-took to the field and executed those plays. So, we are missing this level of
-detail: *the execution of biological plans by the molecular players*.
-
-What we are missing is the biochemical reaction network. Proteins in the cell
-catalyze the conversion of substrate molecules into product molecules, and these
-*reactions* are responsible for generating energy, constructing cellular machinery
-and structures, detecting molecules in the environment, signaling, and
-more. Biochemical reactions can be grouped into pathways when they work in
-concert to carry out a function. (If a reaction is a football play, then the
-pathway is a `drive`_). And Escher can be used to visualize these reactions and
-pathways. Together, we call these visualizations **pathway maps**.
-
-Escher to the rescue
-^^^^^^^^^^^^^^^^^^^^
-
 Many Escher maps represent *metabolic* pathways, and Escher was developed at the
 `Systems Biology Research Group`_ where we have been building genome-scale
 models of metabolism over the past fifteen years. However, Escher is not limited to

diff --git a/docs/javascript_api.rst b/docs/javascript_api.rst
@@ -42,11 +42,10 @@ JavaScript API
 
        .. js:attribute:: options.use_3d_transform
 
-          (Default: Chooses a good option by testing the browser) If true, then
-          use CSS3 3D transforms to speed up panning and zooming. This feature
-          will only work on browsers that `support the 3D transforms`_. It works
-          best in the latest versions of Chrome, Firefox and Internet
-          Explorer. Safari works better with this turned off.
+          (Default: false) If true, then use CSS3 3D transforms to speed up
+          panning and zooming. This feature will only work on browsers that
+          `support the 3D transforms`_. In general, this is no longer necessary
+          for modern browsers and hardware with small to medium sized maps.
 
        .. js:attribute:: options.enable_editing
 
@@ -292,30 +291,35 @@ JavaScript API
 
        .. js:attribute:: options.tooltip_component
 
-          (Default: ``escher.Tooltip.DefaultTooltip``) A function or `tinier`_
-          component to show when hoving over reactions, metabolites, and
-          genes. If a function is passed, the function will be called with a
-          single object as an argument with two attributes: state - containing
-          the data associated with that reaction, metabolite or gene; and el - a
-          HTML node that you can render content in. If you need to manage state
-          for your tooltip, you can alternatively pass a tinier component.  See
+          (Default: ``escher.Tooltip.DefaultTooltip``) A `Preact`_ Component to
+          show when hoving over reactions, metabolites, and genes. See
           ``escher.Tooltip.DefaultTooltip`` in the source code for an example of
-          a tinier component that defines the default tooltips.
+          a Preact component that defines the default tooltips. And see the
+          :doc:`Tooltip Tutorial <development-tutorial>` for more tips on
+          getting started with custom tooltips.
 
        .. js:attribute:: options.enable_tooltips
 
-          (Default: `[`label`]`) Determines the mouseover or touch event required
-          to show the related tooltip.['label'] will show tooltips upon mouseover
-          or touch of the reaction or metabolite labels whereas ['object'] will
-          show the the tooltips over the reaction line segments and metabolite
-          circles. Can be set as an empty array to disable tooltips or can have
-          both options passed in to enable tooltips over both labels and objects.
+          (Default: ``['label']``) Determines the mouseover or touch
+          event required to show the related tooltip.['label'] will show
+          tooltips upon mouseover or touch of the reaction or metabolite labels
+          whereas ['object'] will show the the tooltips over the reaction line
+          segments and metabolite circles. Can be set as an empty array to
+          disable tooltips or can have both options passed in to enable tooltips
+          over both labels and objects.
+
+       .. js:attribute:: options.enable_keys_with_tooltip
+
+          (Default: ``true``) Set this to ``false`` to disallow non-prefixed
+          (i.e. not starting with ctrl or cmd) keyboard shortcuts when the
+          tooltip is visible. This is useful if your tooltip has text inputs.
 
        **Callbacks**
 
        .. js:attribute:: options.first_load_callback
 
-          A function to run after loading the Builder.
+          A function to run after loading the Builder. The Builder instance is
+          passed as a single argument to the callback.
 
     ..
        **Callbacks**
@@ -397,4 +401,4 @@ JavaScript API
                                               turn of the gene_reaction_rules.
 
 .. _`support the 3D transforms`: http://caniuse.com/#feat=transforms3d
-.. _`tinier`: https://github.com/zakandrewking/tinier
+.. _`Preact`: https://preactjs.com/