diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..79646b8 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,53 @@ +name: Docs + +on: + push: + branches: [main, dev] + workflow_dispatch: + +jobs: + + docs: + runs-on: ubuntu-latest + defaults: + run: + shell: bash -l {0} + + steps: + - name: Checkout zarp repository + uses: actions/checkout@v4 + + - name: Setup miniconda & zarp env + uses: conda-incubator/setup-miniconda@v3 + with: + python-version: "3.10" + mamba-version: "*" + channels: conda-forge + channel-priority: true + auto-update-conda: false + activate-environment: zarp + environment-file: install/environment.yml + auto-activate-base: false + + - name: Update zarp env with root. packages + run: mamba env update -p $CONDA_PREFIX -f install/environment.root.yml + + - name: Update zarp env with dev. packages + run: mamba env update -p $CONDA_PREFIX -f install/environment.dev.yml + + - name: Display all miniconda & env info + run: | + conda info -a + conda list + + - name: Cache build artifacts + uses: actions/cache@v4 + with: + key: ${{ github.ref }} + path: .cache + + - name: Install doc requirements + run: pip install -r docs/requirements.txt + + - name: Publish docs + run: mkdocs gh-deploy --force --clean --verbose diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..248c37d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,71 @@ +
+ ![ZARP logo](./images/zarp_logo.384px.png){ width="384" } +
+ +# ZARP + +**Welcome to the _ZARP_ documentation pages!** + +_ZARP_ is a [Snakemake][snakemake] workflow ... + +**TODO:** Complete intro/summary section + +**NOTES TO SELF:** + +- Include references in `/includes/references.md` +- Include abbreviations in `includes/abbreviations.md` (example: EAWNKWIMPR) +- Include emojis (example: :rocket:) +- Check out the [ZARP-cli docs pages](https://zavolab.github.io/zarp-cli/) +for inspiration. +- Check out [MKDocs](https://www.mkdocs.org/) and [Material for +MkDocs](https://squidfunk.github.io/mkdocs-material/) docs for more info + +## How does it work? + +Briefly, when a _ZARP_ run is triggered, ... + +**TODO:** Complete section + +## How to cite + +If you use _ZARP_ in your work, please kindly cite the following article: + +**ZARP: A user-friendly and versatile RNA-seq analysis workflow** +_Maria Katsantoni, Foivos Gypas, Christina J. Herrmann, Dominik Burri, Maciej +Bak, Paula Iborra, Krish Agarwal, Meric Ataman, Máté Balajti, Noè Pozzan, Niels +Schlusser, Youngbin Moon, Aleksei Mironov, Anastasiya Börsch, Mihaela Zavolan, +Alexander Kanitz_ +F1000Research 2024, 13:533 + + +## Training materials + +Coming soon... + +## Info materials + +Coming soon... + +## Reach out + +There are several ways to get in touch with us: + +- For ZARP usage questions, please use the [_ZARP_ Q&A forum][zarp-qa] (requires + [GitHub registration][github-signup]) +- For feature suggestions and bug reports, please use either the + [ZARP][zarp-issue-tracker] or [ZARP-cli][zarp-cli-issue-tracker] issue + tracker (requires [GitHub registration][github-signup]) +- For any other requests, please reach out to us via [email][contact] + +!!! info "Contributors welcome!" + + Open source contributors are always welcome, for [_ZARP_][zarp], + [_ZARP-cli_][zarp-cli] or any other of the [Zavolab + projects][zavolab-gh]. Simply reach out by [email][contact] to schedule + an onboarding call. + +## Acknowledgements + +[![Zavolab](images/zavolab_logo.200px.png)](https://www.biozentrum.unibas.ch/research/research-groups/research-groups-a-z/overview/unit/research-group-mihaela-zavolan) +[![Biozentrum, University of Basel](images/biozentrum_logo.200px.png)](https://www.biozentrum.unibas.ch/) +[![Swiss Institute of Bioinformatics](images/sib_logo.200px.png)](https://www.sib.swiss/) diff --git a/docs/guides/installation.md b/docs/guides/installation.md new file mode 100644 index 0000000..54526d2 --- /dev/null +++ b/docs/guides/installation.md @@ -0,0 +1,33 @@ +# Installation + +On this page, you will find out how to install _ZARP_ on your system. + +## Requirements + +Installation requires the following: + +- Linux (tested with Ubuntu 20.04; macOS has not been tested yet) +- [Conda][conda] (tested with `conda 22.11.1`) +- [Mamba][mamba] (tested with `mamba 1.3.0`) +- [Singularity][singularity] (tested with `singularity 3.8.6`; not required + if you have root permissions on the machine you would like to install _ZARP_ + on; in that case, see [below](#2-set-up-conda-environment)) + +> Other versions, especially older ones, are not guaranteed to work. + +**TODO:** Add/replace requirements/versions and check that everything is correct + +## Installation steps + +### 1. Clone ZARP + +Clone the [ZARP workflow repository][zarp] with: + +```sh +git clone git@github.com:zavolanlab/zarp +# or: git clone https://github.com/zavolanlab/zarp.git +``` + +### 2. Set up Conda environment + +**TODO:** Add on... diff --git a/docs/images/biozentrum_logo.200px.png b/docs/images/biozentrum_logo.200px.png new file mode 100644 index 0000000..12ad52b Binary files /dev/null and b/docs/images/biozentrum_logo.200px.png differ diff --git a/docs/images/sib_logo.200px.png b/docs/images/sib_logo.200px.png new file mode 100644 index 0000000..34ff2de Binary files /dev/null and b/docs/images/sib_logo.200px.png differ diff --git a/docs/images/zarp_logo.256px.png b/docs/images/zarp_logo.256px.png new file mode 100644 index 0000000..be053fd Binary files /dev/null and b/docs/images/zarp_logo.256px.png differ diff --git a/docs/images/zarp_logo.32px.png b/docs/images/zarp_logo.32px.png new file mode 100644 index 0000000..26f8b83 Binary files /dev/null and b/docs/images/zarp_logo.32px.png differ diff --git a/docs/images/zarp_logo.384px.png b/docs/images/zarp_logo.384px.png new file mode 100644 index 0000000..43ab6c4 Binary files /dev/null and b/docs/images/zarp_logo.384px.png differ diff --git a/docs/images/zavolab_logo.200px.png b/docs/images/zavolab_logo.200px.png new file mode 100644 index 0000000..e38f001 Binary files /dev/null and b/docs/images/zavolab_logo.200px.png differ diff --git a/docs/includes/abbreviations.md b/docs/includes/abbreviations.md new file mode 100644 index 0000000..5785b75 --- /dev/null +++ b/docs/includes/abbreviations.md @@ -0,0 +1 @@ +*[EAWNKWIMPR]: Example Abbreviation Where Nobody Knows What It Means, Please Remove diff --git a/docs/includes/references.md b/docs/includes/references.md new file mode 100644 index 0000000..e76293b --- /dev/null +++ b/docs/includes/references.md @@ -0,0 +1,12 @@ +[conda]: +[contact]: +[github-signup]: +[mamba]: +[singularity]: +[snakemake]: +[zarp]: +[zarp-cli]: +[zarp-cli-issue-tracker]: +[zarp-issue-tracker]: +[zarp-qa]: +[zavolab-gh]: diff --git a/docs/overrides/.icons/email.svg b/docs/overrides/.icons/email.svg new file mode 100644 index 0000000..effd393 --- /dev/null +++ b/docs/overrides/.icons/email.svg @@ -0,0 +1 @@ +email \ No newline at end of file diff --git a/docs/overrides/.icons/forum.svg b/docs/overrides/.icons/forum.svg new file mode 100644 index 0000000..7d74006 --- /dev/null +++ b/docs/overrides/.icons/forum.svg @@ -0,0 +1,53 @@ + +image/svg+xml \ No newline at end of file diff --git a/docs/overrides/.icons/github.svg b/docs/overrides/.icons/github.svg new file mode 100644 index 0000000..ca96837 --- /dev/null +++ b/docs/overrides/.icons/github.svg @@ -0,0 +1,101 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + diff --git a/docs/overrides/.icons/twitter.svg b/docs/overrides/.icons/twitter.svg new file mode 100644 index 0000000..04e0462 --- /dev/null +++ b/docs/overrides/.icons/twitter.svg @@ -0,0 +1,62 @@ + + + + \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..27e446d --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +mkdocs>=1.6.0 +mkdocs-awesome-pages-plugin>=2.9.3 +mkdocs-material>=9.5.32 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..1c550af --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,68 @@ +copyright: '© 2019 Zavolab, University of Basel' + +site_name: ZARP documentation +site_url: https://zavolanlab.github.io/zarp +site_author: Zavolab + +repo_name: zarp +repo_url: https://github.com/zavolanlab/zarp +edit_uri: edit/dev/docs +docs_dir: docs + +theme: + name: material + favicon: images/zarp_logo.32px.png + icon: + repo: fontawesome/brands/github + language: en + logo: images/zarp_logo.256px.png + custom_dir: docs/overrides + features: + - content.code.copy + - navigation.footer + - navigation.instant + - navigation.top + - navigation.tracking + +markdown_extensions: + - abbr + - admonition + - attr_list + - md_in_html + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + options: + custom_icons: + - docs/overrides/.icons + - pymdownx.snippets: + auto_append: + - docs/includes/abbreviations.md + - docs/includes/references.md + - pymdownx.superfences + - toc: + permalink: ¶ + +plugins: + - search + +extra: + generator: false + social: + - icon: github + link: https://github.com/zavolanlab + name: Zavolab GitHub organization + - icon: twitter + link: https://twitter.com/ZavolanLab + name: Zavolab Twitter profile + - icon: forum + link: https://github.com/zavolanlab/zarp/discussions + name: ZARP Q&A forum + - icon: email + link: mailto:zavolab-biozentrum@unibas.ch + +nav: + - Home: README.md + - Installation: guides/installation.md + # ADD ADDITIONAL PAGES HERE