avxlabs-docs

Repository for lab guides for avxlabs-hosted classes including ACE, Flight School, and Build workshops. These guides are written in markdown and formatted in jupyter{book}. Jupyter{book} runs with a modified version of markdown called MyST - markdown with added features.

MyST Cheatsheet

Prerequisites

• Python >= 3.10
• pip3 install -r requirements.txt

Folder structure

• docs - published guide contents in subfolders (subfolder is the navigation uri for each guide).
• docs/_logos - shared images across all lab guides.
• images - images for the readme
• The rest of the folders contain the raw markdown content for each guide

Url

Guides are hosted at: https://docs.aviatrixlab.com/[guide-name]

Building a new lab guide

1. Clone this repository:

git clone https://github.com/AviatrixSystems/avxlabs-docs.git

2. Create a new branch for your work.

git switch -c new_branch_name

3. Create a new folder for the new guide using the naming convention [ace || flightschool || build]_[version]. Example: ace_associate
4. Create a folder call docs inside your new folder. This will be the location for your markdown files. Create as many or few files as needed. Each file will be a new section in the table of contents (toc).
5. Copy the _config.yml and _toc.yml files from an existing lab guide folder and edit the files appropriately. The toc.yml file has references to your markdown files (without the .md extension) located in the [your_folder]/docs directory.
6. When satisfied with the content created in steps 4 adn 5, run the following command to build your content in the jupyter format. At the end of the command, there will be a link to view your content in a browser.

jb build [your_folder]/
...
...
...
===================================================

Finished generating HTML for book.
Your book's HTML pages are here:
    your_folder/_build/html/
You can look at your book by opening this file in a browser:
    your_folder/_build/html/index.html
Or paste this line directly into your browser bar:
    file:///Users/your_user/Aviatrix/avxlabs-docs/your_folder/_build/html/index.html

===================================================

7. Commit your changes locally (to the local copy of the repository branch)

git add .
git commit -m "meaningful message that describes the changes in this commit"

8. Push your changes to the remote repository (push to origin)

git push

9. Create a PR to have the new guide published.

Useful code examples

Link to a file for download

Add this code to your markdown file, adjusting the text as needed. The icon and highlighted text are clickable:

Click this link to {Download}`the sample pdf<files/sample.pdf>`.

Example

Code block with syntax highlighting (and copy button)

Add this to the top of your md file, adjusting the language as necessary:

---
jupytext:
  formats: md:myst
  text_representation:
    extension: .md
    format_name: myst
kernelspec:
  display_name: Terraform
  language: terraform
  name: terraform
---

Then, create your code-cell block:

```{code-cell} terraform
resource "aviatrix_vpc" "aws_vpc" {
    cloud_type           = 1
    account_name         = "aws-account"
    region               = "eu-central-1"
    name                 = "aws-transit"
    cidr                 = "10.50.40.0/23"
    aviatrix_firenet_vpc = true
  }

  resource "aviatrix_transit_gateway" "aws_transit_gateway" {
    cloud_type        = 1
    account_name      = "aws-account"
    gw_name           = "aws-transit"
    vpc_id            = aviatrix_vpc.aws_vpc.vpc_id
    vpc_reg           = "eu-central-1"
    gw_size           = "t2.micro"
    subnet            = aviatrix_vpc.aws_vpc.public_subnets[0].cidr
    connected_transit = true
  }

Example

Cleanup

You can iterate and rebuild your content with the following command:

jb clean --all [your_folder]/

Remove unreferenced images

The following code, when run on macOS, will search through your images folder and remove any png files that aren't referenced in any markdown file. First, cd to the docs folder of your project.

cd ace_pro/docs

Then, execute the following:

#---------------------------------
# Clean up unused images from docs
#---------------------------------
imagepaths=(images/*.png)
for imagepath in $imagepaths; do
    filename=$(basename -- $imagepath)
    if ! grep -i -q -r --exclude-dir=".git" $filename .; then
        echo $filename
        rm images/$filename
    fi
done