convert to Jupyter-book

.github/workflows/build_book.yml

@@ -0,0 +1,36 @@
+name: deploy-book
+
+# Only run this when the master branch changes
+on:
+  push:
+    branches:
+    - master
+    - main
+
+# This job installs dependencies, build the book, and pushes it to `gh-pages`
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    # Install dependencies
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r ./docs/requirements.txt
+    # Build the book
+    - name: Build the book
+      run: |
+        jupyter-book build docs/
+    # Push the book's HTML to github-pages
+    - name: GitHub Pages action
+      uses: peaceiris/[email protected]
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build/html

.gitignore

@@ -6,6 +6,9 @@ __pycache__/
 # C extensions
 *.so
 
+# exclude _build directory
+_build/
+
 # Distribution / packaging
 .Python
 build/

docs/_config.yml

@@ -0,0 +1,12 @@
+title: "OMERO Tools"
+author: "BiAPoL"
+
+execute:
+  execute_notebooks: off
+
+sphinx:
+  extra_extensions:
+  - 'sphinx.ext.autodoc'
+  - 'sphinx.ext.napoleon'
+  - 'sphinx.ext.viewcode'
+  - 'sphinx.ext.autosummary'

docs/_toc.yml

@@ -0,0 +1,6 @@
+format: jb-book
+root: index
+
+chapters:
+  - file: instructions/transfer_dataset
+  - file: notebooks/synchronize_tags

docs/index.md

@@ -0,0 +1,12 @@
+# Omero-tools
+
+This repository contains a collection of tools for working with OMERO. Such tools can be working with the OMERO command line interface to [transfer datasets between repositories](OMERO.transfer_dataset), etc. If you find anything to be missing, please feel free to contribute to this repository or open an issue.
+
+## Contributions
+
+Contributions are welcome! Please feel free to open an issue or a pull request if you have any suggestions or improvements. To build the jupyter book on your local machine, you can use the following commands:
+
+```bash
+pip install -r jupyter-book
+jupyter-book build docs
+```

root/docs/instructions/Transfer_dataset.md → docs/instructions/transfer_dataset.md

@@ -1,3 +1,4 @@
+(OMERO.transfer_dataset)=
 # How to transfer a dataset between two omero instances
 
 It is a common task to transfer a dataset between two omero instances. This can be done using the OMERO API. The following steps will guide you through the process. Consider the following example: The dataset with id `dataset_id` is to be transferred from the source omero instance to the target omero instance.

root/docs/notebooks/synchronize_tags.ipynb → docs/notebooks/synchronize_tags.ipynb

@@ -1,8 +1,23 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Synchronize tags across groups\n",
+    "\n",
+    "To make sure that there is some standardization across projects with regard to how data is tagged and annotated, we need to synchronize tags across groups. The goal is to make sure that the tags used in the data are consistent across groups. This will make it easier to search for data and to use the data in the future. The defined tags themselves are based off of the [REMBI metadata schema](https://www.nature.com/articles/s41592-021-01166-8). More specifically, we orient ourselves on the tags used in the [provided spreadsheet](https://docs.google.com/spreadsheets/d/1Ck1NeLp-ZN4eMGdNYo2nV6KLEdSfN6oQBKnnWU6Npeo/edit).\n",
+    "\n",
+    "\n",
+    "To install the necessary packages, run the following command:\n",
+    "```bash\n",
+    "mamba install omero-py ezomero -c bioconda\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -15,6 +30,16 @@
     "import yaml"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "# Prerequisites\n",
+    "\n",
+    "We create user that is called `tag-man` and make sure that this user is member of all groups to which we want to synchronize tags. We then add these groups to the groups we want to synchronize."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 6,
@@ -32,6 +57,13 @@
     "TARGET_GROUPS = ['BiAPoL', 'Campas Lab', 'Dye Lab']"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We need some utility functions to read tags from a tagset and to write tags to a tagset. We also need a function to synchronize tags across groups."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 3,
@@ -91,6 +123,13 @@
     "    return tag_names"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Lastly, this function will be called and iterates over every group that is part of the synchronization process (see above) and synchronizes the tags. For this, it checks existing tags and tagsets. If there is a tag that exists in the [local collection of tags](tag_collection.yaml) but doesn't exist in the remote tagset, it will be added. If a tag exists remotely but not locally in the preset collection, nothing happens. This makes sure that users can add their own individual tags to the tagmanager without them being overwritten by the synchronization process."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 4,
@@ -152,6 +191,13 @@
     "                #conn.getUpdateService().saveAndReturnObject(link)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's show all the tagsets and tags in our local collection and then synchronize them across groups."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 7,