copying the installation guide

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "restructuredtext.confPath": "/Users/dli/eg-docs/docs"
+}

docs/datahub.rst

@@ -1,2 +1,65 @@
 Datahub
-=======
+=======
+
+A datahub is a JSON_ file descibing a set of tracks in the browser. A datahub file is an array of tracks,
+which are also defined in JSON syntax:
+
+.. code-block:: json
+
+    [
+        {
+        "type": "track_type1",
+        "name": "track_name1",
+        "url": "track_url1",
+        "options": {
+            "color": "red",
+            "other option": "other value"
+            }
+        },
+        {
+        "type": "track_type2",
+        "name": "track_name2",
+        "url": "track_url2",
+        "options": {
+            "color": "red",
+            "other option": "other value"
+            }
+        }
+    ]
+
+.. _JSON: http://json.org/
+
+
+Example bigWig track
+--------------------
+
+.. code-block:: json
+
+    {
+        "type": "bigwig",
+        "name": "example bigwig",
+        "url": "https://vizhub.wustl.edu/hubSample/hg19/GSM429321.bigWig",
+        "options": {
+            "color": "blue",
+        }
+    }
+
+Supported options: color_, color2_, yScale_, yMax_, yMin_
+
+options
+-------
+
+color
+~~~~~
+
+color2
+~~~~~~
+
+yScale
+~~~~~~
+
+yMax
+~~~~
+
+yMin
+~~~~

docs/installation.rst

@@ -1,2 +1,162 @@
 Installation
 ============
+
+Server-side
+-----------
+
+Enter the ``backend`` directory.  ``npm install``\ , and then ``npm run setup``.  MongoDB must be running.
+
+Running
+~~~~~~~
+
+#. Make sure MongoDB is running.
+#. Enter the ``backend`` directory.
+#. ``npm start``.
+#. Enter the ``frontend`` directory.
+#. ``npm start``.
+
+Client-side
+-----------
+
+Quick tour
+~~~~~~~~~~
+
+The client code is in the ``frontend`` folder.  Here is a quick tour of ``frontend/src``\ :
+
+
+* ``components``\ : All React components.
+
+  * ``genomeNavigator``\ : the navigation bar at the top that allows users to navigate
+  * ``track``\ : track-related components
+  * ``trackManagers``\ : UI that manages adding tracks
+
+* ``dataSources``\ : API calls, AJAX calls, database connections, etc. that get data to display.
+* ``model``\ : data models.
+* ``stories``\ : stories for Storybook, on which unit tests depend.
+* ``vendor``\ : 3rd-party libraries that are not in NPM.
+
+Suggested order of reading
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you plan to understand the app as a whole, here's a suggested order of code to read:
+
+
+#. ``Feature``\ : a feature or annotation in the genome
+#. ``NavigationContext``\ : a list of ``Feature`` that represents everywhere a user can navigate.  If the ``Feature``\ s are
+   actually entire chromosomes, then the user can effectively navigate the whole genome.
+#. ``DisplayedRegionModel``\ : an interval in a ``NavigationContext``
+#. ``App``\ : the root component of the app
+#. From ``App``\ , descend into interested components.
+
+Making a new track type
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Make a new TrackConfig
+^^^^^^^^^^^^^^^^^^^^^^
+
+Make a new class that extends ``TrackConfig``\ , or one of its subclasses.  This class packages many essential track
+characteristics:
+
+
+* ``getComponent()`` - gets the component that renders the main visualizer and legend of the track.
+* ``getMenuComponents()`` - specifies context menu items in an array of components.  You can choose existing ones
+  in the ``contextMenu`` directory, or make new ones.
+* ``getOptions()`` - the visualizer probably renders with default options, like a color.  This method returns a plain
+  object containing those options.
+
+You do not have to implement these methods immediately, as the base ``TrackConfig`` class provides minimal defaults.
+Just work on making the browser render *some* temporary placeholder at first.
+
+Specify when to use the TrackConfig
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+#. Import your new TrackConfig into ``trackConfig/getTrackConfig.js``.
+#. Add an appropriate entry to ``TYPE_NAME_TO_SUBTYPE``\ , which maps track type name to track renderer.
+
+Write a new track visualizer component (implement ``getComponent()``\ )
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+#. Make a new component expecting to receive a bunch of props from ``TrackContainer``.  ``Track.js`` documents the props
+   to expect.
+#. If you need data, assume it will come through the ``data`` prop.  We will add data fetch in the next step.
+#. Your new component may ``render`` anything, though it is **highly** recommended you render a ``<Track>`` component, if
+   not one of the more specialized components like ``<AnnotationTrack>`` or ``<NumericalTrack>``.  Pass *all* track container
+   props to these sub-components.
+#. In addition to track container props, you need to provide certain props to these sub-components, all of which the
+   respective files document.
+
+   * For example, ``<Track>`` requires a legend and visualizer element.  Use the track container props, which includes
+     view region and width, to render a visualizer and pass it to ``<Track>``.
+
+Add data fetch
+^^^^^^^^^^^^^^
+
+Available data sources are in the ``dataSources`` folder.  If none of them fulfill your needs, write a new class that
+fulfills the interface of ``DataSource.js``.  More can be found in that file.
+
+How do we give your visualizer data?  `Higher-order components <https://reactjs.org/docs/higher-order-components.html>`_\ !
+``track/commonComponents`` contains track-specific HOCs; their names start with ``config-`` or ``with-``.
+
+``configStaticDataSource`` requests a callback that returns a ``DataSource`` and then returns a *function* that wraps React
+components.  After you use this function, a component will automatically receive three props ``data``\ , ``isLoading``\ , and
+``error``.  These update with the browser's current view region.  In particular, the HOC guarantees synchronization of the
+``data`` prop with the current view region if ``isLoading`` is false.
+
+2.  Specify context menu components (implement ``getMenuComponents()``\ )
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Specify context menu items with an array of components.  You can choose existing ones in the ``contextMenu`` directory, or
+make new ones.
+
+
+* Make sure the method returns Component *classes*\ , not component instances.
+
+3.  Specify default options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Default option objects look like the ``options`` prop of ``TrackModel`` objects.  Context menu items will read these options
+if the track model does not specify them.  Make sure these options are consistent with the way you are rendering your
+track component!  The ``configOptionMerging`` HOC should help with that.
+
+Once you have a default options object, call ``setDefaultOptions()`` in the constructor of ``TrackConfig`` to use them.
+
+Performance tips
+~~~~~~~~~~~~~~~~
+
+Querying the width or height of any element, for example through ``clientWidth`` or ``getBoundingClientRect()``\ , is slow.
+Such queries take on the order of 2 to 20 ms.  While it is fine to do it once or twice, avoid doing it in a loop.
+Suppose you aim to plot 500 data points on a SVG, and for each point you query the SVG's width.  That is already a
+second or more of computation -- very noticable to the user!
+
+React (and other) gotchas
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+* On Macs, control + click is the same as a right click, which fires a ``contextmenu`` event.  Note that ``click`` events
+  do not fire on ``contextmenu`` events.  The ``mousedown`` and ``mouseup`` events will still fire, though.
+* When using native DOM events, they take priority over React events.  This is because React waits for events to bubble
+  to the root component before handling them.  This can cause undesirable effects: for example, calling
+  ``stopPropagation()`` on a React event will not actually stop native events.  This StackOverflow post may also help if you
+  have propagation problems: https://stackoverflow.com/questions/24415631/reactjs-syntheticevent-stoppropagation-only-works-with-react-events
+* React *always* unmounts components if their parents change type.  The ``Reparentable`` component works around this by
+  using app-unique IDs, but it can cause side effects with React's native events.  Use with care.
+* Webpack does not support circular dependencies, and while compilation may be successful, an import may resolve as
+  ``undefined`` at runtime.
+
+Lessons trying to refactor into WebWorkers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+#. Data fetch and track display options are intimately related.  For example, what if someone wants HiC data and
+   selects the 5KB resolution option?
+#. Thus, for each track type, we have one object that gets the track component, default rendering options, and data
+   fetch/processing.
+#. Webpack hangs forever if it encounters a cyclic dependency involving a webworker.
+#. The code as in (2) causes a cyclic depdendency.  This cycle is [config object] --> [data source] --> [worker] -->
+   [track config deserializer] --> [config object]
+#. We cannot have our cake and eat it too.
+
+Unfortunately, this means we cannot pipeline all expensive computation in worker context, while also ensuring track
+component and data source live in the same place.

docs/tracks.rst

@@ -1,39 +1,40 @@
-Tracks 
-====== 
+Tracks
+======
 
-This section introduces the track types the browser supports. 
+This following sections introduce the track types the browser supports.
 
-Numerical Tracks 
----------------- 
+Numerical Tracks
+----------------
 
 Currently there are two types of numerical tracks:
 
-* `bigWig`_
-* `bedGraph`_
+* bigWig_
+* bedGraph_
 
 bigWig
 ~~~~~~
 
-``bigWig`` is a popular format to represent numerical values over 
-genomic coordinates.
+``bigWig`` is a popular format to represent numerical values over genomic coordinates.
 Please check `UCSC bigWig`_ page to learn more about this format.
 
 .. _UCSC bigWig: https://genome.ucsc.edu/goldenpath/help/bigWig.html
 
+
 bedGraph
 ~~~~~~~~
-``bedGraph`` format also defines values in diffenent genomic locations. 
+
+``bedGraph`` format also defines values in diffenent genomic locations.
 More about bedGraph please check `UCSC bedGraph`_ page.
+
 Example lines are below::
 
     chr12   6537598 6537599 28.80914
     chr12   6537599 6537600 28.96908
     chr12   6537599 6537612 -2
     chr12   6537600 6537601 29.30229
 
-Every line consists of 4 fields separated by ``Tab`` delimiter, 
-the fields from left to right are
-``chromosome``, ``start position``, ``end position`` (not included), and ``value``.
+Every line consists of 4 fields separated by ``Tab`` delimiter,the fields from
+left to right are ``chromosome``, ``start position``, ``end position`` (not included), and ``value``.
 
 .. note:: You can use nagative values for reverse strand, both positive and negative
           values can exist in same coordinates (they can overlap), in ``bigWig`` format