Fixes and minor enhancements for documentation

docs/commands.md

@@ -4,9 +4,9 @@ The shapelets library makes use of [entry points](https://packaging.python.org/e
 Entry points are custom command-line arguments to use the shapelets package.
 
 * `shapelets-run /path/to/config`
-    * To run shapelets analysis via configuration files 
-    * Here `/path/to/config` is the relative or absolute filepath to your configuration file - see the [examples](https://uw-comphys.github.io/shapelets/shapelets/docs.html)
+    * Purpose: To run shapelets analysis via configuration files 
+    * Args: `/path/to/config` is the relative or absolute filepath to your configuration file - see the [examples](https://uw-comphys.github.io/shapelets/shapelets/docs.html)
+
 
 * `shapelets-test`
-    * Triggers all shapelets unit tests. 
-    * You should use this command after modifying the source code or to confirm successful installation of the shapelets package
+    * Purpose: Triggers all shapelets unit tests. Use after modifying source code or to check your shapelets installation.

docs/example_1.md

@@ -4,7 +4,7 @@ See [here](https://github.com/uw-comphys/shapelets/tree/main/examples/example_1)
 
 This example demonstrates the response distance method ([R. Suderman (2015)](https://doi.org/10.1103/PhysRevE.91.033307)) implemented in ``shapelets.self_assembly.quant.rdistance`` for a simulated stripe self-assembled nanostructure image ([R. Suderman (2015)](https://doi.org/10.1103/PhysRevE.91.033307)).
 
-![](images/lamSIM1.png)
+![](../examples/example_1/images/lamSIM1.png)
 
 ## Overview
 
@@ -68,8 +68,8 @@ To run the example, execute ``shapelets-run ./analysis/config`` in the command l
 
 The output (shown below) will be available in ``./analysis/output`` containing the response distance scalar field (left) as well as this field superimposed onto the original pattern (right).
 
-![](../images/lamSIM1_response_distance_k20.png)
-![](../images/lamSIM1_response_distance_overlay_k20.png)
+![](../examples/images/lamSIM1_response_distance_k20.png)
+![](../examples/images/lamSIM1_response_distance_overlay_k20.png)
 
 ## Selecting subdomain bounds during runtime
 

docs/example_2.md

@@ -4,7 +4,7 @@ See [here](https://github.com/uw-comphys/shapelets/tree/main/examples/example_2)
 
 This example demonstrates the defect identification method ([M.P. Tino (2024)](http://dx.doi.org/10.1088/1361-6528/ad1df4)) implemented in ``shapelets.self_assembly.quant.defectid`` for the simulated hexagonal self-assembled nanostructure image ([R. Suderman (2015)](https://doi.org/10.1103/PhysRevE.91.033307)) shown below.
 
-![](images/hexSIM1.png)
+![](../examples/example_2/images/hexSIM1.png)
 
 ## Overview
 
@@ -60,11 +60,11 @@ During runtime you will be prompted to manually select the clusters associated w
 
 The output (shown below) will be available in ``./analysis/output`` containing the location of each cluster (top left), radar chart of centroid response vectors (top right), the defect response distance scalar field (bottom left), and this field superimposed onto the original pattern (bottom right). In this example, clusters 2, 5, and 8 were chosen by the user as defect clusters. 
 
-![](../images/hexSIM1_defectid_clustloc_k10.png)
-![](../images/hexSIM1_defectid_rc_k10.png)
+![](../examples/images/hexSIM1_defectid_clustloc_k10.png)
+![](../examples/images/hexSIM1_defectid_rc_k10.png)
 
-![](../images/hexSIM1_defectid_drd_k10.png)
-![](../images/hexSIM1_defectid_drd_overlay_k10.png)
+![](../examples/images/hexSIM1_defectid_drd_k10.png)
+![](../examples/images/hexSIM1_defectid_drd_overlay_k10.png)
 
 ## Additional Notes
 

docs/example_3.md

@@ -4,7 +4,7 @@ See [here](https://github.com/uw-comphys/shapelets/tree/main/examples/example_3)
 
 This example demonstrates the local pattern orientation method ([M.P. Tino (2024)](http://dx.doi.org/10.1088/1361-6528/ad1df4)) implemented in ``shapelets.self_assembly.quant.orientation`` for a square self-assembled nanostructure image ([C. Tang (2008)](https://doi.org/10.1126/science.1162950))
 
-![](images/sqrAFM2.png)
+![](../examples/example_3/images/sqrAFM2.png)
 
 ## Overview
 
@@ -48,11 +48,11 @@ Depending on your computer hardware, the iterative convergence scheme may take a
 
 The output (shown below) will then be available in ``./analysis/output`` containing the mask (top left), dilated feature orientation (top right), smoothed orientation result, and the smoothed orientation result superimposed onto the original pattern (shown below, respectively).
 
-![](../images/sqrAFM2_orientation_maskedresp.png)
-![](../images/sqrAFM2_orientation_dilate.png)
+![](../examples/images/sqrAFM2_orientation_maskedresp.png)
+![](../examples/images/sqrAFM2_orientation_dilate.png)
 
-![](../images/sqrAFM2_orientation_blend.png)
-![](../images/sqrAFM2_orientation_overlay.png)
+![](../examples/images/sqrAFM2_orientation_blend.png)
+![](../examples/images/sqrAFM2_orientation_overlay.png)
 
 ## Additional Notes
 

docs/example_4.md

@@ -5,8 +5,8 @@ See [here](https://github.com/uw-comphys/shapelets/tree/main/examples/example_4)
 This example demonstrates the galaxy decomposition and reconstruction method ([A. Refregier (2003)](https://doi.org/10.1046/j.1365-8711.2003.05901.x)) implemented via multiple functions in the ``shapelets.astronomy`` submodule for a FITS file, which contains a subset of images of galaxies from the Hubble Deep Field North ([A. Refregier (2003)](https://doi.org/10.1046/j.1365-8711.2003.05901.x)). 
 This data is shown below as linear (left) and mean normalized (right) greyscale images. 
 
-![](../images/galaxies_linear.png)
-![](../images/galaxies_std.png)
+![](../examples/images/galaxies_linear.png)
+![](../examples/images/galaxies_std.png)
 
 ## Overview
 
@@ -70,8 +70,8 @@ The second image (right) contains information about the first decomposed galaxy,
 * a reconstruction of the galaxy using the all calculated coefficients and a compressed set coefficients, and
 * the compressed reconstruction's relative error
 
-![](../images/galaxies_map.png)
-![](../images/galaxies_decomposed.png)
+![](../examples/images/galaxies_map.png)
+![](../examples/images/galaxies_decomposed.png)
 
 ## Additional Notes
 

pyproject.toml

@@ -63,7 +63,7 @@ tracker = "https://github.com/uw-comphys/shapelets/issues"
 
 [tool.setuptools.packages.find]
 where = ["."]
-exclude = ["docs"]
+exclude = ["shapelets.docs", "shapelets.docs.*"]
 
 [tool.setuptools.package-data]
 # Using shapelets as the main directory, then list global patterns underneath it

shapelets/docs/__init__.py

@@ -17,7 +17,21 @@
 
 r"""
 
-This submodule contains documentation for several examples of implemented shapelets applications (see below) and other important resources (see options on left-hand side tab).
+## Documentation 
+
+This submodule contains documentation for the shapelets package. You can navigate the documentation on the left-hand side, and below is an overview of each tab. 
+
+### Changelog
+
+The changelog for the shapelets package, providing an overview of changes associated to each version release.
+
+### Commmands
+
+This page describes the custom commands created for the shapelets package to be used from the command-line.
+
+### Examples
+
+We provide a series of examples demonstrating the shapelets applications included with shapelets. 
 
 Examples for the **shapelets.self_assembly** submodule:
 * Example 1 - the response distance method ([R. Suderman (2015)](https://doi.org/10.1103/PhysRevE.91.033307))
@@ -27,6 +41,10 @@
 Examples for the **shapelets.astronomy** submodule:
 * Example 4 - decomposition and reconstruction of images of galaxies ([A. Refregier (2003)](https://doi.org/10.1046/j.1365-8711.2003.05901.x))
 
+### Install
+
+The installation guide for the shapelets package for Windows, macOS, and Linux (Ubuntu). 
+
 """
 
 from .changelog import *