esp-idf/.gitlab/ci/dependencies
Marius Vikhammer 89179dc286 docs: add fast build feature and activate it in CI
Adds feature for skipping include of doxygen headers into sphinx build
when env variable is set.

Builds incomplete docs (no function API documention)
but speeds up building (20min to 1<min).

Add this fast build as the default way of building docs in CI on
non protected branches.
2021-04-28 16:32:35 +08:00
..
README.md ci(docs): improve doc with latest behavior 2021-03-02 16:16:23 +08:00
dependencies.yml docs: add fast build feature and activate it in CI 2021-04-28 16:32:35 +08:00
generate_rules.py ci: add example c3 as a special case for build only 2021-03-29 11:11:02 +08:00

README.md

How the generate_rules.py works

Functionalities

This script can do only two things:

  1. Auto-generate some labels/rules we need and update them in rules.yml
  2. Generate a dependency tree graph

Schema

This file only used basic YAML grammar and has nothing to do with the GitLab version YAML file.

It has five custom keywords:

  • matrix: An array of sub-arrays, used to replicate rules by formatting strings. You can use the format string everywhere, it will be formatted recursively
  • labels: An array of labels.
  • patterns: An array of patterns. Patterns that not included
  • included_in: An array of other rule names. It indicates the labels and patterns will be included in all specified rules as well
  • deploy: An array of strings, used to replicate rules by adding postfix -<item in deploy array>. It indicates the extra label used in rules, which will explain later.

How to use this file to generate rules.yml

Let's take a complicated example to help understand the process

"test-{0}-{1}":
    matrix:
        - [a, b]
        - [c, d]
    labels:
        - "{0}-{1}"
    patterns:
        - "{0}"
        - pattern-not-exist
    included_in:
        - build-{0}
  1. expand the mapping dicts defined by matrix

    After this step, it will turn into 4 dicts:

    key labels patterns included_in
    test-a-c a-c a build-a
    test-a-d a-d a build-a
    test-b-c b-c b build-b
    test-b-d b-d b build-b

    Advanced Usage: You can overwrite a mapping by declaring it again later, For example:

    If we concatenate this part to the previous example,

    # ... The same as the previous example
    
    test-a-c:
        labels:
            - overwrite
    

    rule test-a-c will be turned into:

    key labels
    test-a-c overwrite

    Mappings with the keyword deploy will also replicate by adding a postfix -<item in deploy array> to the mapping key

  2. create rules by included_in

    After this step, it will turn into 6 mapping dicts:

    key labels patterns
    test-a-c a-c a
    test-a-d a-d a
    test-b-c b-c b
    test-b-d b-d b
    build-a a-c, a-d a
    build-b b-c, b-d b
  3. replace the auto-generated region in rules.yml with labels, and rules. Each mapping will generate a rule and all the required labels. patterns are pre-defined in rules.yml and could not be generated automatically. If a mapping is using a pattern undefined, the pattern will be ignored.

    • If a mapping key has postfix -preview, no if-protected-xxx clause will be added
    • else if a mapping key has postfix -production, an if-protected-no_label clause will be added
    • else, an if-protected clause will be added

Graph

All label nodes are in green, pattern nodes are in cyan, rule nodes are in blue

Requirements

There are a few extra dependencies while generating the dependency tree graph, please refer to pygraphviz documentation to install both graphviz and pygraphviz

CLI usage

python generate_rules.py --graph OUTPUT_PATH