StephenNneji · Sep 30, 2026 · Sep 25, 2026 · Sep 29, 2026 · Sep 30, 2026
diff --git a/doc/source/_static/custom.css b/doc/source/_static/custom.css
@@ -13,6 +13,55 @@ html[data-theme=dark] {
   --pst-color-secondary: var(--pst-color-primary);
 }
 
+/* make sure the article container uses all available space */
+.bd-article-container {
+  max-width: 100% !important;
+}
+
+.center{
+  display:grid;
+  place-items:center;
+}
+
+.button {
+  display: inline-block;
+  padding: 10px 18px;
+  background-color: #0969da;
+  color: #f8f8ff;
+  text-decoration: none;
+  border-radius: 6px;
+  cursor: pointer;
+}
+
+.button:active,
+.button:visited,
+.button:visited:hover,
+.button:visited:hover
+{
+  color: #f8f8ff; !important;
+}
+
+.button:hover
+{
+  background-color: #e34234;
+  color: #f8f8ff; !important;
+}
+
+.hide-header > h1:first-child {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.bd-main .bd-content .bd-article-container{
+  max-width:100%;
+}
+
 .toctree-wrapper li[class^=toctree-l]>a {
   font-size: medium !important;
 }

diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -54,6 +54,11 @@
     ],
 }
 
+html_sidebars = {
+    "index": [],
+    "install": [],
+    "example": [],
+}
 
 rst_epilog = """
 .. |Angstrom| replace:: :math:`\mathring{A}`
@@ -65,4 +70,7 @@
 
 .. |delete| image:: /images/delete.png
              :scale: 10
+
+.. |options| image:: /images/settings.png
+            :scale: 10
 """
diff --git a/doc/source/example.rst b/doc/source/example.rst
@@ -1,2 +1,30 @@
 Examples
 ========
+A few examples are available in RasCAL-2 which demonstrate the supported model and calculation types. These
+example projects are created from the |RAT examples| where more explanations about each example can be found.
+
+To open an example:
+
+.. image:: /images/load_examples.png
+   :scale: 80
+   :alt: Open example project
+   :align: center
+
+1. Click **File > Open Project** in the main menu to open the load project dialog.
+2. In the dialog, click the Examples tab to reveal a list of examples and click on the desired entry in the
+   examples list.
+
+This will copy the selected example project to a temporary directory so the user does not modify the original, then
+open the copied project in RasCAL-2. The following examples are available in the examples list:
+
+1. **DSPC standard layers**: Reflectivity analysis of a floating bilayer of DSPC using standard layer model.
+2. **DSPC custom layers**: Reflectivity analysis of a floating bilayer of DSPC using custom layer model.
+3. **DSPC custom XY**: Reflectivity analysis of a floating bilayer of DSPC using custom XY model.
+4. **domains standard layers**: Incoherent summing ('domains') from standard layer model.
+5. **domains custom layers**: Incoherent summing ('domains') from custom layer model.
+6. **domains custom XY**: Incoherent summing ('domains') from custom XY model.
+7. **absorption**: Shows absorption (imaginary SLD) effect usually seen below the critical edge.
+
+.. |RAT Examples| raw:: html
+
+   <a href="https://rascalsoftware.github.io/RAT-Docs/1.0/python_examples/index.html" target="_blank">RAT API Examples</a>
diff --git a/doc/source/guide.rst b/doc/source/guide.rst
@@ -1,14 +1,56 @@
 User Guide
 ==========
-
+RasCAL-2 is available for windows, linux, and macOS. Follow the instructions on the :doc:`/install` page to install and
+start the software on your system. The following pages describe the user interface and features of RasCAL-2.
 
 .. toctree::
    :titlesonly:
 
-   user/overview
    user/interface
+   user/structure
    user/control
    user/plot
    user/project
    user/terminal
+   user/features
+   user/settings
+
+Check for RasCAL-2 Updates
+--------------------------
+RasCAL-2 automatically checks for updates when the software is opened. You can manually check for update by clicking
+**Help > Check for Update** in the main menu
+
+After an update check, the software will notify the user if a new release is available and provide a hyperlink to
+download the installer for the new version.
+
+.. image:: /images/update_dialog.png
+   :scale: 80
+   :alt: Update Dialog showing Successful Check
+   :align: center
+
+.. note:: You can also stop the automatic update checks by unchecking the **Check for updates on startup** checkbox.
+
+Report Issues
+-------------
+When reporting a bug or crash, it is important to report the version of RasCAL-2 and provide the software logs so it is
+easier to replicate and fix the issue. These information are present in the about dialog which can be opened by clicking
+**Help > About** in the main menu.
+
+.. image:: /images/about_dialog.png
+   :scale: 80
+   :alt: About Dialog
+   :align: center
+
+Exiting RasCAL-2
+----------------
+RasCAL-2 can be closed by clicking the **File > Exit** on the main menu in the software. If the current rasCAL-2 project
+has been modified or has unsaved results, a message will pop up to prompt saving the Project. Press the **Save** button
+to specify saving the project, the **Discard** button to specify not saving the project, or Cancel to abort the
+operation and return to the software.
+
+.. image:: /images/unsaved_changes_dialog.png
+   :scale: 80
+   :alt: Unsaved Changes Dialog
+   :align: center
 
+.. note:: This dialog could look slightly different on linux or macOS.
diff --git a/doc/source/images/about_dialog.png b/doc/source/images/about_dialog.png
diff --git a/doc/source/images/banner.png b/doc/source/images/banner.png
diff --git a/doc/source/images/browse.png b/doc/source/images/browse.png
diff --git a/doc/source/images/confirm_stop_dialog.png b/doc/source/images/confirm_stop_dialog.png
diff --git a/doc/source/images/load_examples.png b/doc/source/images/load_examples.png
diff --git a/doc/source/images/load_existing.png b/doc/source/images/load_existing.png
diff --git a/doc/source/images/load_rascal_1.png b/doc/source/images/load_rascal_1.png
diff --git a/doc/source/images/load_recent.png b/doc/source/images/load_recent.png
diff --git a/doc/source/images/new.png b/doc/source/images/new.png
diff --git a/doc/source/images/new_project.png b/doc/source/images/new_project.png
diff --git a/doc/source/images/redo.png b/doc/source/images/redo.png
diff --git a/doc/source/images/save.png b/doc/source/images/save.png
diff --git a/doc/source/images/settings_general.png b/doc/source/images/settings_general.png
diff --git a/doc/source/images/settings_matlab.png b/doc/source/images/settings_matlab.png
diff --git a/doc/source/images/settings_plot.png b/doc/source/images/settings_plot.png
diff --git a/doc/source/images/startup_screen.png b/doc/source/images/startup_screen.png
diff --git a/doc/source/images/undo.png b/doc/source/images/undo.png
diff --git a/doc/source/images/undo_history.png b/doc/source/images/undo_history.png
diff --git a/doc/source/images/unsaved_changes_dialog.png b/doc/source/images/unsaved_changes_dialog.png
diff --git a/doc/source/images/update_dialog.png b/doc/source/images/update_dialog.png
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -1,8 +1,18 @@
-RasCAL-2
-========
+.. rst-class:: hide-header
 
-RasCAL-2 is a software for the analysis of multi-contrast neutron reflectometry data.
-It is a graphical user interface (GUI) for the `Python RAT API <https://github.com/RascalSoftware/python-RAT>`_.
+Welcome to RasCAL-2
+===================
+
+.. raw:: html
+
+   <h4 class="center">RasCAL-2 is a software for the analysis of multi-contrast neutron reflectometry data.</h4>
+   <div class="center"><p>Successor to RasCAL-1 and the graphical user interface (GUI) for the <a href="https://github.com/RascalSoftware/python-RAT" >Python RAT API</a>.</span></p>
+   <p><a href="install.html" class="button" >Get Started</a> <a href="example.html" class="button">Explore Examples</a></span></p>
+   </div>
+
+.. image:: /images/banner.png
+   :scale: 100
+   :align: center
 
 
 .. toctree::

diff --git a/doc/source/user/features.rst b/doc/source/user/features.rst
@@ -0,0 +1,29 @@
+Other Features
+==============
+This page describes other useful features available in RasCAL-2
+
+Undo and Redo
+-------------
+RasCAL-2 is designed so that changes made to the project, controls and results can be undone. You can undo
+and redo an action by clicking the |undo| or redo |redo| buttons from the toolbar respectively. The history of
+reversible actions can be viewed by clicking **Edit > Undo History**. This will open the undo history dialog which
+shows a list of actions performed and the current action will be highlighted. Clicking on any entry in the list will
+make that entry the current action by undoing or redoing until that action is reached.
+
+.. image:: /images/undo_history.png
+   :scale: 80
+   :alt: Undo History Dialog
+   :align: center
+
+The following operations cannot be undone:
+
+* Visualization actions (e.g. changing the plot zoom, or arrangement of windows),
+* Changes to the settings,
+* Exporting plot, project or fits.
+
+
+.. |undo| image:: /images/undo.png
+            :scale: 10
+
+.. |redo| image:: /images/redo.png
+            :scale: 10
diff --git a/doc/source/user/interface.rst b/doc/source/user/interface.rst
@@ -1,2 +1,77 @@
 User Interface
 ==============
+Starting the RasCAL-2 software would show a splash screen while the software is loading. When loading is complete,
+the startup screen will be shown.
+
+.. image:: /images/startup_screen.png
+   :scale: 80
+   :alt: RasCAL Startup Screen
+   :align: center
+
+At the top of the startup screen is the title bar which will show the name of the software and the project name and
+path if a project is opened. Below the title bar is the menu bar and toolbar, which provides access to a number of
+operations. At the center of the screen are options for creating or loading a RasCAL project.
+
+.. note:: Some operating systems can change the location and look of title and menu bar.
+
+Menus and Toolbar
+-----------------
+RasCAL-2 provides access to some actions in a menu bar under the tile bar. These actions are grouped into 5
+groups explained below. Clicking on a menu item will perform its associated action.
+
+.. note:: On startup, some menu items like the **Windows** menu will be disabled. These menu items will be enabled
+   after a project is created or loaded.
+
+1. **File**
+    * **New Project**: Create a new project.
+    * **Open Project**: Open a existing project or example project
+    * **Open RasCAL-1 Project**: Open a RasCAL-1 project.
+    * **Save**: Save changes to the current project.
+    * **Save To Folder**: Save current project to another folder.
+    * **Export as Script**: Export the project as a python script.
+    * **Export Fits**: Export the results as CSV files.
+    * **Settings**: Open the settings dialog.
+    * **Exit**: Close the RasCAL application.
+2. **Edit**
+    * **Undo**: Undo the last action.
+    * **Redo**: Redo the last undone action.
+    * **Undo History**: View the action history.
+3. **Windows**
+    * **Tile Windows**: Arrange windows in a tile formation.
+    * **Reset to Default**: Reset the windows locations and sizes to the user saved defaults.
+    * **Save Current Window Positions**: Save the current positions and sizes of the windows as the user default.
+4. **Tools**
+    * **Show Sliders/Hide Sliders**: Show or hide slider view in the project window. see :ref:`about_sliders`.
+    * **Clear Terminal**: Clears the text in the terminal window.
+5. **Help**
+    * **Help**: Open the documentation website in the browser.
+    * **Check for Update**: Check online for new RasCAL-2 version.
+    * **About**: Show information about RasCAL-2.
+
+RasCAL-2 also provides access to some actions in a toolbar below the menu bar. The toolbar actions are **New Project**,
+**Open Project**, **Save**, **Undo**, **Redo**, **Settings**, and **Help**. Clicking on the appropriate icon in the
+toolbar will perform its associated action.
+
+Window Management
+-----------------
+After creating or loading a project, the interface will display 4 sub-windows arranged by default in 2x2 irregular
+grid. The sub-windows are
+
+* Plot window (top left)
+* Project window (top right)
+* Terminal window (bottom left)
+* Controls window (bottom right)
+
+These sub-windows can be rearranged by clicking on the title bar of the sub-window and dragging the sub-window. The
+sub-window can also be resized, minimised and maximized similar to the main window. It can be useful to make a
+sub-window bigger or smaller to suit a workflow, after which the arrangement can be saved by clicking
+**Windows > Save Current Window Positions** in the menu, this will make that arrangement the default and RasCAL will
+use that saved arrangement whenever the software is started.
+
+If you move a sub-window and want to revert back to you saved arrangement, click **Windows > Reset to Default** in the
+menu. If you want to revert to the original arrangement, click **Windows > Tile Windows** then click
+**Windows > Save Current Window Positions** in the menu to save the arrangement.
+
+
+.. note:: The sub-windows cannot be dragged outside the boundary of the main software window but only within the
+   centre area of the main window.
diff --git a/doc/source/user/overview.rst b/doc/source/user/overview.rst
diff --git a/doc/source/user/plot.rst b/doc/source/user/plot.rst
@@ -107,9 +107,6 @@ The plot will be saved as png file with a white background by default, the backg
 by changing the **Export Background Colour** option to **none** in Settings dialog
 
 
-.. |options| image:: /images/settings.png
-            :scale: 10
-
 .. |reset| image:: /images/refresh.png
             :scale: 10
 

diff --git a/doc/source/user/project.rst b/doc/source/user/project.rst
@@ -55,6 +55,8 @@ The project tabs help organise the components of a project, the following tabs e
 * :doc:`project/domains`
 * :doc:`project/contrasts`
 
+.. _about_sliders:
+
 Changing Fitted Parameter Values
 --------------------------------
 Fitted parameters defined in the different project tabs can be modified in a single place using the slider view.

diff --git a/doc/source/user/settings.rst b/doc/source/user/settings.rst
@@ -0,0 +1,50 @@
+Settings
+========
+The settings for RasCAL-2 can be configured by clicking |options| in the toolbar or clicking File > Settings in the
+main menu. The settings dialog has 3 tabs:
+
+1. **General**:
+
+   .. image:: /images/settings_general.png
+      :scale: 80
+      :alt: General Settings
+      :align: center
+
+   * **Style**: This sets the active theme of RasCAL-2. The software can use the default **system** theme, a **light**
+     or a **dark** theme.
+   * **Editor Fontsize**: This is the font size of the internal custom file editor.
+   * **Matlab As Default Editor**: This indicates that should if Matlab should be used to open both Python and Matlab
+     custom files.
+   * **Live Recalculate**: This indicates the results should be recalculated and plotted whenever the user changes values
+     outside edit mode. This can be disabled if running the calculation is expensive.
+   * **Show Stop Calculation Warning**: This indicates a warning should be shown to user when stopping a run will lead
+     to result being lost.
+
+     .. image:: /images/confirm_stop_dialog.png
+        :scale: 80
+        :alt: Confirm Calculation Stop Dialog
+        :align: center
+
+2. **Plotting**: Setting related to plots.
+
+   .. image:: /images/settings_plot.png
+      :scale: 80
+      :alt: Plot Settings
+      :align: center
+
+   * **Export Background Colour**: indicates if exported plot background should be white or transparent.
+
+
+3. **Matlab**: Setting related to running Matlab custom files.
+
+   .. image:: /images/settings_matlab.png
+      :scale: 80
+      :alt: Matlab Settings
+      :align: center
+
+   * **Current Matlab Directory**: This tells RasCAL-2 where the Matlab installation for custom files is located. On
+     Windows and Linux, this should be the folder path e.g *C:\\Program Files\\MATLAB\\R2023a* while on MacOS should be
+     the app e.g */Applications/MATLAB_R2023b.app*. The minimum supported MATLAB is 2023b.
+   * **Matlab RAT directory**: This tells RasCAL-2 to use the provided Matlab RAT files when running a Matlab custom
+     file. This could provide improved performance by avoiding switching in and out of Matlab code. Download and use
+     the latest version of RAT, set this to the path of the RAT folder e.g *C:\\RAT*.