docs: write down dev documentation

README.md

@@ -4,6 +4,8 @@
 
 ## What?
 
+Documentation: https://biosustain.github.io/shu/docs/
+
 App to plot multidimensional data to a metabolic map. Metabolic maps are graphs with metabolites
 as nodes and reactions as edges.
 

docs/source/developers.rst

@@ -0,0 +1,163 @@
+For developers
+==============
+
+The following instructions are for developers who want to contribute to **shu** or deploy it.
+
+Build instructions from source
+------------------------------
+
+To build **shu** from source, you need to have Rust and `cargo` installed.
+**Shu** uses the nightly toolchain: 
+
+.. code:: bash
+
+  rustup toolchain install nightly
+
+and `ldd` to speed up linking times. See the `bevy setup documentation`_ to
+install it or simply remove the `.cargo` directory if that is not desired.
+
+Then, clone the repository and build the project:
+
+.. code:: bash
+
+  git clone https://github.com/biosustain/shu.git
+  cd shu
+  cargo build
+
+Architecture
+------------
+
+The API documentation can be found at https://docs.rs/shu.
+
+Shu follows a Grammar of Graphics design like ggplot_  or plotnine_. See the
+`plotting chapter <plotting.html>`__ for the full analogy. The
+particular implementation is an Entity Component System in bevy_:
+
+* Each aesthetic is a *component* (`Gsize`, `Gcolor`, etc.) containing its data (see `aesthetics.rs`_). Identifiers are stored in the `Aesthetic` *component*.
+* *Entities* with `Aesthetic`, other aes components and Geom component (`GeomArrow`, `GeomMetabolite`, etc. in `geom.rs`_) are processed and plotted by a *system* (in `aesthetics.rs`_).
+* The accepted aesthetics for a given geom are made explicit in the *queries* of the *systems*.
+
+Data handling lives in `data.rs`_ and `escher.rs`_.
+
+About the GUI, there are three separate pieces: the Settings window, the
+histogram interactions and legend. The settings window is handled by bevy_egui_
+(`gui.rs`_). The histogram interactions are non-UI components spawned in
+`aesthetics.rs`_ and handled mostly in `gui.rs`_. Finally, the legend is in its
+own separate `legend module`_ and consists on UI components in a flexbox in a
+way that it is by default collapse and only the relevant legend appears once
+its corresponding data is added to the map.
+
+Deployment
+----------
+
+Binaries for Linux, Mac, Windows and WASM are generated once release tags are pushed to the repository. For instance, a tag for version 26.2.0 would be pushed in the following way:
+
+.. code:: bash
+
+  git tag 26.2.0
+  git push origin 26.2.0
+
+A github action will build and create the binaries.
+
+Native deployment
+~~~~~~~~~~~~~~~~~
+
+To generate binaries locally:
+
+.. code:: bash
+
+  git clone https://github.com/biosustain/shu.git
+  cd shu
+  cargo build --release
+
+A binary has been generated at `target/release/shu`. You can copy it to your path or run it directly from there. Alternatively, simply run
+
+.. code:: bash
+
+   cargo install --path .
+
+And `cargo`_ will handle the rest.
+
+WASM deployment
+~~~~~~~~~~~~~~~
+
+If you want to deploy the WASM version locally or for internal use, you can build it yourself using `wasm-bindgen`_:
+
+.. code:: bash
+
+  # clone the repository if you haven't already
+  git clone https://github.com/biosustain/shu.git
+  cd shu
+  # build the wasm version
+  cargo build --profile wasm-release --target wasm32-unknown-unknown
+  # bundle it into the pkg directory
+  wasm-bindgen --out-dir pkg --target web ./target/wasm32-unknown-unknown/wasm-release/shu.wasm
+
+Afterwards, an `index.html` file can be created in the root directory that
+contains `pkg`. See the `gh-pages branch`_ for an example of that. A directory
+containing the `inde.html`, `assets` and `pkg` directories can be deployed to a
+static page like `Github pages`_ or `Gitlab pages`_.
+
+Contributing
+------------
+
+Contributions are welcome!
+
+1. Look up similar issues_.
+2. `Write an issue`_.
+3. Fork_ the repository.
+
+.. code:: bash
+
+  # https
+  git clone https://github.com/biosustain/shu.git
+  # or ssh
+  git clone [email protected]:biosustain/shu.git
+  # add a remote with to your fork
+  git remote add downstream [email protected]:username/shu.git
+
+4. Branch from trunk.
+
+.. code:: bash
+
+  git checkout -b 'feat-incrediblefeature'
+
+5. Write your code and push the commits to you repository (we use `semantic commits`_).
+
+.. code:: bash
+
+  git commit -m 'feat: add incredible feature'
+  git push -u downstream feat-incrediblefeature
+
+6. Submit a `Pull Request`_ with your feature/bug fix.
+7. Get the Pull Request approved (CI must pass).  
+
+For the CI to pass, you need to run and pass `cargo fmt` and `cargo test`
+before comitting. `cargo clippy` is not enforced but desirable.
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall
+be dual licensed as Apache2.0/MIT, without any additional terms or conditions.
+
+.. _cargo: https://doc.rust-lang.org/cargo/getting-started/installation.html
+.. _ggplot: https://ggplot2.tidyverse.org/
+.. _plotnine: https://plotnine.readthedocs.io/en/stable/index.html
+.. _python API: https://vita.had.co.nz/papers/tidy-data.html 
+.. _bevy: https://bevyengine.org/
+.. _bevy setup documentation: https://bevyengine.org/learn/book/getting-started/setup/#enable-fast-compiles-optional
+.. _bevy_egui: https://github.com/mvlabat/bevy_egui
+.. _aesthetics.rs: https://github.com/biosustain/shu/tree/master/src/aesthetics.rs
+.. _geom.rs: https://github.com/biosustain/shu/tree/master/src/geom.rs
+.. _data.rs: https://github.com/biosustain/shu/tree/master/src/data.rs
+.. _escher.rs: https://github.com/biosustain/shu/tree/master/src/escher.rs
+.. _gui.rs: https://github.com/biosustain/shu/tree/master/src/gui.rs
+.. _legend module: https://github.com/biosustain/shu/tree/master/src/legend
+.. _wasm-bindgen: https://rustwasm.github.io/wasm-bindgen/reference/cli.html
+.. _gh-pages branch: https://github.com/biostain/shu/tree/gh-pages
+.. _Github pages: https://pages.github.com/
+.. _Gitlab pages: https://docs.gitlab.com/ee/user/project/pages/
+.. _issues: https://github.com/biosustain/shu/issues
+.. _Write an issue: https://github.com/biosustain/shu/issues/new
+.. _Fork: https://docs.github.com/en/enterprise/2.13/user/articles/fork-a-repo
+.. _semantic commits: https://seesparkbox.com/foundry/semantic_commit_messages 
+.. _Pull request: https://github.com/biosustain/shu/pulls

docs/source/index.rst

@@ -16,10 +16,11 @@ Controls
 
 * **Left click** and drag to move around the map.
 * **Scroll whell** to zoom in and out.
-* **Right click** on a histogram (on its center) and drag the mouse while holding
+* **Right click** on a histogram or the legend (on its center) and drag the mouse while holding
   the button to zoom in/out to rotate it.
-* **Middle click** on a histogram (on its center) and drag the mouse while holding
+* **Middle click** on a histogram or the legend (on its center) and drag the mouse while holding
   the button to move it.
+* **+** and **-** keys to scale up and down the legend.
 
 Contents
 --------
@@ -28,6 +29,7 @@ Contents
 
    plotting
    map
+   developers
 
 .. _releases: https://github.com/biosustain/shu/releases/latest
 .. _escher: https://github.com/zakandrewking/escher