Restructure User Documentation Using Diátaxis Framework (#2353)

docs/index.rst

@@ -6,7 +6,7 @@ Mantid Imaging is a graphical toolkit for performing 3D reconstruction of neutro
 .. grid:: 1 1 2 2
     :gutter: 4
 
-    .. grid-item-card:: 🧙‍♂️
+    .. grid-item-card:: 👩‍🔬
         :link: user_guide/index
         :link-type: doc
         :text-align: center

docs/user_guide/gui/image_view.rst → docs/user_guide/explanations/gui/image_view.rst

@@ -5,7 +5,7 @@ Image view
 
 The image view widget is used in many places in Mantid Imaging to display individual images and image stacks. It is based on ImageView from PyQtGraph and allows fast interaction with large datasets.
 
-.. image:: ../../_static/image_view.png
+.. image:: ../../../_static/image_view.png
     :alt: Image view in main window
     :width: 70%
     :align: center
@@ -27,7 +27,7 @@ On some trackpads without a scroll feature it may be helpful to enable "1 button
 Histogram
 ---------
 
-.. image:: ../../_static/image_view_histogram.png
+.. image:: ../../../_static/image_view_histogram.png
     :alt: Controlling the histogram the image view
     :width: 90%
     :align: center
@@ -40,7 +40,7 @@ The control ticks (triangles labelled 'B' above) can be moved around to customis
 
 Alternative colour schemes can be selected by right-clicking on the gradient as shown below. It is also possible to choose if the gradient interpolation between ticks occurs in Red-Green-Blue (RGB) or Hue-Saturation-Value (HSV) colour space.
 
-.. image:: ../../_static/image_view_colour.png
+.. image:: ../../../_static/image_view_colour.png
     :alt: Selecting colours for the image view
     :width: 70%
     :align: center
@@ -58,7 +58,7 @@ This feature can be accessed by right clicking the projection histogram in the i
 Reconstruction window, there is also the option to access the auto colour feature by clicking on the "Auto Change Colour
 Palette" button in the bottom-left corner. This is shown below:
 
-.. image:: ../../_static/access_auto_colour_palette.png
+.. image:: ../../../_static/access_auto_colour_palette.png
     :alt: Accessing the auto colour palette
     :width: 90%
     :align: center
@@ -69,7 +69,7 @@ the results of Otsu/Jenks and choosing colours that emphasise the separateness o
 changing the colour map only provides a cosmetic difference and does not influence the results of the algorithm. Users
 should note that the execution time of the algorithms increases greatly with the number of materials.
 
-.. image:: ../../_static/auto_colour_palette_menu.png
+.. image:: ../../../_static/auto_colour_palette_menu.png
     :alt: The auto colour palette menu
     :width: 50%
     :align: center

docs/user_guide/gui/loading_saving.rst → docs/user_guide/explanations/gui/loading_saving.rst

@@ -15,7 +15,7 @@ Load Dataset
 
 When *Load dataset* is selected, the following dialog will appear:
 
-.. image:: ../../_static/loading_screen.png
+.. image:: ../../../_static/loading_screen.png
     :alt: Initial Load dialog
 
 This allows you to select the data you wish to load; The Sample entry should be used to select the first projection TIFF
@@ -26,7 +26,7 @@ projections and sample logs.
 Once data has been selected, its shape is inspected and the stack index fields
 are populated as shown below:
 
-.. image:: ../../_static/loading_screen_filled.png
+.. image:: ../../../_static/loading_screen_filled.png
     :alt: Load dialog after selecting data
 
 The *Start* and *End* fields control the range of images that are loaded and
@@ -112,7 +112,7 @@ Save as Image Files
 
 When *Save as Image Files* is selected the save images dialog appears:
 
-.. image:: ../../_static/gui_save_dialog.png
+.. image:: ../../../_static/gui_save_dialog.png
     :alt: Save dialog
 
 This prompts you to select the image stack you wish to save, the directory in
@@ -141,7 +141,7 @@ Dataset Tree View
 
 When a dataset has been successfully loaded, it will be possible to see its elements listed in the dataset tree view.
 
-.. image:: ../../_static/dataset_tree_view.png
+.. image:: ../../../_static/dataset_tree_view.png
     :alt: Dataset tree view
 
 Adding / Replacing Data
@@ -150,7 +150,7 @@ Adding / Replacing Data
 The stacks that comprise an existing dataset can be deleted or -- in the case of *strict* datasets only -- replaced.
 This can be done by right clicking an item in the dataset tree view and choosing the Add / Replace Stack option.
 
-.. image:: ../../_static/add_to_dataset_dialog.png
+.. image:: ../../../_static/add_to_dataset_dialog.png
     :alt: Dataset tree view
 
 As in the case of loading images from the main menu, selecting a single file will cause Mantid Imaging to load all like
@@ -169,7 +169,7 @@ Moving Data
 Data can also be moved from one dataset to another, or one stack type to another, by right-clicking the stack you wish
 to move and choosing the Move Stack option.
 
-.. image:: ../../_static/move_stack.png
+.. image:: ../../../_static/move_stack.png
     :alt: Dataset tree view
 
 Deleting Data
@@ -178,5 +178,5 @@ Deleting Data
 Deleting data can also be achieved by right-clicking on the dataset tree view. This can be used to delete individual
 stacks as well as entire datasets.
 
-.. image:: ../../_static/delete_data.png
+.. image:: ../../../_static/delete_data.png
     :alt: Deleting data in the tree view

docs/user_guide/gui/operations_window.rst → docs/user_guide/explanations/gui/operations_window.rst

@@ -10,7 +10,7 @@ Operations may be applied to image stacks of any type (i.e. projection, sinogram
 reconstruction), they are essentially just image filters and do not directly
 care about the type of image.
 
-.. image:: ../../_static/operations_window.png
+.. image:: ../../../_static/operations_window.png
     :alt: Operations dialog
     :width: 90%
 
@@ -60,7 +60,7 @@ For filters that use a region of interest as a parameter (namely Crop
 Coordinates and ROI Normalisation) the ROI is selected using the controls on the
 stack visualiser for the selected image stack (as shown in the screenshot below).
 
-.. image:: ../../_static/gui_filters_dialog_crop_roi.png
+.. image:: ../../../_static/gui_filters_dialog_crop_roi.png
     :alt: Crop coordinates filter with ROI
     :width: 60%
 

docs/user_guide/gui/recon_window.rst → docs/user_guide/explanations/gui/recon_window.rst

@@ -5,7 +5,7 @@ Reconstruction Window
 
 The reconstruction window contains the tools for center of rotation (COR) and tilt alignment, beam hardening correction (BHC) and tomographic reconstruction.
 
-.. image:: ../../_static/recon_window.png
+.. image:: ../../../_static/recon_window.png
     :alt: Operations dialog
     :width: 100%
 

docs/user_guide/gui/spectrum_viewer.rst → docs/user_guide/explanations/gui/spectrum_viewer.rst

@@ -8,7 +8,7 @@ The spectrum viewer can be accessed from the main menu under "Workflow" > "Spect
 
 To try out the spectrum viewer, you can find a basic example workflow to follow within `quick start <https://mantidproject.github.io/mantidimaging/user_guide/quick_start.html>`_
 
-.. image:: ../../_static/spectrum_viewer.png
+.. image:: ../../../_static/spectrum_viewer.png
     :alt: Spectrum Viewer ROI Mode
     :width: 90%
     :align: center
@@ -45,7 +45,7 @@ Image mode, accessible by selecting the "Image" tab, is a mode of the Spectrum V
 In this mode, you can select whether you would like to export your data in single spectrum or binned spectrum format. 
 You can also select the step size and bin size. If the step size is the same as the bin size, a tiled average will be performed. If the step size is less than the bin size, a rolling average will be performed. The unit of measurement is pixels
 
-.. image:: ../../_static/Spectrum_viewer_ImageMode.png
+.. image:: ../../../_static/Spectrum_viewer_ImageMode.png
     :alt: Spectrum Viewer Image Mode
     :width: 90%
     :align: center

docs/user_guide/explanations/index.rst

@@ -0,0 +1,14 @@
+.. _user_explanations:
+
+Explanations
+============
+
+In-depth conceptual explanations about the key components of the software and their underlying principles.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Explanations:
+
+   gui/index
+   operations/index
+   reconstructions/index

docs/user_guide/reconstructions/algorithms.rst → docs/user_guide/explanations/reconstructions/algorithms.rst

@@ -59,7 +59,7 @@ PDHG-TV
 
 Primal Dual Hybrid Gradient optimiser with Total Variation regularisation. This is an advanced iterative optimised reconstruction algorithm, described in the paper below. The user can adjust regularisation parameter alpha, the figure shows a 2 values of alpha for a reconstructed slice.
 
-.. figure:: ../../_static/pdhg_tv_alpha.png
+.. figure:: ../../../_static/pdhg_tv_alpha.png
     :alt: PDHG-TV with alpha=0.1 on the left and alpha=10 on the right
     :width: 90%
     :align: center

docs/user_guide/how-to-guides/index.rst

@@ -0,0 +1,12 @@
+.. _user_how-to-guides:
+
+How-To Guides
+=============
+
+Practical, task-oriented guides for achieving specific goals within the software.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: How-To Guides:
+
+

docs/user_guide/index.rst

@@ -3,18 +3,52 @@
 User Guide
 ==========
 
-Getting started
----------------
+Welcome to the user guide. This guide is organized based on the Diátaxis framework, with sections for tutorials, how-to guides, explanations, and reference documentation to help users navigate and use the application effectively.
 
-See :ref:`installation`
+.. grid:: 1 1 2 2
+    :gutter: 4
 
-New users may want to :ref:`quick-start`
+    .. grid-item-card:: 🚀
+        :link: user_tutorials
+        :link-type: ref
+        :text-align: center
+
+        **Tutorials**
+
+        Step-by-step guides to get started with MantidImaging.
+
+    .. grid-item-card:: 📘
+        :link: user_how-to-guides
+        :link-type: ref
+        :text-align: center
+
+        **How-To Guides**
+
+        Instructions for specific tasks and workflows in MantidImaging.
+
+    .. grid-item-card:: 🧠
+        :link: user_explanations
+        :link-type: ref
+        :text-align: center
+
+        **Explanations**
+
+        In-depth discussions of key concepts and operations.
+
+    .. grid-item-card:: 📚
+        :link: user_reference
+        :link-type: ref
+        :text-align: center
+
+        **Reference**
+
+        Detailed technical documentation and API references.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   gui/index
-   operations/index
-   reconstructions/index
-   quick_start
+   tutorials/index
+   how-to-guides/index
+   explanations/index
+   reference/index

docs/user_guide/reference/index.rst

@@ -0,0 +1,11 @@
+.. _user_reference:
+
+Reference
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   ../../../support
+   ../../../api
+   ../../../release_notes/next

docs/user_guide/tutorials/index.rst

@@ -0,0 +1,15 @@
+.. _user_tutorials:
+
+Tutorials
+=========
+
+Quick Start
+-----------
+
+Follow these step-by-step guides to get started using MantidImaging effectively.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials:
+
+   quick_start

docs/user_guide/quick_start.rst → docs/user_guide/tutorials/quick_start.rst

@@ -14,7 +14,7 @@ Loading Sample Stack
 
 Firstly, let's load our projections. Go to "File" then "Load Dataset" or alternatively use the shortcut "Ctrl"+"o". This brings up the following loading screen:
 
-.. image:: ../_static/loading_screen.png
+.. image:: ../../_static/loading_screen.png
     :alt: Loading screen
     :width: 70%
     :align: center
@@ -40,7 +40,7 @@ Project Window
 ##############
 
 
-.. image:: ../_static/gui_main_window.png
+.. image:: ../../_static/gui_main_window.png
     :alt: View of the application window
     :align: center
 
@@ -53,7 +53,7 @@ Operations
 
 Next let's take the sample we loaded and let's tidy it up with operations. To open the operations go to "Workflow" then "Operations".
 
-.. image:: ../_static/operations_window.png
+.. image:: ../../_static/operations_window.png
     :alt: View of the application window
     :align: center
 
@@ -66,13 +66,13 @@ Next let's take the sample we loaded and let's tidy it up with operations. To op
 3. **Flat Fielding** As we only have one set of flat and dark images we will set the flat fielding method to "Only Before". With safe apply checked running this operation opens the following window:
     - Safe Apply window showing before flat fielding on the left and after flat fielding on the right. Next select "Choose New Data" to apply operation.
 
-.. image:: ../_static/flat_fielding.png
+.. image:: ../../_static/flat_fielding.png
    :alt: Flat fielding with Safe Apply option turned on
    :align: center
 
 4. **Crop Coordinates** Next we will crop the stack to contain the sample only by selecting a ROI as in the following.
 
-.. image:: ../_static/Crop.png
+.. image:: ../../_static/Crop.png
    :alt: ROI that needs to be selected for the crop
    :align: center
    :width: 70%
@@ -95,7 +95,7 @@ For this reconstruction we will be manually finding the COR and tilt values. The
 3. Press the "Refine" button whilst selecting this slice. This brings up the following window:
 
 
-.. image:: ../_static/refine_window.png
+.. image:: ../../_static/refine_window.png
    :alt: Loading screen
    :align: center
 
@@ -127,7 +127,7 @@ you can apply some post-processing operations (such as circular mask), or just s
 Spectrum Viewer
 ###############
 
-.. image:: ../_static/spectrum_viewer.png
+.. image:: ../../_static/spectrum_viewer.png
     :alt: Spectrum Viewer Window
     :align: center