start new documentation format

Author: ErinWeisbart

documentation/.github/workflows/deploy.yml

@@ -0,0 +1,40 @@
+name: deploy-documentation
+
+# Only run this when the master branch changes
+on:
+  push:
+    branches:
+    - master
+    # Only run if edits in DS-documentation or
+    paths:
+    - documentation/CP-plugins-documentation/**
+    - .github/workflows/deploy.yml
+
+# This job installs dependencies, builds the book, and pushes it to `gh-pages`
+jobs:
+  deploy-book:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+
+    # Install dependencies
+    - name: Set up Python 3.8
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.8
+
+    - name: Install dependencies
+      run: |
+        pip install jupyter-book
+
+    # Build the book
+    - name: Build the book
+      run: |
+        jupyter-book build CP-plugins-documentation/
+
+    # Push the book's HTML to github-pages
+    - name: GitHub Pages action
+      uses: peaceiris/actions-gh-pages@v3.6.1
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./CP-plugins-documentation/_build/html

documentation/CP-plugins-documentation/Mac_installation.md

@@ -0,0 +1,343 @@
+# How to install CellProfiler from source with all plugins on Mac OS
+
+1. **Download and install [Java JDK 11](https://adoptium.net/temurin/releases/?version=11)**
+   
+   <img src="https://user-images.githubusercontent.com/28116530/184950214-ca9d8d07-ab66-45f2-9a18-fb220bd0a8ec.png" width=500px/>
+   
+   &nbsp;
+   
+   **NOTE**: For M1/M2 Macs, which use the ARM 64-bit architecture, use [this link](https://www.azul.com/downloads/?version=java-11-lts&os=macos&architecture=arm-64-bit&package=jdk) to get Java 11.
+   
+   <img src = "https://user-images.githubusercontent.com/28116530/184956441-26ded1ac-0f8f-4bc2-93d9-e6c8554a0018.png" width=500px/>
+
+
+   After you download the file, open the installer and proceed through the steps to install Java 11.
+   
+    &nbsp;
+
+
+2. **Download and install or update conda**
+
+   For beginners, we recommend you use Anaconda Navigator since it is more beginner-friendly, but you can also use miniconda. [Download Anaconda](https://www.anaconda.com/products/distribution) from the website and install.
+
+   **NOTE**: if you already have conda, you can get the command to update conda by typing `conda update` on your command line. The command will generally look like:
+
+   `conda update --prefix /Users/USERNAME/opt/anaconda3 anaconda`
+
+   &nbsp;
+   
+3. **Clone the CellProfiler-plugins Repo**
+
+    Download a copy of (aka "clone") the CellProfiler-plugins repo from [here](https://github.com/CellProfiler/CellProfiler-plugins.git). You can download the whole repo by cloning it with git or simply clicking the green **Code** button on [the repo page](https://github.com/CellProfiler/CellProfiler-plugins.git) and selecting **Download ZIP** (see below).
+
+   <img src="images/Install_environment_instructions_windows/2022-06-02T21-39-05.png" width="500"/>
+
+    You can also use git or GitHub Desktop to clone the repo if you prefer.
+    
+   &nbsp;
+
+4. **Create the environment from the .yml file**
+
+   Open Anaconda Navigator and select the **Environments** tab on the left. We recommend you create the environment from the command line. To do this, Select the play button next to your base (root) environment and select **Open Terminal**:
+
+   <img src="images/Install_environment_instructions_windows/2022-06-02T21-11-49.png" width="500"/>
+
+   A black box should pop up with a blinking cursor. This is your terminal. You now need to navigate to where the **cellprofiler_plugins_mac.yml** file is inside of the CellProfiler-plugins folder you downloaded in the last step. This file is in the `Instructions` subfolder. Here is how we recommend you do this:
+    1) In Finder, open the folder you downloaded in the previous step (usually called "CellProfiler-plugins-master") 
+    2) There should be a folder called **Instructions**. Right click or ctrl+click that folder. Then hold down the option key (or Alt) on your keyboard. An option to **Copy "Instructions" as Pathname** should appear. Select this option. (see below)
+
+    <img width="509" alt="image" src="https://user-images.githubusercontent.com/28116530/184949743-901ada5e-dbe5-40d6-99c2-ad0877bddc31.png">
+    
+
+   3) Go back to your terminal and type `cd PATH_TO_FOLDER` where `PATH_TO_FOLDER` is the address you copied in the previous step. Press Enter.
+  
+   &nbsp;
+   
+   Now that you're in the right place, copy and paste this command into the terminal and press Enter.
+   ```
+   conda env create -f CellProfiler_plugins_mac.yml
+   ```
+   &nbsp;
+   
+
+ 5. **Activate your environment**
+
+    In your terminal, enter `conda activate CellProfiler_plugins` to activate your environment
+    
+    &nbsp;
+
+
+ 6. **Verify that cellprofiler is installed correctly by running it from the command line.**
+
+    In your terminal, type in `pythonw -m cellprofiler` and hit Enter. this will open CellProfiler or will give you an error message.
+    
+    &nbsp;
+
+ 7. **Install other packages for other plugins**
+
+    Certain packages cannot easily installed when importing the environment. 
+    
+    For StarDist: In terminal with your environment activated, enter:
+    ```
+    pip install stardist csbdeep --no-deps
+    ```
+    
+    
+    If you would like to use the omnipose models in cellpose, ensure you have cellpose 1.0.2 (you should by default if you've used the CellProfiler_plugins_mac.yml file to generate the environment) and enter on the command line (in your activated environment):
+
+    ```
+    pip install omnipose
+    ```
+    
+    &nbsp;
+
+
+ 8. **Connect CellProfiler and the plugins repo**
+
+    With your environment active, type `pythonw -m cellprofiler` in terminal to open CellProfiler if it is not open already.
+
+     * In CellProfiler, go to **File** then **Preferences...**
+     * Scroll down and look for "CellProfiler Plugins Directory" on the left.
+     * Select the **Browse** button and choose the folder where you extracted the CellProfiler plugins files. It is probably called "CellProfiler-plugins-master" unless you have renamed it.
+     * Select **Save** at the bottom of the Preferences window
+     * Close CellProfiler and reopen it by typing `pythonw -m cellprofiler` on the command line
+
+
+  **NOTE**: You might get a warning like this:
+  ```
+  W tensorflow/stream_executor/platform/default/dso_loader.cc:64] Could not load dynamic library 'cudart64_110.dll'; dlerror: cudart64_110.dll not found
+  2022-05-26 20:24:21.906286: I tensorflow/stream_executor/cuda/cudart_stub.cc:29] Ignore above cudart dlerror if you do not have a GPU set up on your machine.
+  ```
+  If you don't have a GPU, this is not a problem. If you do, your configuration is incorrect and you need to try reinstalling drivers and the correct version of CUDA for your system.
+
+&nbsp;
+
+ 9. **Verify that the installation worked**
+
+    Add a module to your pipeline by hitting the **+** button in the pipeline panel (bottom left)
+
+    In the "Add Modules" window that pops up, type "run" into the search bar. You should be able to see plugins like RunCellpose and RunStarDist if the installation was successful:
+    ![](images/Install_environment_instructions_windows/2022-06-02T21-43-56.png)
+
+   ---
+
+
+## Common errors
+
+1. My wheels are failing to build
+
+- If you get a message like "ERROR: Failed building wheel for pyzmq" this usually means that you do not have pyzmq installed. Try to reinstall pyzmq.
+
+2. Java virtual machine cannot be found
+
+- If you're getting errors about Java, it means that java is not being configured properly on your system.
+- Make sure you have installed The Java Development Kit 11 [here](https://adoptopenjdk.net/). Note that newer versions may not work.
+- Make sure you've added environment variables at the **System** level and not at the **User** level. 
+```
+brew install java
+
+# For the system Java wrappers to find this JDK, symlink it with
+sudo ln -sfn /opt/homebrew/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk
+
+# Set version in zshrc
+echo export JAVA_HOME=$(/usr/libexec/java_home -v 1.8) >> ~/.zshrc
+source ~/.zshrc
+```
+
+3. Installing pyzmq failed
+
+- You might get an error when trying to install pyzmq. Something like
+```
+ERROR: Command errored out with exit status 1:
+```
+And earlier in the traceback:
+```
+Fatal: Cython-generated file 'zmq\backend\cython\_device.c' not found.
+                  Cython >= 0.20 is required to compile pyzmq from a development branch.
+                  Please install Cython or download a release package of pyzmq.
+```
+
+  To fix this, `conda install cython`       
+
+
+## Installation instructions for CellProfiler, CellProfiler plugins and CellPose in a conda environment on Apple silicon (eg M1).
+
+1. **Install brew**
+    ```
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+    ```
+
+2. **Update brew**
+    ```
+    brew update
+    ```
+    
+3. **Install Java**
+    ```
+    brew install java
+    ```
+
+4. **For the system Java wrappers to find this JDK and symlink it**
+    ```
+    sudo ln -sfn /opt/homebrew/opt/openjdk/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk.jdk
+    ```
+
+5. **Set version in .zshrc**
+    ```
+    echo export JAVA_HOME=$(/usr/libexec/java_home -v 1.8) >> ~/.zshrc
+    source ~/.zshrc
+    ```
+
+6. **Brew install package requirements**
+    ```
+    brew install freetype mysql git
+    ```
+
+7. **Direct to brew openssl**
+    ```
+    export LDFLAGS="-L$(brew --prefix)/opt/openssl/lib"
+    ```
+
+8. **Install hdf5**
+    ```
+    brew install hdf5@1.12
+    ```
+
+9. **Make sure to get the version directory correct for the version installed. Find with `ls /opt/homebrew/Cellar/hdf5/`**
+    ```
+    export HDF5_DIR=/opt/homebrew/Cellar/hdf5/1.12.1_1/
+    ```
+10. **Create a folder and download cellprofiler-plugins**
+
+    ```
+    mkdir cp_plugins
+    cd cp_plugins
+    git clone https://github.com/CellProfiler/CellProfiler-plugins
+    ```
+
+11. **Download and install miniconda**
+
+   ```
+    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh -O ~/miniconda.sh
+   ```
+
+
+12. **Create a conda `.yml` file**
+    In a text editor, paste the following test and save it as `cellprofiler_plugins_macM1.yml`:
+    ```
+    name: cpcellpose
+
+    channels:
+    - conda-forge
+    - anaconda
+    - bioconda
+    - defaults
+    - apple
+
+    dependencies:
+    - python=3.8
+    - pip
+    - h5py
+    - mysqlclient
+    - imagecodecs
+    - python.app
+    - pandas
+    - pip:
+        - cellpose
+        - attrdict
+        - sip==5.5.0
+        - boto3>=1.12.28
+        - centrosome==1.2.1
+        - docutils==0.15.2
+        - h5py~=3.6.0
+        - imageio>=2.5
+        - inflect>=2.1
+        - Jinja2>=2.11.2
+        - joblib>=0.13
+        - mahotas>=1.4
+        - matplotlib==3.1.3
+        - mysqlclient==1.4.6
+        - numpy>=1.20.1
+        - Pillow>=7.1.0
+        - prokaryote==2.4.4
+        - python-bioformats==4.0.6
+        - python-javabridge==4.0.3
+        - pyzmq~=22.3
+        - sentry-sdk==0.18.0
+        - requests>=2.22
+        - scikit-image>=0.17.2
+        - scikit-learn>=0.20
+        - scipy>=1.4.1
+        - six
+        - tifffile<2022.4.22
+        - wxPython==4.2.0
+    ```
+
+
+13. **Create a conda environment using the cellprofiler_plugins_macM1.yml file**
+
+    At this stage, your folder/file structure should look like this:
+
+    ```
+    ├── cp_plugins
+        ├── CellProfiler-plugins
+        └── cellprofiler_plugins_macM1.yml
+    ```
+
+    In the terminal, make sure you are in the `cp_plugins` folder mentioned above (run `cd cp_plugins` to get there).
+
+    ```
+    conda env create -n cp_plugins --file cellprofiler_plugins_macM1.yml
+    ```
+
+14. **Activate the conda environment**
+
+    ```
+    conda activate cp_plugins
+    ```
+
+15. **Install CellProfiler and CellProfiler-core**
+    ``` 
+    pip install cellprofiler-core
+
+    # We install CellProfiler with no dependencies here since we installed them with the conda yml file
+    # This allows us to have some dependencies for M1 that are not the default for CellProfiler (eg wxPython)
+    git clone https://github.com/CellProfiler/CellProfiler
+
+    pip install --no-deps cellprofiler
+    ```
+
+16. **Open CellProfiler**
+    ```
+    pythonw -m cellprofiler
+    ```
+
+17. **Connect CellProfiler with the plugins folder**
+
+    1. In CellProfiler, go to `File` then `Preferences...`
+    2. Scroll down and look for `CellProfiler Plugins Directory` on the left.
+    3. Select the Browse button and choose the folder where you extracted the CellProfiler plugins files. It is probably called `CellProfiler-plugins` unless you have renamed it.
+    4. Select Save at the bottom of the Preferences window
+    5. Close CellProfiler and reopen it by typing `pythonw -m cellprofiler` in the command line
+
+
+### Resolving dependencies conflicts
+
+    There can be some strange dependency conflicts that can arise with python-javabridge. In the terminal with your environment activate, enter:
+    ```
+    pip uninstall -y centrosome python-javabridge
+    pip install --no-cache-dir --no-deps --no-build-isolation python-javabridge centrosome
+    pip uninstall matplotlib -y
+    pip install matplotlib==3.2
+    pip uninstall mahotas -y
+    pip install mahotas
+    ```
+
+    The latest version of CellProfiler available on github removes the python-javabridge requirement and instead uses ScyJava.
+
+### Test your installation
+
+Add a module to your pipeline by hitting the **+** button in the pipeline panel (bottom left)
+
+In the "Add Modules" window that pops up, type "run" into the search bar. You should be able to see plugins like RunCellpose and RunStarDist if the installation was successful:
+![](images/Install_environment_instructions_windows/2022-06-02T21-43-56.png)