diff --git a/docs/GITHUB-ACTIONS-README.md b/docs/GITHUB-ACTIONS-README.md index 93f0069e..c59d66af 100644 --- a/docs/GITHUB-ACTIONS-README.md +++ b/docs/GITHUB-ACTIONS-README.md @@ -1,40 +1,44 @@ -# Guide for using KiBot with Github Actions. +# Guide for using KiBot with GitHub Actions. +Author: @sethkaz -This is a guide for getting started using KiBOT with Github Actions. +This is a guide for getting started using KiBot with GitHub Actions. ## Basics -[Github Actions](https://github.com/actions) is a CI system that runs on Github. It uses [YAML files](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) to define what actions it will take. Unfortunately, some of the links between YAML lines and their associated actions are a bit cryptic. This guide will try to shed light on those cyptic portions. +[GitHub Actions](https://github.com/actions) is a CI system that runs on GitHub. It uses [YAML files](https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html) to define what actions it will take. Unfortunately, some of the links between YAML lines and their associated actions are a bit cryptic. This guide will try to shed light on those cryptic portions. -### Basic github file +### Basic GitHub file + +Must be located at `{repo root}/.github/workflows/{meaningful_name}.yml` -Must be located at `{repo root}/.github/workflows/{meaningful_name}.yml ```yaml name: KiBot_GitHub_Actions # This is a name. It can be anything you want. -on: [push, pull_request] # github triggers for running this. In this example it will run when anything is pushed to github or a pull request is created. +on: [push, pull_request] # GitHub triggers for running this. In this example it will run when anything is pushed to GitHub or a pull request is created. jobs: # List of jobs to be run. Can be used to better organize steps. KiBot-Generation: # This is a name. It can be anything you want. runs-on: ubuntu-latest # Don't change - container: ghcr.io/inti-cmnb/kicad7_auto:latest # Don't Change, except if needing older version of KiCAD. + container: ghcr.io/inti-cmnb/kicad7_auto_full:latest # Don't Change, except if needing older version of KiCad. - steps: + steps: - name: Checkout repo - uses: actions/checkout@v3 # Github built-in repo checkout step. + uses: actions/checkout@v3 # GitHub built-in repo checkout step. # Start of the KiBot steps - name: Run KiBot run: | kibot -e "project_name.kicad_sch" - # Post KiBot steps (Optional). + # Post KiBot steps (Optional). - name: Optionally do other things run: | - ECHO Run bash commands to do things like commiting the files or adding them as artifacts + echo "Run bash commands to do things like committing the files or adding them as artifacts" ``` ### Basic KiBot file -This file will match the syntax and keywords described in the [readme](../README.md). + +This file will match the syntax and keywords described in the [readme](https://kibot.readthedocs.io/en/latest/). + ```yaml kibot: version: 1 @@ -53,9 +57,9 @@ outputs: output: '%p-Schematic.%x' ``` -## Github-specific details +## GitHub-specific details -The `uses: actions/checkout` refers to a specific repo, [Github Actions](https://github.com/actions). +The `uses: actions/checkout` refers to a specific repo, [GitHub Actions](https://github.com/actions). ## KiBot Specific details @@ -63,12 +67,12 @@ The `uses: actions/checkout` refers to a specific repo, [Github Actions](https:/ ## Caveats, Gotchyas, and Pitfalls -1. KiBot requires a `{meaningful_name}.kibot.yaml` file name scheme. While most places use `*.yml` and `*.yaml` interchangeably, it is specific here that `*.kibot.yml` won't work. This is especially odd since github uses `*.yml` and kibot uses `*.yaml`. +1. KiBot requires a `{meaningful_name}.kibot.yaml` file name scheme. While most places use `*.yml` and `*.yaml` interchangeably, it is specific here that `*.kibot.yml` won't work. This is especially odd since GitHub uses `*.yml` and kibot uses `*.yaml`. ## Different ways of doing things -This section will try to describe some different options for doing things within KiBot and Github, and hope to explain pros and cons. +This section will try to describe some different options for doing things within KiBot and GitHub, and hope to explain pros and cons. -TODO: Fill this out. -TODO: (Topic) github artifacts vs exports commited. -TODO: (Topic) When to run KiBOT?? ERC/DRC only vs full outputs. +- TODO: Fill this out. +- TODO: (Topic) GitHub artifacts vs exports committed. +- TODO: (Topic) When to run KiBot?? ERC/DRC only vs full outputs. diff --git a/docs/source/usage_with_ci_cd.rst b/docs/source/usage_with_ci_cd.rst index 7087fd9e..5b9e4ab9 100644 --- a/docs/source/usage_with_ci_cd.rst +++ b/docs/source/usage_with_ci_cd.rst @@ -99,6 +99,14 @@ For more information about the docker images visit `kicad_debian `__ and `kicad_auto `__. +.. index:: + pair: usage; GitHub + +GitHub workflows +~~~~~~~~~~~~~~~~ + +A work-in-progress guide can be found `here `__. + .. index:: pair: usage; GitHub Actions