mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00

History

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
..
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	ci(docs): improve doc with latest behavior	2021-03-02 16:16:23 +08:00

README.md

How the `generate_rules.py` works

Functionalities

This script can do only two things:

Auto-generate some labels/rules we need and update them in rules.yml
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}

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
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
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

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

key	labels
test-a-c	overwrite

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

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