Merge pull request #272 from scijava/docs/improve-build-instructions

ctrueden · web-flow · commit fe24f23a3034 · 2024-09-06T11:51:44.000-05:00
Improve docs build instructions + sample image download links
diff --git a/docs/README.md b/docs/README.md
@@ -1,16 +1,41 @@
-# Adding a new ReadTheDocs page for a project in this repository
+This directory houses the online docs for core SciJava components. Each subfolder is its own ReadTheDocs site.
+
+## Building the docs
+
+If this is your first time building the docs on this machine, create the needed environment with:
+
+```shell
+mamba env create -f environment.yml
+```
+
+Subsequently, every time you want to build, run the following commands:
+
+```
+mamba activate scijava-docs
+make clean html && python -m http.server
+```
+
+If all goes well, you'll see output ending like:
+```
+The HTML pages are in _build/scijava-ops/html.
+Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
+```
+
+To view the built site, open the HTTP link in your browser of choice, then navigate to the stated subdirectory.
+
+## Adding a new ReadTheDocs page for a project in this repository
 
 We use [`sphinx-multiproject`](https://sphinx-multiproject.readthedocs.io/en/latest/index.html) to build multiple RTD sites from within a single repository. To add a new site within this repository, take the following steps:
 
-## Create a new subfolder for the site's documents
+### Create a new subfolder for the site's documents
 
 See the existing `ops` folder for a template.
 
-## Add relevant sections to this folder's `conf.py`
+### Add relevant sections to this folder's `conf.py`
 
 Specifically, you'll want to add an entry to the `multiproject_projects` dictionary. Again, you can copy and edit the `ops` entry.
 
-## Create a new project on `ReadTheDocs`
+### Create a new project on `ReadTheDocs`
 
 You'll want to take the following steps:
 1. Choose to import a project manually
diff --git a/docs/environment.yml b/docs/environment.yml
@@ -1,4 +1,4 @@
-name: scijava-docs-ops
+name: scijava-docs
 channels:
   - conda-forge
   - defaults
diff --git a/docs/ops/doc/examples/deconvolution.rst b/docs/ops/doc/examples/deconvolution.rst
@@ -8,7 +8,12 @@ The SciJava Ops framework currently supports the standard RL algorithm as well a
 algorithm, which utilizes a regularization factor to limit the noise amplified by the RL algorithm :sup:`1`. Typically,
 the RLTV algorithm returns improved axial and lateral resolution when compared to RL.
 
-You can download the 3D HeLa cell nuclus dataset `here`_.
+You can download the 3D HeLa cell nucleus dataset here:
+
+.. admonition:: Download
+   :class: note
+
+   `hela_nucleus.tif`_
 
 .. figure:: https://media.scijava.org/scijava-ops/1.0.0/rltv_example_1.gif
 
@@ -145,5 +150,5 @@ SciJava Ops via Fiji's scripting engine with `script parameters`_:
 
 .. _`Dey et. al, Micros Res Tech 2006`: https://pubmed.ncbi.nlm.nih.gov/16586486/
 .. _`Gibson & Lanni, JOSA 1992`: https://pubmed.ncbi.nlm.nih.gov/1738047/
-.. _`here`: https://media.scijava.org/scijava-ops/1.0.0/hela_nucleus.tif
+.. _`hela_nucleus.tif`: https://media.scijava.org/scijava-ops/1.0.0/hela_nucleus.tif
 .. _`script parameters`: https://imagej.net/scripting/parameters
diff --git a/docs/ops/doc/examples/flim_analysis.rst b/docs/ops/doc/examples/flim_analysis.rst
@@ -13,7 +13,12 @@ We use a sample of `FluoCells™ Prepared Slide #1`_, imaged by `Jenu Chacko`_ u
 
   FluoCells™ Prepared Slide #1 contains bovine pulmonary artery endothelial cells (BPAEC). MitoTracker™ Red CMXRos was used to stain the mitochondria in the live cells, with accumulation dependent upon membrane potential. Following fixation and permeabilization, F-actin was stained with Alexa Fluor™ 488 phalloidin, and the nuclei were counterstained with the blue-fluorescent DNA stain DAPI.
 
-The sample data can be downloaded `here <https://media.scijava.org/scijava-ops/1.0.0/flim_example_data.sdt>`_ and can be loaded into Fiji with `SCIFIO`_ using ``File → Open...`` or ``File → Import → Image...``. The data may take a minute to load.
+The sample data can be downloaded here and can be loaded into Fiji with `SCIFIO`_ using ``File → Open...`` or ``File → Import → Image...``. The data may take a minute to load.
+
+.. admonition:: Download
+   :class: note
+
+   `flim_example_data.sdt`_
 
 Within the script, the `Levenberg-Marquardt algorithm`_ fitting Op of SciJava Ops FLIM is used to fit the data.
 
@@ -222,6 +227,7 @@ In the panels below, we show the results of executing both scripts with computat
     :width: 49%
 
 
+.. _`flim_example_data.sdt`: https://media.scijava.org/scijava-ops/1.0.0/flim_example_data.sdt
 .. _`SCIFIO` : https://scif.io
 .. _`FLIM` : https://en.wikipedia.org/wiki/Fluorescence-lifetime_imaging_microscopy
 .. _`FluoCells™ Prepared Slide #1` : https://www.thermofisher.com/order/catalog/product/F36924
diff --git a/docs/ops/doc/examples/mesh_viz.rst b/docs/ops/doc/examples/mesh_viz.rst
@@ -2,7 +2,12 @@
 3D Analysis and Visualization
 =============================
 
-In this example, we will use SciJava Ops to construct a 3D mesh from a binary dataset, passing the result into `3D Viewer`_ for visualization. We use the `bat cochlea volume`_ dataset (more information `here <https://imagej.net/images/bat-cochlea-volume.txt>`_) from the ImageJ sample images, which users can either download using the link or open from the ``File → Open Samples → Bat Cochlea Volume`` menu selection within Fiji.
+In this example, we will use SciJava Ops to construct a 3D mesh from a binary dataset, passing the result into `3D Viewer`_ for visualization. We use the bat cochlea volume dataset (more information `here <https://imagej.net/images/bat-cochlea-volume.txt>`_) from the ImageJ sample images. The dataset can either be downloaded here, or opened directly in Fiji via ``File → Open Samples → Bat Cochlea Volume``
+
+.. admonition:: Download
+   :class: note
+
+   `bat-cochlea-volume.zip`_
 
 .. figure:: https://media.scijava.org/scijava-ops/1.1.0/mesh-visualization.png
 
@@ -109,6 +114,6 @@ The following script accepts the binary dataset as its sole input, and creates t
         toggleFrame.setVisible(true)
 
 .. _3D Viewer: https://imagej.net/plugins/3d-viewer/
-.. _bat cochlea volume: https://imagej.net/images/bat-cochlea-volume.zip
+.. _`bat-cochlea-volume.zip`: https://imagej.net/images/bat-cochlea-volume.zip
 .. _bat cochlea info: https://imagej.net/images/bat-cochlea-volume.txt
 .. _marching cubes: https://en.wikipedia.org/wiki/Marching_cubes
diff --git a/docs/ops/doc/examples/opencv_denoise.rst b/docs/ops/doc/examples/opencv_denoise.rst
@@ -9,7 +9,12 @@ a pixel of interest (*e.g.* a 5x5 patch) with patches from other pixels from the
 patches are then averaged to eliminate gaussian noise, without the requirement of additional
 images for comparison.
 
-The sample data for this example can be downloaded `here`_.
+The sample data for this example can be downloaded here:
+
+.. admonition:: Download
+   :class: note
+
+   `opencv_denoise_16bit.tif`_
 
 .. figure:: https://media.scijava.org/scijava-ops/1.0.0/opencv_denoise_example_1.png
 
@@ -121,4 +126,4 @@ SciJava Ops via Fiji's scripting engine with `script parameters`_:
 
 .. _`script parameters`: https://imagej.net/scripting/parameters
 .. _`OpenCV library`: https://docs.opencv.org/4.x/d5/d69/tutorial_py_non_local_means.html
-.. _`here`: https://media.scijava.org/scijava-ops/1.0.0/opencv_denoise_16bit.tif
+.. _`opencv_denoise_16bit.tif`: https://media.scijava.org/scijava-ops/1.0.0/opencv_denoise_16bit.tif
diff --git a/docs/ops/doc/examples/saca.rst b/docs/ops/doc/examples/saca.rst
@@ -17,7 +17,12 @@ can be computed easily by using the *Z*-score heatmap with the ``stats.pnorm`` O
 significantly colocalized. This example script takes advantage of this feature of the SACA framework and utilizes the significant pixel
 mask as a region of interest to compute Pearson's :sup:`4` and Li's :sup:`5` colocalization coefficients.
 
-You can download the colocalization dataset `here`_.
+You can download the colocalization dataset here:
+
+.. admonition:: Download
+   :class: note
+
+   `hela_hiv_gag_ms2_mcherry.tif`_
 
 .. figure:: https://media.scijava.org/scijava-ops/1.0.0/saca_input.png
 
@@ -169,5 +174,5 @@ To apply the ``phase`` LUT and a colorbar use the following script and select th
 .. _`Becker and Sherer, JVI 2017`: https://pubmed.ncbi.nlm.nih.gov/28053097/
 .. _`Wang et. al, IEEE 2019`: https://ieeexplore.ieee.org/abstract/document/8681436
 .. _`Stockley et. al, Bacteriophage 2016`: https://pubmed.ncbi.nlm.nih.gov/27144089/
-.. _`here`: https://media.scijava.org/scijava-ops/1.0.0/hela_hiv_gag_ms2_mcherry.tif
+.. _`hela_hiv_gag_ms2_mcherry.tif`: https://media.scijava.org/scijava-ops/1.0.0/hela_hiv_gag_ms2_mcherry.tif
 .. _`script parameters`: https://imagej.net/scripting/parameters
diff --git a/docs/ops/doc/examples/scyjava.rst b/docs/ops/doc/examples/scyjava.rst
@@ -3,11 +3,18 @@ SciJava Ops from Python
 =======================
 
 This example demonstrates how to use SciJava Ops with Python. Using SciJava Ops framework with Python depends on ``scyjava`` to provide robust
-Java code access and ``imglyb`` to bridge the ImgLib2 and NumPy data structures. The Python script in this example downloads a `3D 3T3 cell`_
-nucleus dataset (with shape: ``37, 300, 300``), performes image processing with to improve the nucleus signal, segments the nucleus and measures
+Java code access and ``imglyb`` to bridge the ImgLib2 and NumPy data structures. The Python script in this example downloads a 3T3
+nucleus dataset (with shape: ``37, 300, 300``), performs image processing with to improve the nucleus signal, segments the nucleus and measures
 the 3D volume of the nucleus by creating a mesh. Finally the input image, processed image and the segmented label images are displayed in
 ``matplotlib``, and the volume (μm\ :sup:`3`) is printed to the console.
 
+You can download the 3D 3T3 cell dataset here:
+
+.. admonition:: Download
+   :class: note
+
+   `3t3_nucleus.tif`_
+
 .. figure:: https://media.scijava.org/scijava-ops/1.0.0/scyjava_example_1.png
 
 .. code-block:: bash
@@ -167,4 +174,4 @@ Activate the ``scijava-ops`` conda/mamba environment and run the following Pytho
     plt.tight_layout()
     plt.show()
 
-.. _`3D 3T3 cell`: https://media.scijava.org/scijava-ops/1.0.0/3t3_nucleus.tif
+.. _`3t3_nucleus.tif`: https://media.scijava.org/scijava-ops/1.0.0/3t3_nucleus.tif
diff --git a/docs/ops/doc/examples/volume_labeling.rst b/docs/ops/doc/examples/volume_labeling.rst
@@ -21,7 +21,14 @@ to accomplish this analysis goal the script utilizes SciJava Ops to:
 5. Measure the 3D geometry of the puncta and nuclear regions.
 6. Display results in two tables (puncta and nuclear).
 
-To use the script in the example first download the sample dataset `here`_. Next, open Fiji, the sample image and this scipt. Click **Run** to create the script parameter GUI,
+To use the script in the example, first download the sample dataset:
+
+.. admonition:: Download
+   :class: note
+
+   `hela_hiv_vif.tif`_
+
+Next, open Fiji, the sample image and this script. Click **Run** to create the script parameter GUI,
 where you can customize some values to your own data, such as the channel names, channel position and image calibration values.
 
 .. figure:: https://media.scijava.org/scijava-ops/1.1.0/labeling_mesh_example_dialog.png
@@ -295,4 +302,4 @@ In addition to the result tables, the label imdage (also known as an *index imag
         ui.show("{} results table".format(ch_a_name), ab_table)
         ui.show("{} results table".format(ch_b_name), b_table)
 
-.. _`here`: https://media.scijava.org/scijava-ops/1.0.0/hela_hiv_vif.tif
+.. _`hela_hiv_vif.tif`: https://media.scijava.org/scijava-ops/1.0.0/hela_hiv_vif.tif

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-name: scijava-docs-ops`
	`1`	`+name: scijava-docs`
`2`	`2`	`channels:`
`3`	`3`	`- conda-forge`
`4`	`4`	`- defaults`