Merge pull request #276 from imagej/update-docs-layout-and-content

This merge updates the ReadTheDocs table of contents layout, fixes a few documentation errors and updates the ImageJ/Fiji version used in the docs to `2.14.0`.
imagej · Aug 10, 2023 · 4350c89 · 4350c89
2 parents d99fcf0 + c5214a0
commit 4350c89
Show file tree

Hide file tree

Showing 21 changed files with 903 additions and 1,031 deletions.
diff --git a/doc/01-Starting-PyImageJ.ipynb b/doc/01-Starting-PyImageJ.ipynb
@@ -1,13 +1,15 @@
 {
  "cells": [
  {
+ "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
  "This notebook is part of the PyImageJ [Tutorial Series](./notebooks.rst), and assumes familiarity with the ImageJ API. Dedicated tutorials for ImageJ can be found [here](https://imagej.net/tutorials/)."
  ]
  },
  {
+ "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
@@ -27,19 +29,20 @@
  "name": "stdout",
  "output_type": "stream",
  "text": [
- "ImageJ version: 2.5.0/1.53r\n"
+ "ImageJ version: 2.14.0/1.54f\n"
  ]
  }
  ],
  "source": [
  "import imagej\n",
  "\n",
  "# initialize ImageJ\n",
- "ij = imagej.init('sc.fiji:fiji:2.5.0')\n",
+ "ij = imagej.init('sc.fiji:fiji:2.14.0')\n",
  "print(f\"ImageJ version: {ij.getVersion()}\")"
  ]
  },
  {
+ "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
@@ -48,12 +51,12 @@
  "| Requirement | Code<sup>1</sup> | Reproducible?<sup>2</sup> |\n",
  "|:-------------------------------------------------------|:------------------------------------------------------------------|:-------------------------:|\n",
  "| Newest available version of ImageJ2 w/ ImageJ support | `ij = imagej.init()` | NO |\n",
- "| Specific version of ImageJ2 w/ ImageJ support | `ij = imagej.init('2.5.0')` | YES |\n",
+ "| Specific version of ImageJ2 w/ ImageJ support | `ij = imagej.init('2.14.0')` | YES |\n",
  "| Interactive (newest version)* | `ij = imagej.init(mode='interactive')` | NO |\n",
- "| Interactive (specific version)* | `ij = imagej.init('net.imagej:imagej:2.5.0', mode='interactive')` | YES |\n",
+ "| Interactive (specific version)* | `ij = imagej.init('net.imagej:imagej:2.14.0', mode='interactive')` | YES |\n",
  "| Without support for original ImageJ (newest versions) | `ij = imagej.init('net.imagej:imagej', add_legacy=False` | NO |\n",
  "| With Fiji plugins (newest version) | `ij = imagej.init('sc.fiji:fiji')` | NO |\n",
- "| With Fiji plugins (specific version) | `ij = imagej.init('sc.fiji:fiji:2.5.0')` | YES |\n",
+ "| With Fiji plugins (specific version) | `ij = imagej.init('sc.fiji:fiji:2.14.0')` | YES |\n",
  "| From a local installation | `ij = imagej.init('/Applications/Fiji.app')` | DEPENDS |\n",
  "\n",
  "*: _`mode='interactive'` is unavailalbe on macOS. Instead use `mode='gui'`. When set to `gui` mode the Python interpeter is blocked and no longer interactive. Check out the [initialization](Initialization.md) documentation for more information._\n",
@@ -64,6 +67,7 @@
  ]
  },
  {
+ "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
@@ -81,6 +85,13 @@
  "execution_count": 2,
  "metadata": {},
  "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "Operating in headless mode - the original ImageJ will have limited functionality.\n"
+ ]
+ },
  {
  "name": "stdout",
  "output_type": "stream",
@@ -99,6 +110,7 @@
  ]
  },
  {
+ "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
@@ -128,7 +140,7 @@
  {
  "data": {
  "text/plain": [
- "'ImageJ2 2.5.0/1.53r; Java 11.0.15-internal [amd64]; 305MB of 16016MB'"
+ "'ImageJ2 2.14.0/1.54f; Java 11.0.15-internal [amd64]; 35MB of 7952MB'"
  ]
  },
  "execution_count": 3,
@@ -157,7 +169,7 @@
  "name": "python",
  "nbconvert_exporter": "python",
  "pygments_lexer": "ipython3",
- "version": "3.10.6"
+ "version": "3.10.12"
  },
  "toc": {
  "base_numbering": 1,

diff --git a/doc/02-Working-with-Java-classes-and-Python.ipynb b/doc/02-Working-with-Java-classes-and-Python.ipynb
diff --git a/doc/03-Sending-Data-to-Java.ipynb b/doc/03-Sending-Data-to-Java.ipynb
diff --git a/doc/04-Retrieving-Data-from-Java.ipynb b/doc/04-Retrieving-Data-from-Java.ipynb
diff --git a/doc/05-Convenience-methods-of-PyImageJ.ipynb b/doc/05-Convenience-methods-of-PyImageJ.ipynb
@@ -1,13 +1,15 @@
 {
  "cells": [
  {
+ "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
  "This notebook is part of the PyImageJ [Tutorial Series](./notebooks.rst), and assumes familiarity with the ImageJ API. Dedicated tutorials for ImageJ can be found [here](https://imagej.net/tutorials/)."
  ]
  },
  {
+ "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
@@ -17,6 +19,7 @@
  ]
  },
  {
+ "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
@@ -36,13 +39,15 @@
  ]
  },
  {
+ "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
  "There are other convenience methods that are attached to `ij.py`. After initializing ImageJ you can explore `ij.py`'s methods with `dir`."
  ]
  },
  {
+ "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
@@ -67,7 +72,7 @@
  "name": "stdout",
  "output_type": "stream",
  "text": [
- "ImageJ2 version: 2.9.0/1.53t\n",
+ "ImageJ2 version: 2.14.0/1.54f\n",
  "Legacy layer active: True\n"
  ]
  }
@@ -118,6 +123,7 @@
  ]
  },
  {
+ "attachments": {},
  "cell_type": "markdown",
  "metadata": {},
  "source": [
@@ -141,7 +147,7 @@
  "name": "python",
  "nbconvert_exporter": "python",
  "pygments_lexer": "ipython3",
- "version": "3.10.6"
+ "version": "3.10.12"
  },
  "vscode": {
  "interpreter": {

diff --git a/doc/06-Working-with-Images.ipynb b/doc/06-Working-with-Images.ipynb
diff --git a/doc/07-Running-Macros-Scripts-and-Plugins.ipynb b/doc/07-Running-Macros-Scripts-and-Plugins.ipynb
diff --git a/doc/08-Discover-and-run-ImageJ-commands.ipynb b/doc/08-Discover-and-run-ImageJ-commands.ipynb
diff --git a/doc/09-Working-with-Large-Images.ipynb b/doc/09-Working-with-Large-Images.ipynb
diff --git a/doc/10-Using-ImageJ-Ops.ipynb b/doc/10-Using-ImageJ-Ops.ipynb
diff --git a/doc/11-Working-with-the-original-ImageJ.ipynb b/doc/11-Working-with-the-original-ImageJ.ipynb
diff --git a/doc/12-Troubleshooting.ipynb b/doc/12-Troubleshooting.ipynb
diff --git a/doc/Classic-Segmentation.ipynb b/doc/Classic-Segmentation.ipynb
diff --git a/doc/Headless.md b/doc/Headless.md
@@ -112,7 +112,7 @@ The script should print the results pandas dataframe (the data from ImageJ's `Re
 log4j:WARN No appenders could be found for logger (org.bushe.swing.event.EventService).
 log4j:WARN Please initialize the log4j system properly.
 log4j:WARN See http://logging.apache.org/log4j/1.2/faq.html#noconfig for more info.
-ImageJ2 version: 2.5.0/1.53r
+ImageJ2 version: 2.14.0/1.54f
 Output:
  Area Mean Min Max
 0 1.267500 3477.416667 2219.0 5312.0

diff --git a/doc/Initialization.md b/doc/Initialization.md
@@ -54,16 +54,16 @@ include the imagej-legacy endpoint unless the `add_legacy=False` flag is given.
 |:---------------------------------------------------------|:----------------------------------------------------------------------------------:|:-------------:|
 | Newest available version of ImageJ2 | `ij = imagej.init()` | NO |
 | Newest available version of ImageJ2 (no original ImageJ) | `ij = imagej.init(add_legacy=False)` | NO |
-| Specific version of ImageJ2 | `ij = imagej.init('2.5.0')`  | YES |
-| Specific version of ImageJ2 (no original ImageJ) | `ij = imagej.init('2.5.0', add_legacy=False)`  | YES |
+| Specific version of ImageJ2 | `ij = imagej.init('2.14.0')` | YES |
+| Specific version of ImageJ2 (no original ImageJ) | `ij = imagej.init('2.14.0', add_legacy=False)` | YES |
 | With a GUI (newest version, blocking) | `ij = imagej.init(mode='gui')` | NO |
-| With a GUI (specific version, blocking) | `ij = imagej.init('net.imagej:imagej:2.5.0', mode='gui')`  | YES |
+| With a GUI (specific version, blocking) | `ij = imagej.init('net.imagej:imagej:2.14.0', mode='gui')` | YES |
 | With a GUI (newest version, interactive) | `ij = imagej.init(mode='interactive')` | NO |
-| With a GUI (specific version, interactive) | `ij = imagej.init('net.imagej:imagej:2.5.0', mode='interactive')`  | YES |
+| With a GUI (specific version, interactive) | `ij = imagej.init('net.imagej:imagej:2.14.0', mode='interactive')` | YES |
 | With Fiji plugins (newest version) | `ij = imagej.init('sc.fiji:fiji')` | NO |
-| With Fiji plugins (specific version) | `ij = imagej.init('sc.fiji:fiji:2.5.0')`  | YES |
+| With Fiji plugins (specific version) | `ij = imagej.init('sc.fiji:fiji:2.14.0')` | YES |
 | With a specific plugin (newest version) | `ij = imagej.init(['net.imagej:imagej', 'net.preibisch:BigStitcher'])` | NO |
-| With a specific plugin (specific version) | `ij = imagej.init(['net.imagej:imagej:2.5.0', 'net.preibisch:BigStitcher:0.4.1'])` | YES |
+| With a specific plugin (specific version) | `ij = imagej.init(['net.imagej:imagej:2.14.0', 'net.preibisch:BigStitcher:0.4.1'])`| YES |
 | From a local installation | `ij = imagej.init('/Applications/Fiji.app')` | DEPENDS |
 
 ### Newest available version
@@ -84,7 +84,7 @@ You can specify a particular version, to facilitate reproducibility:
 
 ```python
 import imagej
-ij = imagej.init('2.5.0')
+ij = imagej.init('2.14.0')
 ij.getVersion()
 ```
 
@@ -156,7 +156,7 @@ or at a reproducible version:
 
 ```python
 import imagej
-ij = imagej.init('sc.fiji:fiji:2.5.0')
+ij = imagej.init('sc.fiji:fiji:2.14.0')
 ```
 
 ### From a local installation
@@ -202,7 +202,7 @@ This can be done for the latest versions as above, or at fixed versions like:
 
 ```python
 import imagej
-ij =imagej.init(['net.imagej:imagej:2.5.0', 'net.preibisch:BigStitcher:0.4.1'])
+ij =imagej.init(['net.imagej:imagej:2.14.0', 'net.preibisch:BigStitcher:0.4.1'])
 ```
 
 ### Plugins without Maven endpoints

diff --git a/doc/Install.md b/doc/Install.md
@@ -73,9 +73,9 @@ you chose this route over conda/mamba above.
 
 Here's one way to test that it works:
 ```
-python -c 'import imagej; ij = imagej.init("2.5.0"); print(ij.getVersion())'
+python -c 'import imagej; ij = imagej.init("2.14.0"); print(ij.getVersion())'
 ```
-Should print `2.5.0` on the console.
+Should print `2.14.0` on the console.
 
 ## Dynamic installation within Jupyter
 
@@ -106,7 +106,7 @@ Here is an example set of notebook cells to run PyImageJ
 on Google Colab with a wrapped local Fiji installation:
 
 1. Install [condacolab](https://pypi.org/project/condacolab/):
- ```python
+ ```bash
  !pip install -q condacolab
  import condacolab
  condacolab.install()
@@ -119,13 +119,13 @@ on Google Colab with a wrapped local Fiji installation:
  ```
 
 3. Install PyImageJ:
- ```python
+ ```bash
  !mamba install pyimagej openjdk=11
  ```
  You can also install other deps here as well (scikit-image, opencv, etc).
 
 4. Download and install Fiji, and optionally custom plugins as well:
- ```python
+ ```bash
  !wget https://downloads.imagej.net/fiji/latest/fiji-linux64.zip > /dev/null && unzip fiji-linux64.zip > /dev/null
  !rm fiji-linux64.zip
  !wget https://imagej.nih.gov/ij/plugins/download/Filter_Rank.class > /dev/null

diff --git a/doc/Puncta-Segmentation.ipynb b/doc/Puncta-Segmentation.ipynb
diff --git a/doc/Troubleshooting.md b/doc/Troubleshooting.md
@@ -77,7 +77,7 @@ and is therefore not available, due to this OS-specific limitation.
 PyImageJ uses some functions of ImageJ2 and supporting libraries that are not
 available in older versions of ImageJ2. While it may be possible to initialize
 an ImageJ2 gateway with an older version of ImageJ2, certain functionality may
-not behave as intended, so we advise to use version 2.5.0 or later if possible.
+not behave as intended, so we advise to use version 2.11.0 or later if possible.
 
 ### Starting Python from inside ImageJ
 

diff --git a/doc/api.rst b/doc/api.rst
@@ -1,5 +1,5 @@
-API Reference
-=============
+API
+===
 
 PyImageJ provides a set of wrapper functions for integration between
 ImageJ+ImageJ2 and Python. A major advantage of this approach is the ability to

diff --git a/doc/index.rst b/doc/index.rst
@@ -15,15 +15,40 @@ scikit-image, CellProfiler, OpenCV, ITK and many more.
 
 .. toctree::
  :maxdepth: 3
- :caption: Contents:
+ :caption: 🚀 Getting Started
 
  Install
  Initialization
+
+.. toctree::
+ :maxdepth: 3
+ :caption: 🪄 How-to guides
+
  notebooks
- use_cases
  Headless
- Development
  Troubleshooting
+
+.. toctree::
+ :maxdepth: 3
+ :caption: 🔬 Use cases
+
+ Blob detection (interactive) <examples/blob_interactive.rst>
+ Blob detection (headless) <examples/blob_xvfb.rst>
+ CellProfiler <cellprofiler/README>
+ Classic Segmentation <Classic-Segmentation>
+ Puncta Segmentation <Puncta-Segmentation>
+ other_use_cases
+
+.. toctree::
+ :maxdepth: 3
+ :caption: 🛠️ Development
+
+ Development
+
+.. toctree::
+ :maxdepth: 3
+ :caption: 📚 Reference
+
  api
 
 Indices and tables

diff --git a/doc/use_cases.rst → doc/other_use_cases.rst b/doc/use_cases.rst → doc/other_use_cases.rst
@@ -1,21 +1,5 @@
-Use cases
-=========
-
-Below are use cases utitlizing PyImageJ and other packages such as :code:`scikit-image`.
-These examples are available in the `PyImageJ repository`_.
-
-.. toctree::
- :maxdepth: 3
-
- Blob detection (interactive) <examples/blob_interactive.rst>
- Blob detection (headless) <examples/blob_xvfb.rst>
- CellProfiler <cellprofiler/README>
- Classic Segmentation <Classic-Segmentation>
- Puncta Segmentation <Puncta-Segmentation>
-
-------------------------------------------------------------------------
-
-.. rubric:: More use cases
+Other use cases
+===============
 
 Here are additional links to some other examples using PyImageJ
 in other projects.