Workbook

Setting up a half-day training workbook.

Workbooks are carefully constructed to be used as:

• attendee notes and step-by-step exercises

• instructor presentation and answer key

Workbook structure

Directory structure:

• .gitignore - optional to ignore files such as the build directory

• README.md - workbook title and objectives

• build.xml - ant build script

• build.properties - fill-in-the blank properties for build script

• target/ - generated output

• src/ - workbook contents

• src/config.py - sphinx build file

build.xml

Apache Ant is a cross platform build system similar to the unix make command. It defines a series of build targets that can be performed on the command line. Each build target is a small recipe consisting of tasks to be performed. Build targets can depend on each other (so that training material must be generated before being packaged as a zip bundle).

To list ant build targets intended for use (those that have a desription):

ant -p

% ant -p
Buildfile: example/build.xml
GeoCat Theme Example Writing guidelines
ant script to run sphinx-build:
  ant clean
  ant workbook
  ant workbook -Dopen=true

Main targets:

 build       build documentation (requires sphinx-build)
 bundle      Package instructor workbook and slides
 clean       clean up build directory
 instructor  instructor notes
 package     Package workbook for attendees
 slides      instructor slides
 workbook    attendee workbook
Default target: build

Examples are written using http://localhost:8080..., to override:

ant clean build -Dhost=https://training.geocat.live/

An override perform a search and replace the generated output.

Postprocessing is used to handle http://localhost:8080/geoserver links in sample data and generated html:

{
    "version": 8,
    "name": "Example",
    "sprite": "http://localhost:8080/geoserver/styles/sprite",
    "glyphs": "http://localhost:8080/geoserver/styles/{fontstack}/{range}.pbf"
}

.. literalinclude:: files/example.json
   :language: json
   :linenos:

See also Dynamic Examples .

README.md

Shown when browsing content in GitHub and GitLab.

Note sphinx-build can process markdown files, however an exclude_pattern has been configured to avoid processing README.md file.

conf.py

Configuration file for sphinx-build and configure builders for html and slide output.

The config.py file is written in python, we have used this to:

• Parse build.properites

• Current year, copyright and license information

• Extensions used

• External links

• Configure html builder

• Configure slide builder

# (c) GeoCat B.V. and others
#
# Configuration file for the Sphinx documentation builder.
#
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# http://www.sphinx-doc.org/en/master/config


# -- setup --------------------------------------------------------------------

import datetime
import os
import warnings

# ignore warning from docutils code
# https://github.com/sphinx-contrib/confluencebuilder/pull/289
warnings.filterwarnings("ignore", category=FutureWarning) 

# -- Build properties --------------------------------------------------------

build_dir = os.path.sep.join(os.getcwd().split(os.path.sep)[:-2])
properties_file = os.path.join(build_dir,'build.properties')

build_properties = dict()
with open(properties_file, 'r') as file:
    for line in file:
        key = line.split('=')[0]
        value = line.split('=')[1].strip('\n')
        build_properties[key] = value

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

# -- Project information -----------------------------------------------------

now = datetime.datetime.now()
year = now.year

project = build_properties['project']
copyright = u'{}, GeoCat BV'.format(year)
author = build_properties['author']

# The short X.Y version.
version = now.strftime('%Y.%m')

# The full version, including alpha/beta/rc tags.
release = now.strftime('%Y.%m.%d')


# -- General configuration ---------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '3.2.1'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
  'sphinxcontrib.jquery',
  'sphinx.ext.todo',
  'sphinx.ext.ifconfig',
  'sphinx.ext.extlinks',
  'hieroglyph',
  'sphinx_copybutton',
  'myst_parser'
]

# Add any paths that contain templates here, relative to this directory.
templates_path = [
  os.path.join(build_dir,build_properties['theme_path'])
]

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The encoding of source files.
source_encoding = 'utf-8'

# The master toctree document.
master_doc = 'index'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'en'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['**/Thumbs.db', '**/.DS_Store','**/README.md']

# highlight language pygments lexer name (defaults to 'default' tries python3 and falls back to none)
highlight_language = 'none'

# options for pygments lexer
highlight_options = {
   'tabsize': 2
}

# The name of the Pygments (syntax highlighting) style to use, or None for theme.conf default
pygments_style = None

# Disable smart quotes as they cause issues with code examples
smartquotes = False

# -- Extension External Links ------------------------------------------------
if 'host' in build_properties :
   host = build_properties['host']
else:
   host = 'http://localhost:8080/'

extlinks = {
    'host': (host+'/%s','%s'),
    'geoserver': ('http://docs.geoserver.org/latest/en/user/%s','%s'),
    'sphinx': ('https://www.sphinx-doc.org/en/master/%s','%s')
}

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'geocat_rtd'

# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = [
  os.path.join(build_dir,build_properties['theme_path'])
]

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
html_theme_options = {
    'logo_only': True,
    'display_version': False,
    'prev_next_buttons_location': 'bottom',
    'show_sphinx': False,
    'show_home': False,
    'is_prerelease': True
}

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
html_logo = 'geocat_product_logos.svg'

# The name of an image file (within the static path) to use as favicon of the
# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
html_favicon = 'favicon.ico'

html_show_sourcelink = False

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
#html_static_path = ['_static']

html_js_files = [
    'js/gctools.js'
]

# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
#
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself.  Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
#
# html_sidebars = {}


# -- Options for HTMLHelp output ---------------------------------------------

# Output file base name for HTML help builder.
htmlhelp_basename = 'GeoCatThemeExampledoc'

# -- Options for Hieroglyph output ---------------------------------------------

slide_title = project

autoslides = True
slide_theme = 'geocat_slides'
subtitle = build_properties['subtitle']
slide_footer = 'GeoCat '+version
slide_levels = 4
slide_numbers = True

# requires html and slides build
slide_link_to_html = True
slide_link_html_to_slides = True
slide_link_html_sections_to_slides = True
slide_relative_path = '_slides/'
slide_html_relative_path = '../' 
slide_html_slide_link_symbol = '§'

# -- Options for LaTeX output ------------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    # 'preamble': '',

    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (master_doc, 'GeoCatThemeExample.tex', 'GeoCat Theme Example',
     'GeoCat BV', 'manual'),
]


# -- Options for manual page output ------------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (master_doc, 'example', 'GeoCat Theme Example',
     [author], 1)
]


# -- Options for Texinfo output ----------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (master_doc, 'GeoServerEnterprise', 'GeoServer Enterprise Documentation',
     author, 'GeoServerEnterprise', 'One line description of project.',
     'Miscellaneous'),
]


# -- Options for Epub output -------------------------------------------------

# Bibliographic Dublin Core info.
epub_title = project

# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
#
# epub_identifier = ''

# A unique identification for the text.
#
# epub_uid = ''

# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']

build.properties

Provide properties to conf.py:

project=GeoCat Theme Example
subtitle=Writing guidelines
author=GeoCat BV
theme_path=..
destfile=writing_guide
host=http://localhost:8080/

Workbook contents

Sphinx toctree contents:

• src/index.rst - title page and table of contents

• src/figure/ - diagrams and illustrations

• src/img/ - common images

Common sections:

• src/welcome/index.rst - overview and objectives

• src/review/index.rst - optional review for certifications

Section contents:

• src/section/index.rst - section page

• src/section/exercsie.txt - exercise included in text

• src/section/img - images and screen snaps

• src/section/files - files for literal includes and downloads

Initial index.rst

Carefully constructed providing:

• Workbook title

• toctree caption for the rtd theme

• Instructor note linking to slides

• placeholder slides as needed

############################
GeoCat Documentation Example
############################

.. ifnotslides::

   Writing guide with cut-and-paste examples for your own documentation, user manuals, and training materials.

.. slide:: GeoCat Introduction
   :level: 1
   :class: slide-intro

   .. figure:: /img/geocat_logo_text.*

   Spatial data publication and discovery with products, services and philosophy following the free and open source source software.
   
   Software development company based in Bennekom, with developers in the Netherlands, Spain and Canada.

.. _contents:

.. slide:: GeoCat Documentation Example
   :level: 2
   :inline-contents: True
   
   .. toctree::
      :maxdepth: 1
      :caption: Contents
  
      guide/index
      workbook/index
      example

.. toctree::
   :caption: Reference
   :hidden:
   
   glossary

.. ifnotslides::
   
   Reference:

   * :doc:`glossary`
   * :ref:`genindex`
   
.. only:: instructor
   
   .. admonition:: `Sides <_slides/index.html>`__
      
      * :kbd:`t` for slide table
      * :kbd:`c` for presenters console

.. slide:: Free and Open Source Company
   :level: 1
   :class: slide-heart

.. slide:: Made with ♥ by GeoCat
   :level: 2
   :class: slide-outro
   
   For more information about GeoCat, visit `www.geocat.net <https://www.geocat.net>`__ 

figure folder

Used for svg and png diagrams:

geoserver_data_directory.svg
geoserver_data_directory.png

Figures are provided with a caption describing the content (even if that ends up repeating some of the text).

The GeoServer data directory is the location of the configuration information on disk.

GeoServer data directory

The GeoServer data directory is the location of the configuration information on disk.

.. figure:: /figure/geoserver_data_directory.*

   GeoServer data directory

Recommend use of a single shared figure folder as shown above with (leading / indicates path is relative to the config.py file). This makes it easier to manage and update diagrams.

Files folder

Used for scripts, configuration files, and sample data such as icons:

elevation.sld
place.png
place.svg

Keep in mind this content is bundled with the workbook content and is not intended for handling large files.

Scripts and configuration files are often presented as a code example using literalinclude directive.

1. Here is an improved elevation.sld SLD showing the elevations:

   <?xml version="1.0" encoding="ISO-8859-1"?>
   <StyledLayerDescriptor version="1.0.0"
     xsi:schemaLocation="http://www.opengis.net/sld http://schemas.opengis.net/sld/1.0.0/StyledLayerDescriptor.xsd"
     xmlns="http://www.opengis.net/sld" xmlns:ogc="http://www.opengis.net/ogc"
     xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <NamedLayer>
       <Name>elevation_points</Name>
       <UserStyle>
         <Title>Elevation Points</Title>
         <FeatureTypeStyle>
           <Rule>
             <Title>azure point</Title>
             <PointSymbolizer>
               <Graphic>
                 <Mark>
                   <WellKnownName>cross</WellKnownName>
                   <Fill>
                     <CssParameter name="fill">#333333</CssParameter>
                   </Fill>
                 </Mark>
                 <Size>3</Size>
               </Graphic>
             </PointSymbolizer>
             <TextSymbolizer>
              <Label>
                <ogc:PropertyName>elevation</ogc:PropertyName> m
              </Label>
              <LabelPlacement>
                <PointPlacement>
                  <AnchorPoint>
                    <AnchorPointX>0.5</AnchorPointX>
                    <AnchorPointY>0.0</AnchorPointY>
                  </AnchorPoint>
                  <Displacement>
                    <DisplacementX>0</DisplacementX>
                    <DisplacementY>2</DisplacementY>
                  </Displacement>
                </PointPlacement>
              </LabelPlacement>
             </TextSymbolizer>
           </Rule>
         </FeatureTypeStyle>
       </UserStyle>
     </NamedLayer>
   </StyledLayerDescriptor>
   

#. Here is an improved :download:`elevation.sld <files/elevation.sld>` SLD showing the elevations:

   .. literalinclude:: files/elevation.sld
      :language: xml

IMG folder

The root img folder is primarily used for branding or common screens such as how to login.:

gc_geosever_logo_300x300.png

Each section has an section/img folder used to manage screen snaps for the section.:

coverage_dem_bands.png
coverage_parameters.png
gray_preview.png

Screen snaps are used with the figure directive, so we can provide a caption.

The SUGGESTED_TILE_SIZE parameter is set automatically by GeoServer when images use internal tiling (generally this setting is not changed from its default).

Coverage parameters

The :guilabel:`SUGGESTED_TILE_SIZE` parameter is set automatically by GeoServer when images use internal tiling (generally this setting is not changed from its default).

.. figure:: img/coverage_parameters.png

   Coverage parameters

Page index.rst

Use straight forward writing with three levels of headings:

• Consistency is required as content is generated into both slides and workbooks

• Consistent structure and writing is both profesional and functional helping comprehension and ability to scan and review material.

Page
****

Section
=======

Content
-------

Content

Exercise
^^^^^^^^

Step-by-step instructions.

We are shifting to numbering toctree directives and providing a heading for exercises to help attendees quickly locate the right section to work on.

Workbook Writing

Care is taken to ensure that content generates as slides and workbook.

Workbooks are built with autoslides:

• Each page turns into a single presentation.

• Each heading becomes a new slide.

• Headings are cross linked between workbook and slides

Headings

Pages use straight forward writing with three levels of headings:

Page
****

Section
=======

Content
-------

Slide content

A forth level of headings is used for exercises:

Exercise: WMS GetCapabilities
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. ifslides::

   .. admonition:: Exercise

      Show the WMS GetCapabilities

.. ifnotslides::

   .. include:: wms_getcapabilities_exercise.txt

Distinct numbered heading helps class members locate exercise quickly.

Manage long pages using include directive for sections:

Basics
******

.. include:: admin.txt
.. include:: workspace.txt
.. include:: datastore.txt
.. include:: layer.txt
.. include:: group.txt
.. include:: style.txt

Slide breaks are available for sections:

.. rst-class:: slide-geoserver

GeoServer Enterprise
====================

.. ifnotslides::

   GeoServer Enterprise is a commercial distribution of GeoServer for GeoCat customers.

List of section-breaks provided by geocat_slides theme:

• slide-geocat - geonetwork enterprise branding

• slide-geoserver - geoserver enterprise branding

• slide-bridge

• slide-service

• slide-bennekom

• slide-victoria

• slide-outro

ifslides and ifnotslides directives

Use ifslides and ifnotslides to control content included in presentation and workbook.

Example

Access to the GeoServer data directory is required to manage the icons and fonts used for styling.

.. ifslides::

   Data directory access required for icons and fonts.

.. ifnotslides::

   Access to the GeoServer data directory is required to manage the icons and fonts used for styling.

Some content like references may only be in the workbook.

Example

Reference:

• WMS reference

.. ifnotslides::

   Reference:

   * :geoserver:`WMS reference <services/wms/reference.html>`

Slide directive

Use slide directive for additional slides.

.. slide:: GeoCat Introduction
   :level: 2
   :class: slide-intro

   .. figure:: /img/geocat_logo_text.*

   Spatial data publication and discovery with products, services and philosophy following the free and open source source software.

   Software development company based in Bennekom, with developers in the Netherlands, Spain and Canada.

Theme provides built-in slide classes:

Example

Slide-heart class

.. slide:: Free and Open Source Company
   :level: 1
   :class: slide-heart

Theme slide-outro is a nice way to end a presentation:

Example

Use of slide-outro to end presentation.

Note ref link to return to top-level .. _contents: anchor:

.. slide:: Questions and Review
  :level: 2
  :class: slide-outro

  :ref:`^ </contents>`

Special Themes

A list of the current special slides

Type	Description	Class	Extra
Introduction	Standard GeoCat introduction (Logo + Text). Title is not used.	:class: slide-intro
Author	Page for the Author	:class: slide-author
Heart	Adds the t-shirt slogan: Put your Heart in everything you do!	:class: slide-heart
GeoCat	Adds the lighter blue background, to be used for a title page, the 'title' is centered, do not use with additional text	:class: slide-geocat	Background color: #009BD2
GeoNetwork	To be used for a GeoNetwork Enterprise title page, the 'title' is centered, do not use with additional text	:class: slide-geonetwork	Background color: #0099CC
GeoServer	To be used for a GeoServer Enterprise title page, the 'title' is centered, do not use with additional text	:class: slide-geoserver	Background color: #00AD9F
Bridge	Adds the yellow background, to be used for a Bridge title page, the 'title' is centered, do not use with additional text	:class: slide-bridge	Background color: #FFD200
Live	Adds the orange background, to be used for a Live title page, the 'title' is centered, do not use with additional text	:class: slide-live	Background color: #FF9900
Service	Adds the dark blue background, to be used for a GeoCat Services title page, the 'title' is centered, do not use with additional text	:class: slide-service	Background color: #1F1249
Bennekom	Adds a photo of Bennekom as background, do not use with additional text	:class: slide-bennekom
Victoria	Adds a photo of Victoria as background, do not use with additional text	:class: slide-victoria
Outro	Slide to end your workshop/presentation, the content is positioned at the bottom, designed for a maximum of 2 lines of text	:class: slide-outro

Slide directive inline-contents

Example

Slide inline-contents used to generate a slide, and include the text in the workbook.

Writing guide with cut-and-paste examples for your own documentation, user manuals, and training materials.

Example

Slide inline-contents example

.. slide:: GeoCat Documentation Example
   :level: 2
   :inline-contents: True

   Writing guide with cut-and-paste examples for your own documentation, user manuals, and training materials.

Special Markup

Text size

By adding a class the text of a slide, or just a block can be changed. The available classes are: text-50, text-60, text-70, text-80 and text-90

Usage:

.. slide:: GeoCat Slides Example
   :level: 1
   :class: text-50

Containers

Containers in rst will be translated to a HTML <div>. The text after the :: will be the class names(s) of the <div>, so adding more than 1 term will end up in more than 1 class.

A container can be used to manipulate text size for a small part of the slide for example. However, the text size of the title element is left as-is.

Usage:

.. slide:: Container example
   :level: 2
   :inline-contents: False

   .. container:: col-container

Grids

When you want to display your contents in 2 (or 3) columns you have to use nested containers. The first container gets the class col-container and the children get class col-6 for example. Everything is based on a 12 column grid, so the columns should total 12. So you can use 2 columns of col-6, or a column of col-4 and col-8.

The following column options are available:

• col-4 - for 2 or 3 column layouts

• col-6

• col-8

• col-12 - special case for vertically centering texts

• col-middle (alias: col-center) - vertically center text/content

• col-bottom (alias: col-end) - align text/content to the bottom

• col-left - align content to the left of the column

• col-right - align content to the right of the column

Usage:

.. slide:: Example with Grid
   :level: 2

   .. container:: col-container

      .. container:: col-6 col-middle text-80

         Depending on the view configuration, editors can reorder elements using up and down controls.

      .. container:: col-6

         .. figure:: img/editor-control-updown.png

Vertically aligned text (or content)

Some extra configuration is needed to vertically align text, it's a combination of css flexbox and grid.

The slide itself needs a class box, the content needs a container with class col-container and a child with the classes col-12 and col-middle or col-bottom

Available classes:

• col-middle (alias: col-center) - vertically center text/content

• col-bottom (alias: col-end) - align text/content to the bottom

Usage:

.. slide:: Vertical text example
   :level: 2
   :class: box

   .. container:: col-container

      .. container:: col-12 col-middle blue

         Depending on the view configuration, editors can reorder elements using up and down controls.

Custom colours

The base styles have some colouring options, you can use the class directly, or [declare a role](https://docutils.sourceforge.io/docs/ref/rst/directives.html#custom-interpreted-text-roles) and use it inline. The role has to be declared on the same level as a slide.

Available classes (roles):

• blue

• yellow

• green

• red

• black

• white

Example with a role and class (blue):

.. role:: green

.. slide:: Re-ordering elements
   :level: 2
   :inline-contents: False
   :class: box

   .. container:: col-container

      .. container:: col-12 col-middle blue

         Depending on the view configuration, :green:``editors can`` reorder elements using up and down controls.

Instructor notes

Use only directive to include content in the instructor build of the workbook.

Example

Note

Instructor: What is the difference between the CRS:84 and EPSG:4326?

Instructor Notes

The difference is the strict definition of axis order.

.. note:: *Instructor*: What is the difference between the ``CRS:84`` and ``EPSG:4326``?

   .. only:: instructor

      .. admonition:: Instructor Notes

         The difference is the strict definition of axis order.

Writing Exercises

Avoid including exercise in slides

Use admonition and ifnotslides directive to avoid including the full exercises into presentations.

Example

WMS 1.3.0 GetCapabilities request

Exercise

Show the WMS GetCapabilities

Example

WMS 1.3.0 GetCapabilities request

Exercise

To show the WMS GetCapabilities:

1. Navigate to Demo ‣ Demo Requests page.

2. Select the WMS_1.1.1_GetCapabilities.url request. The full request is reproduced below, with line breaks added for clarity:

   http://localhost:8080/geoserver/wms?
     service=wms&
     version=1.1.1&
     request=GetCapabilities
   

   The server endpoint, service, and version are all the same as we have seen before. The only difference is the request, which is GetCapabilities. There are no other parameters needed.

3. Click Submit.

WMS 1.3.0 GetCapabilities request
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. ifslides::

   .. admonition:: Exercise

      Show the WMS GetCapabilities

.. ifnotslides::

   .. include:: wms_getcapabilities_exercise.txt

Exercises are written using txt extension to avoid being processed by sphinx-build until included.

wms_getcapabilities_exercise.txt:

.. admonition:: Exercise

   To show the WMS GetCapabilities:

   #. Navigate to :menuselection:`Demo --> Demo Requests` page.

   #. Select the ``WMS_1.1.1_GetCapabilities.url`` request. The full request is reproduced below, with line breaks added for clarity::

        http://localhost:8080/geoserver/wms?
          service=wms&
          version=1.1.1&
          request=GetCapabilities

      The server endpoint, ``service``, and ``version`` are all the same as we have seen before. The only difference is the ``request``, which is ``GetCapabilities``. There are no other parameters needed.

   #. Click :guilabel:`Submit`.

Use admonition block-directives

Consistently use admonition to clearly indicate the type of exercise.

Demo

Instructor demo on screen or online video.

Exercise

Step-by-step exercise required to proceed with workbook.

Explore

Review and apply concepts covered in workbook.

Challenge

Go beyond the workbook with experimentation and research.

Use combination of admonition to state type of exercise, and a topic sentence to introduce the step-by-step instructions:

Example

Exercise

Examine the styles of our newly imported layers, and compare two layers with the same geometries:

1. Click Layer Preview.

.. admonition:: Exercise

   Examine the styles of our newly imported layers, and compare two layers with the same geometries:

   #. Click :guilabel:`Layer Preview`.

Step-by-step instructions

Writing step-by-step instructions:

• Step clearly state what is being performed

• Any data entry or form input captured as list-table directive for cut-and-paste into application

• Include screen snap attendee can use to check their work (before hitting OK)

• Show the result of the action as a new numbered step with a screen snap.

• Use figure directive for screen snap, with caption naming what is on screen, adjusting size with figwidth as needed

#. Log in as the GeoServer administrator.

   .. list-table::
      :widths: 30 70
      :width: 100%
      :stub-columns: 1

      * - User:
        - :kbd:`admin`
      * - Password:
        - :kbd:`geoserver`
      * - Remember me
        - Unchecked

   .. figure:: img/server_geoserver_login.png

      GeoServer Welcome page

Example

1. Log in as the GeoServer administrator.

   User:	admin
   Password:	geoserver
   Remember me	Unchecked

   

   GeoServer Welcome page

Sphinx rst tips for step-by-step instructions:

• Use #. to number steps, so new steps can be added over time.

• Use directives kbd, gui-label, command, menu-selection consistently to allow theme designer to improve workbook appearance over time.

• Use figure directive to provide caption for each screen snap

Do not complicate step-by-step instructions with description or discussion. Or introduce new concepts, these should be covered in the presentation content.

• Discussion, alternatives and decisions are off-topic and confusing if attendee is stressed

• Do not use "simple" or "easy" as this is discouraging if attendee is frustrated (Common response is to blame themselves or blame the software and walk away).

If you really need to take a break for discussion, perhaps in an instructor demo. Make a clearly numbered step that is just discussion.