Merge pull request #758 from nsidc/trey-tutorial-docs-updates

Trey tutorial docs updates

doc/conf.py

@@ -187,3 +187,10 @@ def linkcode_resolve(domain, info):
 extlinks = {
     "github": ("https://github.com/nsidc/qgreenland/tree/main/%s", "GitHub: %s"),
 }
+
+# -- Options for figures ------------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-numfig:
+#   > If true, figures, tables and code-blocks are automatically numbered if
+#   > they have a caption.  The numref role is enabled. Obeyed so far only by
+#   > HTML and LaTeX builders.
+numfig = True

doc/disclaimer.md

@@ -16,6 +16,6 @@ the best approximation reference layer for geolocating Greenland's coastline.
 
 Note that some data were transformed from their native data formats,
 projections, and resolutions for inclusion within QGreenland. The included
-metadata (>Layer Properties >Metadata >History) contains provenance information
+metadata (**Layer Properties -> Metadata -> History**) contains provenance information
 on any transformations. All QGreenland GeoPackages and GeoTIFFs are projected
 in `EPSG:3413`.

doc/user/tutorials/analyze-ice-sheet-volume.md

@@ -1,3 +1,4 @@
+(calculate-volume-greenland-ice-sheet-tutorial)=
 # Calculate the volume of the Greenland ice sheet
 
 The **Processing Toolbox** in QGIS provides a collection of tools and
@@ -22,8 +23,8 @@ first
 
 ## Open the Processing Toolbox
 
-The **Processing Toolbox** can be opened from the menu bar by selecting
-**"View>Panels>Processing Toolbox"**. This will open a new panel with a variety of
+The **Processing Toolbox** can be opened from the menu bar by selecting **View
+-> Panels -> Processing Toolbox**. This will open a new panel with a variety of
 processing tools organized into groups.
 
 ![processing_toolbox](/_images/processing_toolbox.jpg)
@@ -36,9 +37,9 @@ Toolbar** ![attributes-toolbar](/_images/attributes-toolbar.jpg).
 
 ## Use the Raster Surface Volume tool
 
-In the **Processing Toolbox**, go to **"Raster analysis > Raster surface volume"**. This
-is an algorithm that calculates the volume under a raster grid’s
-surface. Double-click **"Raster surface volume"** to open the tool's window, and
+In the **Processing Toolbox**, go to **Raster analysis -> Raster surface
+volume**. This is an algorithm that calculates the volume under a raster grid’s
+surface. Double-click **Raster surface volume** to open the tool's window, and
 enter the following parameters:
 
 * **Input layer** = Ice thickness (150 m)
@@ -52,26 +53,26 @@ enter the following parameters:
 
 ![raster_surface_volume](/_images/raster_surface_volume.jpg)
 
-Click "Run" and wait for the analysis to finish. The window will switch to the
-"Log" tab, which shows log messages and results for the run. A **Results
+Click **Run** and wait for the analysis to finish. The window will switch to the
+**Log** tab, which shows log messages and results for the run. A **Results
 Viewer** panel should open in a panel underneath the **Processing
-Toolbox**. Close the Raster surface volume tool's window and click on the
+Toolbox**. Close the **Raster surface volume** tool's window and click on the
 "Surface volume report" entry in the **Results Viewer**. This will show a link to
 a results HTML page that can be opened in your broswer. Open this file and
 review the results.
 
 ![results_viewer](/_images/results_viewer.jpg)
 
-The **results file** will contain information from the run, including which file was
+The results file will contain information from the run, including which file was
 analyzed, the calculated volume, pixel count, and total area. If one has
 succuessfully run the analysis, the results should show that the Greenland ice
-sheet has a volume of 2,942,360,633,311,806 m<sup>3</sup>, or about 2.9 million
+sheet has a volume of 2,965,561,810,382,715 m<sup>3</sup>, or about 3 million
 km<sup>3</sup>.
 
 ## Summary
 
 In completing this tutorial, the user has become familar with the **Processing
-Toolbox** and has successfully utilized the Raster Surface Volume tool with ice
+Toolbox** and has successfully utilized the **Raster Surface Volume** tool with ice
 sheet thickness data included in the QGreenland core package to calculate the
 volume of the Greenland ice sheet. Having accomplished this, the user is now
 ready to explore other geospatial processing tools included in the **Processing

doc/user/tutorials/create-print-layout.md

@@ -12,9 +12,9 @@ for complete documentation on print layouts in QGIS.
 
 ##  Creating a new print layout
 
-Once one has created a map in the **QGIS map display** that one would like to print
-or publish, one needs to switch to the **QGIS print layout**. Select **"Print Layout"**
-from the "Project" menu.
+Once one has created a map in the QGIS **Map View** that one would like to print
+or publish, one needs to switch to the QGIS **Print Layout**. From the menu bar,
+select **Project -> Print Layout**.
 
 ```{note}
 The **Project Toolbar** ![project_toolbar](/_images/project_toolbar.jpg) also
@@ -23,7 +23,7 @@ that creates a new **Print Layout**.
 ```
 
 First, name the new print layout after the figure you plan to create and click
-**"OK"**.
+**OK**.
 
 ![print_layout_name](/_images/print_layout_name.jpg)
 
@@ -34,7 +34,7 @@ When the print layout window opens, it will be initially blank.
 ## Changing the print layout's properties
 
 To change the size and orientation of your print layout, right click in the map
-area and choose **"Page Properties"**. This will add page size options to the **Item
+area and choose **Page Properties**. This will add page size options to the **Item
 Properties** panel on the right side of the screen.
 
 ![print_page_properties](/_images/print_page_properties.jpg)
@@ -58,8 +58,8 @@ possible to manipulate the map area within the box.
 
 Now explore some of the other buttons included in the map layout Toolbar. Add a
 north arrow and scale bar. Finally, once one is happy with the layout, try
-exporting the layout as an image by opening the **"Layout"** menu and selecting
-**"Export as Image"**.
+exporting the layout as an image by opening the **Layout** menu and selecting
+**Export as Image**.
 
 ## Summary
 

doc/user/tutorials/get-started.md

@@ -52,7 +52,7 @@ version of QGIS.
 
 ```{note}
 If QGIS is already open, one can open the `qgreenland.qgs` project file
-within QGIS by navigating to the **"Project >Open..."** option in the menu bar and
+within QGIS by navigating to the **Project -> Open...** option in the menu bar and
 selecting the `qgreenland.qgs` file from its saved location.
 ```
 
@@ -67,8 +67,14 @@ are using, your QGIS interface may look slightly different.
 The main components of the QGIS interface are the **Map view**, **Status bar**, **Layers panel**, 
 **Toolbars**, and the **Menu bar**. 
 
-![map_view](/_images/map_view.jpg)
-Fig. 1: Main components of the QGIS/QGreenland interface
+
+```{figure} /_images/map_view.jpg
+---
+alt: Map View
+name: map_view
+---
+Main components of the QGIS/QGreenland interface.
+```
 
 The **Map View** is the main part of the QGIS/QGreenland Core interface where the data layers are
 displayed. A GIS ‘layer’ refers to a geospatial dataset along with the symbols and labels used
@@ -87,25 +93,67 @@ vice versa. Layers can be manually moved around in the **Layers Panel** to chang
 the order in which they show up. **Panels** and **Toolbars** can also be manually moved
 around the QGIS interface to fit the user’s preferences. 
 
-When you first open the QGreenland Core data package, two reference layers will be automatically toggled on: Greenland coastlines 2017 and the QGreenland Basemap. Layers can be rearranged by clicking and dragging up or down. Layer groups can be expanded or collapsed by clicking on the arrow to the left of the checkbox. To expand or collapse all layers at once, click on the respective buttons (Fig. 2 (a)) right above the layers list in the **Layers Panel**. In addition to the **Layers Panel**, there are a variety of other panels that can be displayed on the QGIS interface. For example, the Browser panel provides a shortcut for accessing other data layers or project files on your computer or another location. Panels can be moved around the interface by clicking and dragging, and can be removed by clicking on the ‘X’ box in the upper righthand corner.
-
-![QGIS_fig2](/_images/QGIS_fig2.png)
-
-Fig. 2: (a) Buttons above **Layers Panel** to expand or collapse layers; (b) hand button to grab and drag the map view; (c) magnifying glass buttons to zoom in or out in map view; (d) Zoom Full button to bring all visible layers into **Map View**; (d) Zoom to Layer button to bring a desired layer into view. 
-
-The **Toolbars** contain buttons that allow the user to interact with the **Map View**. For example, the hand button (Fig. 2 (b)) in the **Map Navigation Toolbar** lets the user grab and drag the map view around. The magnifying glass buttons (Fig. 2 (c)) allow the user to zoom in and out or to a particular feature or
-selection in the map view. More information about a toolbar button’s function can be obtained by hovering one’s mouse over the button. **Toolbars** can be moved around the QGIS workspace by clicking and dragging. To toggle a toolbar on or off, simple right click on a toolbar and check or uncheck the desired boxes. (Fig. 3).
-
-If data layers are toggled on but not visible in the map view, the magnifying glass with three arrows (‘Zoom Full’) button (Fig. 2 (d)) will bring all visible layers back into the map view.
-Right clicking on a layer in the **Layers Panel** and selecting ‘Zoom to Layer’ or clicking on the magnifying glass over a square button (Fig. 2 (e)) in the **Map Navigation Toolbar** will also bring a desired layer into view in the **Map View**.
+When you first open the QGreenland Core data package, two reference layers will
+be automatically toggled on: Greenland coastlines 2017 and the QGreenland
+Basemap. Layers can be rearranged by clicking and dragging up or down. Layer
+groups can be expanded or collapsed by clicking on the arrow to the left of the
+checkbox. To expand or collapse all layers at once, click on the respective
+buttons ({numref}`qgis_buttons` (a)) right above the layers list in the **Layers
+Panel**. In addition to the **Layers Panel**, there are a variety of other
+panels that can be displayed on the QGIS interface. For example, the **Browser
+Panel** provides a shortcut for accessing other data layers or project files on
+your computer or another location. Panels can be moved around the interface by
+clicking and dragging, and can be removed by clicking on the ‘X’ box in the
+upper righthand corner.
+
+
+```{figure} /_images/QGIS_fig2.png
+---
+alt: QGIS buttons
+name: qgis_buttons
+---
+(a) **Expand All** and **Collapse All** buttons at the top of the **Layers
+Panel** to expand or collapse layers; (b) **Pan Map** button in the **Map
+Navigation Toolbar** to grab and drag the map view; (c) **Zoom In** and **Zoom
+Out** buttons in the **Map Navigation Toolbar** to zoom in or out in map view;
+(d) **Zoom Full** button in the **Map Navigation Toolbar** to bring all visible
+layers into the **Map View**; (d) **Zoom to Layer** button in the **Map
+Navigation Toolbar** to bring a desired layer into view.
+```
 
-![QGIS_figure3](/_images/QGIS_figure3.png)
-Fig. 3: **Toolbars** can be added or removed by right clicking on the toolbar area and checking/unchecking boxes.
+The **Toolbars** contain buttons that allow the user to interact with the **Map
+View**. For example, the **Pan Map** button ({numref}`qgis_buttons` (b)) in the
+**Map Navigation Toolbar** lets the user grab and drag the map view around. The
+magnifying glass buttons ({numref}`qgis_buttons` (c)) allow the user to zoom in
+and out or to a particular feature or selection in the map view. More
+information about a toolbar button’s function can be obtained by hovering one’s
+mouse over the button. **Toolbars** can be moved around the QGIS workspace by
+clicking and dragging. To toggle a toolbar on or off, simple right click on a
+toolbar and check or uncheck the desired boxes ({numref}`qgis_toolbars`).
+
+If data layers are toggled on but not visible in the map view, the magnifying
+glass with three arrows (**Zoom Full**) button ({numref}`qgis_buttons` (d)) will
+bring all visible layers back into the map view.  Right clicking on a layer in
+the **Layers Panel** and selecting **Zoom to Layer** or clicking on the
+magnifying glass over a square button ({numref}`qgis_buttons` (e)) in the **Map
+Navigation Toolbar** will also bring a desired layer into view in the **Map
+View**.
+
+
+```{figure} /_images/QGIS_figure3.png
+---
+alt: QGIS Toolbars
+name: qgis_toolbars
+---
+**Toolbars** can be added or removed by right clicking on the toolbar area and checking/unchecking boxes.
+```
 
-Lastly, the **Menu bar** and **Toolbars** are different ways to access most QGIS functions, such
-as opening or saving a project or analyzing the data using geoprocessing
-tools. **Panels** are another way for users to interact with data layers and
-functions in QGIS. You can fully customize the look and layout of your QGIS interface by going to ‘View’ in the menu bar and selecting the **Panels**, **Toolbars**, etc. that you would like visible.
+Lastly, the **Menu bar** and **Toolbars** are different ways to access most QGIS
+functions, such as opening or saving a project or analyzing the data using
+geoprocessing tools. **Panels** are another way for users to interact with data
+layers and functions in QGIS. You can fully customize the look and layout of
+your QGIS interface by going to ‘View’ in the menu bar and selecting the
+**Panels**, **Toolbars**, etc. that you would like visible.
 
 
 ```{note}
@@ -120,9 +168,10 @@ GIS](https://docs.qgis.org/3.28/en/docs/gentle_gis_introduction/index.html)
 
 ## 4) Browse data in the QGreenland project
 
-Layers in QGreenland Core are organized into groups by category. For example, the
-"Background boundary" layer is "QGreenland boundaries" group, which is itself
-inside of the "Reference" group ("Background boundary/Reference").
+Layers in QGreenland Core are organized into groups by category. For example,
+the "Background boundary" layer is "QGreenland boundaries" group, which is
+itself inside of the "Reference" group ("Reference/QGreenland
+boundaries/Background boundary").
 
 ![layer_groups](/_images/layer_groups.jpg)
 
@@ -133,8 +182,8 @@ visualize another data layer (or remove an existing one), toggle the checkbox
 next to the layer in the **Layers panel**.
 
 Toggle on the "Ice thickness (150m)" layer, which is in the "Terrain
-models/Bedmachine" group. The **Map view** should now include a visualization of
-Ice thickness at a 150m spatial resolution.
+models/Bedmachine v5" group. The **Map view** should now include a visualization
+of Ice thickness at a 150m spatial resolution.
 
 ![ice_thickness_displayed](/_images/ice_thickness_displayed.jpg)