style_guide.rst

Course Materials Style Guide

Introduction

Purpose

This document serves as a collection of the policies and procedures for writing ReStructured Text (RST) content for the courses offered by the Field Engineering team.

As this document was created long after the original RST files were created, we understand that most of the existing content does not match this guide. But any new additions and modifications should adhere to them.

Producing This Guide

This file is designed to be read as a document (as opposed to the slides we generate for training purposes). As such, the command to generate the document would be:

pandoc_fe.py --source ./style_guide.rst --output style_guide.docx --extension docx

(update paths as appropriate)

Course Structure

Courses

A course is stored in a directory in the courses folder of the repository. The course directory contains all of the module information and a standard_course.txt file that contains a list of the modules most commonly taught in that course. If there is a need for a different course listing that is used consistently, it will also have the .txt extension.

The directory name for the course should be the course title, using underscores where blanks would be expected. We are using "<language>_essentials" for the three languages we support (Ada, SPARK, Rust) and then either the tool name (e.g. "gnatsas") or a brief description (e.g. "gnat_project_facility") for any other course.

Modules

A module is a self-contained unit within the course, focusing on a specific concept or set of related concepts. Each module is a complete topic in itself and typically contains several chapters.

For each module in the course, the course folder should contain:

• Base module RST file that lists the chapters typically taught in the module
• Folder with the same name as the RST file that contains the chapter RST files

The module naming scheme uses a 3-digit prefix followed by the module name. This prefix should indicate the preferred order for teaching the module. A simple example would be

005_introduction.rst Introduction module file, containing a list of chapters

005_introduction Introduction module folder, containing an RST file for each chapter

010_overview.rst Overview module file, containing a list of chapters

010_overview Overview module folder, containing an RST file for each chapter

If there is need for multiple versions of the module (introduction, in-depth), the chapters will be stored in the module folder, but there will be an additional module file using the prefix and module name, and then a hyphen to describe the change from the base module.

170_tagged_derivation-intro.rst

195_exceptions-in_depth.rst

Module Structure

Each module will contain chapters - individual files that address a sub-topic within the module. These chapters should conform to the following rubric:

• Chapter 1: Introduction
  • First slide title: Topics Covered
    • Bold bullets for short title of each sub-topic
    • Indented bullet for short description of the sub-topic
  • Remaining slides (optional)
    • Background information about the general module purpose
• Chapters 2 through N
  • Various sub-topics within the scope of the module
• Lab (optional)
  • Description of lab
  • Lab answer
    • Can be multiple slides
    • Entire code if small
    • Selected portions if large
• Last chapter: Summary
  • First slide title: What We Covered
    • Bold bullets for short title of each sub-topic
    • Indented bullet(s) for review points for the sub-topic
  • Remaining slides (optional)
    • Only if necessary (exception not the rule)
    • More specific review of a particular sub-topic

Chapters

A chapter is a focused section within a module that delves into a specific sub-topic or a particular aspect of the module's broader concept. Chapters are designed to present information in a logical, step-by-step manner, often building upon preceding chapters within the same module to contribute to a complete understanding of the overall module topic. Think of chapters as individual lessons or specific themes that collectively form a comprehensive module.

Each chapter will be in its own RST file in the module folder.

The chapter name should start with a two digit number indicating its typical order of presentation. Sometimes, there are two versions of a chapter; they should have the same number and base name, with something added to describe the differences. Not all chapters will be used by every module, but there should never be two versions of the same chapter in a module.

To simplify renaming if we decide to reorder chapters within a module, the summary chapter will always be 99-summary[-version].rst and the lab will always be 88-<module_name>[-version].lab.rst. Examples:

• 88-expressions-with_quantified.lab.rst
• 88-expressions.lab.rst
• 99-summary-with_quantified.rst
• 99-summary.rst

File Naming Conventions

• Folder/file names should match their content with the following rules
  • Alpha-numeric characters only (no punctuation, dashes, etc.)
  • All spaces should be replaced with underscore ("_")
  • No leading, trailing, or consecutive underscores
  • Characters should all be lowercase
• Rules for course folder names
  • Folder name for a course should always match the name of the course
  • Tooling will convert first character in each "word" to upper case
    • In case a course name requires specific upper-case formatting (e.g. "gnatdas" should translate to "GNAT DAS"), you will need to update the "default_title" function in file "pandoc/pandoc_fe.py"
• Rules for module/chapter file names
  • Module and chapter file names should match the module/chapter title.
  • (Module/chapter versions are not part of the title)

Style Rules

Bullet Points

Bullets should always be used when a slide has multiple points to be made.

If a slide has a single point, no bullet should be added.

If a slide has sub-points, the sub-points should be nested bullets (regardless of how many top-level points there are). If there is one top-level point and one sub-point - rework the slide!

Module / Slide Titles

Slide titles are surrounded (via line above and below) by a line of "-" characters. The "-" characters should extend 2 characters past the end of the title string. Example:

-----------------

This is a Title

-----------------

Do not use roles (e.g. "loop) in a title - it does not translate well for easy RST viewing (like in Git) or in extracting information.

Use the following rules when roles/emphasis seems like a good idea in a title

• Filenames and toolnames should use bold emphasis in titles
• All other roles (such as language tokens, commands, etc) should put the text in quotes (")

Code Examples

Names

Code examples should use reasonble identifiers (as opposed to a single letter). Where reasonable, the names should be descriptive of the situation being explained.

Bad snippet

type OneD_T is array (Index_T) of Boolean;
B : OneD_T;

Better snippet

type One_Dimension_Array_T is array (Index_T) of Boolean;
One_Dimension : One_Dimension_Array_T;

Obviously, longer names may make the text harder to read on a slide. Try to balance expressiveness with brevity, and think about reformatting the code example as well.

Comments

Many times comments refer to names in the context. In this case, the name can be highlighted using single quotes not double quotes

function Good_Name (Bad_Name : Integer) return Boolean;
-- This is a good reference to 'Good_Name'.
-- But this is a bad reference to "Bad_Name".

Confusing Terms

• runtime / run-time / run time

  • runtime is basically the operating system
  • run-time means during execution
  • run time is how long the executable took

Spacing Issues

• Sometimes you need to insert whitespace in a slide

  • RST does not have a good way to do that

• Instead, insert some "raw" LaTeX commands into your slide

  .. raw:: latex
  
    \vspace{5mm}
  

  • Obviously you can change the 5 to suit your needs