add grid and launch stage documentations

docs/basics.rst

@@ -43,3 +43,12 @@ visualCaseGen assists users through the custom configuration process to maximize
 but custom setups may require additional troubleshooting. For any issues with custom configurations,
 please refer to the Troubleshooting section of this guide.
 
+
+Resolution vs Grid vs Model Grid
+--------------------------------
+
+In CESM terminology, *resolution* and *grid* are often used interchangeably,
+both referring to the combination of model grids used in a CESM simulation. Unless 
+specifically noted as a *model grid* (i.e., a grid unique to a particular component,
+such as the ocean grid), the term *grid* in the context of visualCaseGen should be understood as
+*resolution*, meaning the full collection of *model grids* used in a particular CESM case.

docs/compset.rst

@@ -116,6 +116,6 @@ modifier combinations.
    .. image:: assets/stage1_10.png
 
 Once you've completed the selection of models, physics, and optional modifiers,
-visualCaseGen will automatically advance to the next primary stage, `Grid`, where
+visualCaseGen will automatically advance to the next main stage, `Grid`, where
 you'll select a model resolution compatible with your chosen compset.
 

docs/grid.rst

@@ -1,15 +1,95 @@
 Stage 2/3: Grid
 ===============
 
-In this stage, ...
+The second major step in configuring your CESM case is choosing a resolution, which
+is a specific set of grids for each active and data model in the compset. You may 
+select either a standard, out-of-the-box resolution or create a custom one by combining
+existing model grids. In `Custom` mode, you can also generate custom model grids for CLM and/or MOM6
+using auxiliary tools included in visualCaseGen. Begin by selecting between `Standard`
+and `Custom` grid modes.
+
+.. image:: assets/stage2_1.png
+
+.. note:: In CESM terminology, *resolution* and *grid* are often used interchangeably,
+   both referring to the combination of model grids used in a CESM simulation. Unless 
+   specifically noted as a *model grid* (i.e., a grid unique to a particular component,
+   such as the ocean grid), the term *grid* in this context should be understood as
+   *resolution*, meaning the full collection of *model grids* used in a particular CESM case.
 
 Standard Grids
 ------------------
 
-lorem ipsum
+Select from the available list of resolutions (combinations of model grids) below.
+Resolutions known to be incompatible with your chosen compset have been omitted 
+from this list. Use the search box to refine the list further. For exact matches,
+use double quotes; otherwise, the search will display all grids containing one 
+or more of the search terms.
+
+.. image:: assets/stage2_2.png
+
+After selecting a grid, visualCaseGen will advance to the `Launch` stage, where
+you can create your CESM case using the chosen compset and grid configuration.
 
 Custom Grids
 ------------------
 
-lorem ipsum
+In Custom Grid mode, you can build a custom grid by mixing and matching standard 
+model grids or generating new MOM6 and/or CLM grids with specialized tools that come with visualCaseGen.
+Start by specifying a path to save the new grid files and a name to refer to this
+new grid in the configuration process and beyond.
+
+.. image:: assets/stage2_3.png
+
+After clicking `Select`, a file browser will open to help you locate your preferred
+directory for saving the new grid files. Once the directory is selected, enter the
+new grid name in the text box at the top right and click `Select` to proceed.
+
+.. image:: assets/stage2_4.png
+
+Atmosphere Grid
+~~~~~~~~~~~~~~~
+
+Next, choose an atmosphere grid from the list of compatible options based on the
+compset you selected in the `Compset` stage. Use the search box to filter options if needed.
+This chosen atmosphere grid will be integrated with other model grids to form your custom CESM grid (resolution).
+
+.. image:: assets/stage2_5.png
+
+Ocean Grid
+~~~~~~~~~~
+
+For the ocean grid, if MOM6 is selected as the ocean model, you can either select a standard
+ocean grid or create a new MOM6 grid. When creating a new MOM6 grid, you'll specify parameters
+such as grid extent and resolution, after which you'll be directed to a separate notebook that
+uses the `mom6_bathy` tool to generate the new grid and bathymetry.
+
+If using a standard ocean grid, select one from the list compatible with your chosen compset
+and atmosphere grid. If creating a new MOM6 grid, complete the required parameters, then proceed
+to launch the `mom6_bathy` tool for final customization.
+
+.. image:: assets/stage2_6.png
+
+After specifying all ocean grid parameters, click `Launch mom6_bathy`. This will open an 
+auto-generated Jupyter notebook where you can fine-tune the ocean grid bathymetry and generate
+all necessary input files. For more details on mom6_bathy, refer to its documentation: https://ncar.github.io/mom6_bathy/
+
+.. note:: If the `mom6_bathy` notebook doesn't open automatically, make sure that your browser allows
+  pop-ups from visualCaseGen. If the notebook still doesn't open, you can manually launch it by
+  navigating to the `mom6_bathy_notebooks/` directory in your visualCaseGen installation and opening
+  the notebook corresponding to your custom grid.
+
+
+Land Grid
+~~~~~~~~~
+
+Following ocean grid selection or creation, you'll move to land grid selection. If CLM is chosen
+as the land model, you can also modify an existing CLM grid. If so, select a base land grid for
+customization.
+
+.. image:: assets/stage2_7.png
+
+.. note:: Detailed instructions on customizing an existing CLM grid will be added here shortly.
 
+Once atmosphere, ocean, and land grids have been chosen or created, custom grid setup is complete.
+visualCaseGen will guide you to the final stage, `Launch`, where you can create a CESM case based on
+the specified compset and grid.

docs/index.rst

@@ -43,7 +43,7 @@ For more information on each step, please refer to the corresponding sections in
 
 .. toctree::
    :maxdepth: 3
-   :caption: Contents:
+   :caption: User Manual:
 
    installation
    open

docs/launch.rst

@@ -1,5 +1,56 @@
 Stage 3/3: Launch
 =================
 
-lorem ipsum
+The final main stage of visualCaseGen is the `Launch` stage, where you bring your CESM case to
+life with the selected compset and grid configuration. In this stage, you'll find tools to
+select the case directory, choose a target machine, and initiate case creation. 
+
+.. image:: assets/stage3_1.png
+
+Chosing the case directory
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To begin, open the file browser widget by clicking the `Select` button to set the directory for
+the new case. Navigate to your desired location, then enter a unique name for the case in the
+text box at the top right of the browser. Click `Select` to confirm your directory and case name.
+
+.. image:: assets/stage3_2.png
+
+Selecting the target machine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Next, choose the machine where the case will run. If CESM has already been ported to the machine,
+this selection should populate automatically. If not, confirm that CESM is properly ported to the
+machine you intend to use and that the correct machine is selected. For some systems, a PROJECT ID
+is required; if so, you'll be prompted to enter it here.
+
+.. note::
+  If you're using a machine that shares a file system with another, you have the flexibility
+  to select a different machine for running the case. For example, if you are working within
+  visualCaseGen on *casper* but intend to run the case on *derecho*, simply change the machine selection
+  to *derecho* at this stage. This allows you to configure the case on one machine while specifying
+  execution on another within the shared system environment.
+
+Creating the case
+~~~~~~~~~~~~~~~~~
+
+When all selections are finalized, you can click `Create Case` to initiate case creation or 
+`Show Commands` to view the terminal commands that will be executed. Below, you'll see an
+example of the interface after clicking `Create Case`. Notice how visualCaseGen handles the
+case setup process, including modifying CESM XML files, executing the create_newcase tool,
+running the `case.setup` script, and applying any XML and namelist changes needed.
+
+.. image:: assets/stage3_3.png
+
+The completion log provides confirmation of a successful case creation, including the path to
+the new case directory, where you can proceed with case customization, building, and execution.
+
+Congratulations!
+~~~~~~~~~~~~~~~~
+
+You've successfully created a CESM case using visualCaseGen, bringing together the models,
+grid, and configurations tailored to your scientific goals. With the case directory set up,
+you're ready to move forward with any additional customizations, building, and executing your
+case. Great job, and happy modeling!
+
 

docs/troubleshooting.rst

@@ -22,3 +22,9 @@ Commonly Encountered Issues
 - **Hanging Loadbar:** If the loadbar hangs after clicking the `Start` button, click the `Help` button on the top
   right corner of the welcome dialog to see if any error messages are displayed. If so, submit an issue on the
   visualCaseGen GitHub repository with the error messages.
+
+- **mom6_bathy notebook doesn't open automatically:** If the `mom6_bathy` notebook doesn't open automatically, 
+  make sure that your browser allows
+  pop-ups from visualCaseGen. If the notebook still doesn't open, you can manually launch it by
+  navigating to the `mom6_bathy_notebooks/` directory in your visualCaseGen installation and opening
+  the notebook corresponding to your custom grid.