From 87b3e6cec62530e964d467471a3c84714952312a Mon Sep 17 00:00:00 2001 From: carrascomj Date: Tue, 31 Jan 2023 16:10:12 +0100 Subject: [PATCH] docs: write down dev documentation --- README.md | 2 + docs/source/developers.rst | 163 +++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 6 +- 3 files changed, 169 insertions(+), 2 deletions(-) create mode 100644 docs/source/developers.rst diff --git a/README.md b/README.md index 3971ac9..e8b1d80 100644 --- a/README.md +++ b/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. diff --git a/docs/source/developers.rst b/docs/source/developers.rst new file mode 100644 index 0000000..0da1c93 --- /dev/null +++ b/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 `__ 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 git@github.com:biosustain/shu.git + # add a remote with to your fork + git remote add downstream git@github.com: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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 4ffb2d7..fd6865d 100644 --- a/docs/source/index.rst +++ b/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