This project is created for Sauce Labs using the open source tool created by google in the tools folder inside. Navigate to tools/README.md to learn more about this tool, how to use it, and get resources

This document will be for documenting sauce_school specific changes and specifications.

Setup The Environment

Local Setup

1. Get the Tools

Install Golang and nodeJS and NPM on your computer. More instructions here

2. Get Claat & Go Env Variables

Download the claat binary using the command

go install github.com/googlecodelabs/tools/claat/cmd@latest

OR

go get -u -v -x github.com/googlecodelabs/tools/claat

When you installed the GO SDK on your computer, it should have installed a folder in /usr/local/go/bin'. When you installed claat, it should have installed a /godirectory in your home directory. and if you navigate to'usr/bin` in your home directory after installing claat, you should see a claat binary as well. more detailed instructions can be found here.

The GOPATH variable should point to the directory where you installed claat (mine is in my $HOME directory), an the GOROOT directory should point to where your SDK was installed (probably in /usr/local/go).More on GOROOT and GOPATH

Make sure you have the Go environment variables in either .bash_profile or .zshrc:

## not required if you’re only using Go modules
export GOPATH=$HOME/go
export GOROOT=/usr/local/go
## required
export PATH=$PATH:$HOME/go/bin

For Windows users you will have to set this variable in the Advanced System Settings

You will want to make sure the the path for the GOROOT variable does in fact point to where your files are stored. use cd .. as many times as you need to get to the very top directory on your system, then cd usr/local and check to make sure the /go directory is installed there.

3. Clone This Repository

Choose where you would like to install sauce-school and either use SSH or HTTPS and install sauce-schools with:

git clone <insert copied url here>

4. Install Gulp

Install node modules in sauce-school main folder:

npm install

Install gulp globally with:

npm install --global gulp

Install gulp CLI tool globally with:

npm install --global gulp-cli

Find more detailed instructions here

5. Project Setup

The project setup is labeled sauce-school. Within it you should see the directories:

• /site
• /codelabs the codelabs directory is where module .md files are uploaded, and from there, they are exported with the guplp.js tool to /site/codelabs where the published versions are built.

Navigate to the site folder:

cd site

Install package dependencies and gulp dependencies in site directory

In order to use claat and gulp, you will need to install the node dependencies in the site folder:

npm install

Install the version of npm-sass that works with the version of NodeJs you have on your machine with:

 npm install [email protected]

7. Serve it Locally

To serve it up locally, ensure you are in site folder and run the command:

gulp serve

It will automatically render your markdown files as a static website. Open a browser and type in localhost:8080 and you should see the codelabs site.

Publishing with Codelabs in Sauce School

Access 'Codelabs' or Course files

The course are located in codelabs directory. Each course will contain a markdown file for each module by language (which contains several lessons) which is compiled into a directory containing an index.html rendered from the corresponding markdown page.

1. Add .md Files to add Courses

Claat will render an HTML page/ JSON file inside of site/codelabs.

Copy the template.md file and place it in the /codelabs directory. Make sure all metadata is updated.

• The /codelab directory contains all courses, each with several modules in it.

• To create a new course, make a copy of one of the directories in /site/app/views (not the default folder). Make sure the "tags" in view.json match the tags you put in the top-matter in your markdown file.

• Each Course module .md. file is labeled by language and module number (e.g. Module3_SeleniumJS.md).

• The tag at the top of each codelab markdown file identifies the course e.g. java, javascript, python etc.) which are made of many 'modules' with several lessons in it. The codelabs will br grouped together into a course (aka views) according to this tag.

*!IMPORTANT at the top of the .md file , you need to have project information with the id- this is the name of the rendered codelab in site/build/codelabs (see below).

• The feedback link is a G-Form for people to fill out about bugs/ issues/ questions.

• Convention, make the .md file use underscores_in_the_name.md and the folder containing that index.html (generated from id in .md file) codelabs files have dashes-in-the-name*

Example metadata at the top of .md file:

author:Lindsay Walker
summary: Module X of the course X. Learn to write Selenium tests in X programming language with X Test runner and X framework
id: ModiuleX_SeleniumLang
tags: <enter tag names here from /site/app/views/*.json>  
categories: <enter a single category for drop-down filter>
environments: Web
status: Published/ Work in Progress
feedback link: https://forms.gle/CGu4QchgBxxWnNJK8
analytics account: Google Analytics ID

More on markdown here

2. Docs to Markdown

When you create a new codelab markdown file from a GDoc, you can use the Docs to Markdown tool, however there will be some HTML tags at the top you need to delete, as well as title cleanup you need to do

• Make sure each title has one hash # for the course name. Each sub-category ('lesson') should have two hashes in front ##)
• Delete any HTML tags, they will screw things up
• Make sure you delete any random <p> tags within the doc, which may have been generated with Docs to Markdown.
• before each lesson with ##, above it insert <!-- ------------------------ --> to denote a new pages

3. Images

Images can mess things up. Make sure you list an image as assets/imagename.png withing the markdown file. The assets folder will be at the same level as the markdown page in /codelabs (not within a /codelabs/ModuleX folder)

4. Adding in Elements to .md files

See the template.md file for how to format most items

Images should be placed in the codelabs/assets directory and referenced as assets/filename.png. Convention is to name the file with a capial identifier for the coure, the module number, and A, B, C, etc for the first, second, third, etc picture in that course. As an example, the fourth picture in the Sauce Control Native Course module 1.05 would be assets/SCTLN1.05D.png

• Format for Images <img src="assets/filename.png" alt="Example Alt Text"/>
• Format for Links [Text to be highlighted](URL)
• Format for iframes ![embed URL](regular URL)
• Format for YouTube videos:

<video id="DWAinkJ54D8"></video>
<video id=""></video>

Video ID can be found in the url for the YouTube video=

More on how to convert markdown files is here

Optional Setup – Visual Studio Container

As I was going through the README I wanted to codify my dependencies and task definitions so that I don’t have to refresh myself the next time I contribute to the repository.

Dependencies:

Docker • https://www.docker.com/products/docker-desktop Remote Containers Extension • https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers

How to use:

Cmd + Shift + P => type "Reopen in container" ↩ Cmd + Shift + P => type "Run task" ↩ => type "serve" ↩

Reference: https://code.visualstudio.com/docs/remote/containers https://code.visualstudio.com/docs/editor/tasks