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:
antcleanbuild-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:
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
1# (c) GeoCat B.V. and others 2# 3# Configuration file for the Sphinx documentation builder. 4# 5# This file does only contain a selection of the most common options. For a 6# full list see the documentation: 7# http://www.sphinx-doc.org/en/master/config 8 9 10# -- setup -------------------------------------------------------------------- 11 12importdatetime 13importos 14importwarnings 15 16# ignore warning from docutils code 17# https://github.com/sphinx-contrib/confluencebuilder/pull/289 18warnings.filterwarnings("ignore",category=FutureWarning) 19 20# -- Build properties -------------------------------------------------------- 21 22build_dir=os.path.sep.join(os.getcwd().split(os.path.sep)[:-2]) 23properties_file=os.path.join(build_dir,'build.properties') 24 25build_properties=dict() 26withopen(properties_file,'r')asfile: 27forlineinfile: 28key=line.split('=')[0] 29value=line.split('=')[1].strip('\n') 30build_properties[key]=value 31 32# -- Path setup -------------------------------------------------------------- 33 34# If extensions (or modules to document with autodoc) are in another directory, 35# add these directories to sys.path here. If the directory is relative to the 36# documentation root, use os.path.abspath to make it absolute, like shown here. 37# 38# import os 39# import sys 40# sys.path.insert(0, os.path.abspath('.')) 41 42# -- Project information ----------------------------------------------------- 43 44now=datetime.datetime.now() 45year=now.year 46 47project=build_properties['project'] 48copyright=u'{}, GeoCat BV'.format(year) 49author=build_properties['author'] 50 51# The short X.Y version. 52version=now.strftime('%Y.%m') 53 54# The full version, including alpha/beta/rc tags. 55release=now.strftime('%Y.%m.%d') 56 57 58# -- General configuration --------------------------------------------------- 59 60# If your documentation needs a minimal Sphinx version, state it here. 61# 62# needs_sphinx = '3.2.1' 63 64# Add any Sphinx extension module names here, as strings. They can be 65# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 66# ones. 67extensions=[ 68'sphinxcontrib.jquery', 69'sphinx.ext.todo', 70'sphinx.ext.ifconfig', 71'sphinx.ext.extlinks', 72'hieroglyph', 73'sphinx_copybutton', 74'myst_parser' 75] 76 77# Add any paths that contain templates here, relative to this directory. 78templates_path=[ 79os.path.join(build_dir,build_properties['theme_path']) 80] 81 82# The suffix(es) of source filenames. 83# You can specify multiple suffix as a list of string: 84# 85# source_suffix = ['.rst', '.md'] 86source_suffix='.rst' 87 88# The encoding of source files. 89source_encoding='utf-8' 90 91# The master toctree document. 92master_doc='index' 93 94# The language for content autogenerated by Sphinx. Refer to documentation 95# for a list of supported languages. 96# 97# This is also used if you do content translation via gettext catalogs. 98# Usually you set "language" from the command line for these cases. 99language='en'100101# List of patterns, relative to source directory, that match files and102# directories to ignore when looking for source files.103# This pattern also affects html_static_path and html_extra_path.104exclude_patterns=['**/Thumbs.db','**/.DS_Store','**/README.md']105106# highlight language pygments lexer name (defaults to 'default' tries python3 and falls back to none)107highlight_language='none'108109# options for pygments lexer110highlight_options={111'tabsize':2112}113114# The name of the Pygments (syntax highlighting) style to use, or None for theme.conf default115pygments_style=None116117# Disable smart quotes as they cause issues with code examples118smartquotes=False119120# -- Extension External Links ------------------------------------------------121if'host'inbuild_properties:122host=build_properties['host']123else:124host='http://localhost:8080/'125126extlinks={127'host':(host+'/%s','%s'),128'geoserver':('http://docs.geoserver.org/latest/en/user/%s','%s'),129'sphinx':('https://www.sphinx-doc.org/en/master/%s','%s')130}131132# -- Options for HTML output -------------------------------------------------133134# The theme to use for HTML and HTML Help pages. See the documentation for135# a list of builtin themes.136#137html_theme='geocat_rtd'138139# Add any paths that contain custom themes here, relative to this directory.140html_theme_path=[141os.path.join(build_dir,build_properties['theme_path'])142]143144# Theme options are theme-specific and customize the look and feel of a theme145# further. For a list of options available for each theme, see the146# documentation.147#148html_theme_options={149'logo_only':True,150'display_version':False,151'prev_next_buttons_location':'bottom',152'show_sphinx':False,153'show_home':False,154'is_prerelease':True155}156157# The name of an image file (relative to this directory) to place at the top158# of the sidebar.159html_logo='geocat_product_logos.svg'160161# The name of an image file (within the static path) to use as favicon of the162# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32163# pixels large.164html_favicon='favicon.ico'165166html_show_sourcelink=False167168# Add any paths that contain custom static files (such as style sheets) here,169# relative to this directory. They are copied after the builtin static files,170# so a file named "default.css" will overwrite the builtin "default.css".171#html_static_path = ['_static']172173html_js_files=[174'js/gctools.js'175]176177# Custom sidebar templates, must be a dictionary that maps document names178# to template names.179#180# The default sidebars (for documents that don't match any pattern) are181# defined by theme itself. Builtin themes are using these templates by182# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',183# 'searchbox.html']``.184#185# html_sidebars = {}186187188# -- Options for HTMLHelp output ---------------------------------------------189190# Output file base name for HTML help builder.191htmlhelp_basename='GeoCatThemeExampledoc'192193# -- Options for Hieroglyph output ---------------------------------------------194195slide_title=project196197autoslides=True198slide_theme='geocat_slides'199subtitle=build_properties['subtitle']200slide_footer='GeoCat '+version201slide_levels=4202slide_numbers=True203204# requires html and slides build205slide_link_to_html=True206slide_link_html_to_slides=True207slide_link_html_sections_to_slides=True208slide_relative_path='_slides/'209slide_html_relative_path='../'210slide_html_slide_link_symbol='§'211212# -- Options for LaTeX output ------------------------------------------------213214latex_elements={215# The paper size ('letterpaper' or 'a4paper').216#217# 'papersize': 'letterpaper',218219# The font size ('10pt', '11pt' or '12pt').220#221# 'pointsize': '10pt',222223# Additional stuff for the LaTeX preamble.224#225# 'preamble': '',226227# Latex figure (float) alignment228#229# 'figure_align': 'htbp',230}231232# Grouping the document tree into LaTeX files. List of tuples233# (source start file, target name, title,234# author, documentclass [howto, manual, or own class]).235latex_documents=[236(master_doc,'GeoCatThemeExample.tex','GeoCat Theme Example',237'GeoCat BV','manual'),238]239240241# -- Options for manual page output ------------------------------------------242243# One entry per manual page. List of tuples244# (source start file, name, description, authors, manual section).245man_pages=[246(master_doc,'example','GeoCat Theme Example',247[author],1)248]249250251# -- Options for Texinfo output ----------------------------------------------252253# Grouping the document tree into Texinfo files. List of tuples254# (source start file, target name, title, author,255# dir menu entry, description, category)256texinfo_documents=[257(master_doc,'GeoServerEnterprise','GeoServer Enterprise Documentation',258author,'GeoServerEnterprise','One line description of project.',259'Miscellaneous'),260]261262263# -- Options for Epub output -------------------------------------------------264265# Bibliographic Dublin Core info.266epub_title=project267268# The unique identifier of the text. This can be a ISBN number269# or the project homepage.270#271# epub_identifier = ''272273# A unique identification for the text.274#275# epub_uid = ''276277# A list of files that should not be packed into the epub file.278epub_exclude_files=['search.html']
1############################ 2GeoCat Documentation Example 3############################ 4 5..ifnotslides:: 6 7 Writing guide with cut-and-paste examples for your own documentation, user manuals, and training materials.
8 9..slide:: GeoCat Introduction
10:level: 1
11:class: slide-intro
1213 ..figure:: /img/geocat_logo_text.*
1415 Spatial data publication and discovery with products, services and philosophy following the free and open source source software.
1617 Software development company based in Bennekom, with developers in the Netherlands, Spain and Canada.
1819.._contents:2021..slide:: GeoCat Documentation Example
22:level: 2
23:inline-contents: True
2425 ..toctree::26:maxdepth: 1
27:caption: Contents
2829 guide/index
30 workbook/index
31 example
3233..toctree::34:caption: Reference
35:hidden:3637 glossary
3839..ifnotslides::4041 Reference:
4243*:doc:`glossary`44*:ref:`genindex`4546..only:: instructor
4748 ..admonition::`Sides <_slides/index.html>`__4950*:kbd:`t` for slide table
51*:kbd:`c` for presenters console
5253..slide:: Free and Open Source Company
54:level: 1
55:class: slide-heart
5657..slide:: Made with ♥ by GeoCat
58:level: 2
59:class: slide-outro
6061 For more information about GeoCat, visit `www.geocat.net <https://www.geocat.net>`__
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.
#. Here is an improved :download:`elevation.sld <files/elevation.sld>` SLD showing the elevations:
..literalinclude:: files/elevation.sld
:language: xml
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
..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:
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.
..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:: GeoCat Documentation Example
:level: 2
:inline-contents: True
Writing guide with cut-and-paste examples for your own documentation, user manuals, and training materials.
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
45 ..container:: col-container
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.
910 ..container:: col-6
1112 ..figure:: img/editor-control-updown.png
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
45 ..container:: col-container
67 ..container:: col-12 col-middle blue
89 Depending on the view configuration, editors can reorder elements using up and down controls.
1..role:: green
2 3..slide:: Re-ordering elements
4:level: 2
5:inline-contents: False
6:class: box
7 8 ..container:: col-container
910 ..container:: col-12 col-middle blue
1112 Depending on the view configuration, :green:``editors can`` reorder elements using up and down controls.
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.
1..note::*Instructor*: What is the difference between the ``CRS:84`` and ``EPSG:4326``?
23 ..only:: instructor
45 ..admonition:: Instructor Notes
67 The difference is the strict definition of axis order.
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 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`.
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:
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`.
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.