Workbook§

Setting up a half-day training workbook.

^

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).

build.xml§

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

ant -p

post-processing§

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§

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

1{
2    "version": 8,
3    "name": "Example",
4    "sprite": "http://localhost:8080/geoserver/styles/sprite",
5    "glyphs": "http://localhost:8080/geoserver/styles/{fontstack}/{range}.pbf"
6}

.. 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

build.properties§

Provide properties to conf.py:

1project=GeoCat Theme Example
2subtitle=Writing guidelines
3author=GeoCat BV
4theme_path=..
5destfile=writing_guide
6host=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

Workbook contents§

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

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

Headings§

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.

Section include§

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

Section break§

Slide breaks are available for sections:

.. rst-class:: slide-geoserver

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

.. ifnotslides::

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

Headings§

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.

ifslides and ifnotslides directives§

.. 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.

Workbook references§

Some content like references may only be in the workbook.

.. 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.

Slide classes§

Theme provides built-in slide classes:

Example

Slide-heart class

Slide directive§

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

Ending a presentation§

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>`

Slide directive inline-contents§

Special Themes§

Slide directive inline-contents§

Slide directive inline-contents§

Example

Slide inline-contents example

Slide directive inline-contents§

.. 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:

1.. slide:: GeoCat Slides Example
2   :level: 1
3   :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:

1.. slide:: Container example
2   :level: 2
3   :inline-contents: False
4
5   .. 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:

 1.. slide:: Example with Grid
 2   :level: 2
 3
 4   .. container:: col-container
 5
 6      .. container:: col-6 col-middle text-80
 7
 8         Depending on the view configuration, editors can reorder elements using up and down controls.
 9
10      .. container:: col-6
11
12         .. 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:

1.. slide:: Vertical text example
2   :level: 2
3   :class: box
4
5   .. container:: col-container
6
7      .. container:: col-12 col-middle blue
8
9         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):

 1.. role:: green
 2
 3.. slide:: Re-ordering elements
 4   :level: 2
 5   :inline-contents: False
 6   :class: box
 7
 8   .. container:: col-container
 9
10      .. container:: col-12 col-middle blue
11
12         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.

Instructor notes§

1.. note:: *Instructor*: What is the difference between the ``CRS:84`` and ``EPSG:4326``?
2
3   .. only:: instructor
4
5      .. admonition:: Instructor Notes
6
7         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.

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

.. ifslides::

   .. admonition:: Exercise

      Show the WMS GetCapabilities

.. ifnotslides::

   .. include:: wms_getcapabilities_exercise.txt

Avoid including exercise in slides§

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§

Admonition and topic sentence§

.. 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

Step-by-step instructions§

Instructions: rst tips§

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

Instructions: Audience respect§

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.