From 64abca726f6843d8c2037d47dde602a285bdadcc Mon Sep 17 00:00:00 2001 From: Daniel Salazar Date: Mon, 13 Mar 2023 16:58:20 -0500 Subject: [PATCH] feat(doc): #940 code sections - Add code sections to all builtins - Use admonitions for notes and warnings Signed-off-by: Daniel Salazar --- docs/src/api/builtins/database.md | 51 ++- docs/src/api/builtins/deploy.md | 339 +++++++------- docs/src/api/builtins/development.md | 132 +++--- docs/src/api/builtins/environment.md | 160 ++++--- docs/src/api/builtins/examples.md | 30 +- docs/src/api/builtins/format.md | 210 +++++---- .../api/builtins/framework-configuration.md | 42 +- docs/src/api/builtins/index.md | 3 +- docs/src/api/builtins/lint.md | 416 +++++++++-------- docs/src/api/builtins/monitoring.md | 90 ++-- docs/src/api/builtins/performance.md | 38 +- docs/src/api/builtins/secrets.md | 433 +++++++++--------- docs/src/api/builtins/security.md | 108 +++-- docs/src/api/builtins/test.md | 94 ++-- docs/src/api/builtins/utilities.md | 72 +-- docs/src/getting-started.md | 8 +- 16 files changed, 1201 insertions(+), 1025 deletions(-) diff --git a/docs/src/api/builtins/database.md b/docs/src/api/builtins/database.md index dd440e58..08d27067 100644 --- a/docs/src/api/builtins/database.md +++ b/docs/src/api/builtins/database.md @@ -23,31 +23,32 @@ Types: [BatchWriteItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html#API_BatchWriteItem_RequestSyntax). This is useful if you want to perform transformations on your data. -Example `makes.nix`: - -```nix -{ projectPath -, ... -}: -{ - dynamoDb = { - usersdb = { - host = "localhost"; - infra = projectPath "/test/database/infra"; - data = [ - projectPath "/test/database/data" - ]; - daemonMode = true; - }; - }; -} -``` - -Example invocation: `$ m . /dyanmoDb/usersdb` - -You can also overwrite the parameters with environment variables. - -Example: `$ DAEMON=false m . /dyanmoDb/usersdb` +Example: + +=== "makes.nix" + + ```nix + { projectPath, + ... + }: { + dynamoDb = { + usersdb = { + host = "localhost"; + infra = projectPath "/test/database/infra"; + data = [ + projectPath "/test/database/data" + ]; + daemonMode = true; + }; + }; + } + ``` + +=== "Invocation" + + ``` bash + DAEMON=false m . /dyanmoDb/usersdb + ``` The following variables are available: diff --git a/docs/src/api/builtins/deploy.md b/docs/src/api/builtins/deploy.md index 6d681cce..50f5db29 100644 --- a/docs/src/api/builtins/deploy.md +++ b/docs/src/api/builtins/deploy.md @@ -1,6 +1,6 @@ ## computeOnAwsBatch -Submit a job to an [AWS BATCH](https://aws.amazon.com/batch/) queue. +Submit a job to a [AWS BATCH](https://aws.amazon.com/batch/) queue. Types: @@ -33,30 +33,6 @@ Types: In general an Batch job definition is required in order to specify which container image our job is going to run on. - - The most basic Batch job definition - to run a Makes job is (in Terraform syntax): - - ```tf - resource "aws_batch_job_definition" "makes" { - name = "makes" - type = "container" - container_properties = jsonencode({ - # This image cannot be parametrized later. - # - # If you need to run jobs on different container images, - # simply create many `aws_batch_job_definition`s - image = "ghcr.io/fluidattacks/makes:23.04" - - # Below arguments can be parametrized later, - # but they are required for the job definition to be created - # so let's put some dummy values here - memory = 512 - vcpus = 1 - }) - } - ``` - - environment (`listOf str`): Optional. Name of the environment variables whose names and values should be copied from the machine running Makes @@ -93,38 +69,42 @@ Types: - vcpus (`ints.positive`): Amount of virtual CPUs that is reserved for the job. -Example `makes.nix`: - -```nix -{ outputs -, ... -}: -{ - computeOnAwsBatch = { - helloWorld = { - attempts = 1; - attemptDurationSeconds = 43200; - command = [ "m" "github:fluidattacks/makes@main" "/helloWorld" ]; - definition = "makes"; - environment = [ "ENV_VAR_FOR_WHATEVER" ]; - memory = 1800; - queue = "ec2_spot"; - setup = [ - # Use default authentication for AWS - outputs."/secretsForAwsFromEnv/__default__" - ]; - tags = { - "Management:Product" = "awesome_app"; - } - vcpus = 1; - }; - }; -} -``` - -Example invocation: `$ m . /computeOnAwsBatch/helloWorld` - -Example invocation: `$ m . /computeOnAwsBatch/helloWorld 1 2 3` +Example: + +=== "makes.nix" + + ```nix + { + outputs, + ... + }: { + computeOnAwsBatch = { + helloWorld = { + attempts = 1; + attemptDurationSeconds = 43200; + command = [ "m" "github:fluidattacks/makes@main" "/helloWorld" ]; + definition = "makes"; + environment = [ "ENV_VAR_FOR_WHATEVER" ]; + memory = 1800; + queue = "ec2_spot"; + setup = [ + # Use default authentication for AWS + outputs."/secretsForAwsFromEnv/__default__" + ]; + tags = { + "Management:Product" = "awesome_app"; + } + vcpus = 1; + }; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /computeOnAwsBatch/helloWorld 1 2 3 + ``` Note that positional arguments (`[ "1" "2" "3" ]` in this case) will be appended to the end of `command` @@ -170,59 +150,74 @@ Types: - tag (`str`): The tag under which the image will be stored in the registry. -Example `makes.nix`: - -```nix -{ inputs -, outputs -, ... -}: -{ - inputs = { - nixpkgs = fetchNixpkgs { - rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; - sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; - }; - }; - - deployContainerImage = { - images = { - nginxDockerHub = { - credentials = { - token = "DOCKER_HUB_PASS"; - user = "DOCKER_HUB_USER"; - }; - src = inputs.nixpkgs.dockerTools.examples.nginx; - registry = "docker.io"; - tag = "fluidattacks/nginx:latest"; - }; - redisGitHub = { - credentials = { - token = "GITHUB_TOKEN"; - user = "GITHUB_ACTOR"; +Example: + +=== "makes.nix" + + ```nix + { + inputs, + outputs, + ... + }: { + inputs = { + nixpkgs = fetchNixpkgs { + rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; + sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; }; - src = inputs.nixpkgs.dockerTools.examples.redis; - registry = "ghcr.io"; - tag = "fluidattacks/redis:$(date +%Y.%m)"; # Tag from command }; - makesGitLab = { - credentials = { - token = "CI_REGISTRY_PASSWORD"; - user = "CI_REGISTRY_USER"; + + deployContainerImage = { + images = { + nginxDockerHub = { + credentials = { + token = "DOCKER_HUB_PASS"; + user = "DOCKER_HUB_USER"; + }; + src = inputs.nixpkgs.dockerTools.examples.nginx; + registry = "docker.io"; + tag = "fluidattacks/nginx:latest"; + }; + redisGitHub = { + credentials = { + token = "GITHUB_TOKEN"; + user = "GITHUB_ACTOR"; + }; + src = inputs.nixpkgs.dockerTools.examples.redis; + registry = "ghcr.io"; + tag = "fluidattacks/redis:$(date +%Y.%m)"; # Tag from command + }; + makesGitLab = { + credentials = { + token = "CI_REGISTRY_PASSWORD"; + user = "CI_REGISTRY_USER"; + }; + src = outputs."/containerImage"; + registry = "registry.gitlab.com"; + tag = "fluidattacks/product/makes:$MY_VAR"; # Tag from env var + }; }; - src = outputs."/containerImage"; - registry = "registry.gitlab.com"; - tag = "fluidattacks/product/makes:$MY_VAR"; # Tag from env var }; - }; - }; -``` + } + ``` -Example invocation: `$ DOCKER_HUB_USER=user DOCKER_HUB_PASS=123 m . /deployContainerImage/nginxDockerHub` +=== "Invocation DockerHub" -Example invocation: `$ GITHUB_ACTOR=user GITHUB_TOKEN=123 m . /deployContainerImage/makesLatest` + ```bash + DOCKER_HUB_USER=user DOCKER_HUB_PASS=123 m . /deployContainerImage/nginxDockerHub + ``` + +=== "Invocation GitHub" -Example invocation: `$ CI_REGISTRY_USER=user CI_REGISTRY_PASSWORD=123 m . /deployContainerImage/makesGitLab` + ```bash + GITHUB_ACTOR=user GITHUB_TOKEN=123 m . /deployContainerImage/makesLatest + ``` + +=== "Invocation GitLab" + + ```bash + CI_REGISTRY_USER=user CI_REGISTRY_PASSWORD=123 m . /deployContainerImage/makesGitLab + ``` ## deployTerraform @@ -248,28 +243,32 @@ Types: - version (`enum [ "0.14" "0.15" "1.0" ]`): Terraform version your module is built with. -Example `makes.nix`: - -```nix -{ - deployTerraform = { - modules = { - module1 = { - src = "/my/module1"; - version = "0.14"; - }; - module2 = { - src = "/my/module2"; - version = "1.0"; +Example: + +=== "makes.nix" + + ```nix + { + deployTerraform = { + modules = { + module1 = { + src = "/my/module1"; + version = "0.14"; + }; + module2 = { + src = "/my/module2"; + version = "1.0"; + }; + }; }; - }; - }; -} -``` + } + ``` -Example invocation: `$ m . /deployTerraform/module1` +=== "Invocation" -Example invocation: `$ m . /deployTerraform/module2` + ```bash + m . /deployTerraform/module1 + ``` ## taintTerraform @@ -300,23 +299,29 @@ Types: - version (`enum [ "0.14" "0.15" "1.0" ]`): Terraform version your module is built with. -Example `makes.nix`: +Example: + +=== "makes.nix" -```nix -{ - taintTerraform = { - modules = { - module = { - resources = [ "null_resource.example" ]; - src = "/test/terraform/module"; - version = "0.14"; + ```nix + { + taintTerraform = { + modules = { + module = { + resources = [ "null_resource.example" ]; + src = "/test/terraform/module"; + version = "0.14"; + }; + }; }; - }; - }; -} -``` + } + ``` -Example invocation: `$ m . /taintTerraform/module` +=== "Invocation" + + ```bash + m . /taintTerraform/module + ``` ## deployNomad @@ -360,38 +365,42 @@ Types: Nomad version your jobs are built with. Defaults to `"1.1"`. -Example `makes.nix`: - -```nix -{ - deployNomad = { - jobs = { - job1 = { - src = ./my/job1.hcl; - namespace = "default"; - }; - job2 = { - src = ./my/job2.json; - namespace = "default"; - }; - }; - namespaces = { - dev.jobs = { - job1 = ./my/dev/job1.hcl; - job2 = ./my/dev/job2.json; - }; - staging.jobs = { - job1 = ./my/staging/job1.hcl; - job2 = ./my/staging/job2.json; +Example: + +=== "makes.nix" + + ```nix + { + deployNomad = { + jobs = { + job1 = { + src = ./my/job1.hcl; + namespace = "default"; + }; + job2 = { + src = ./my/job2.json; + namespace = "default"; + }; + }; + namespaces = { + dev.jobs = { + job1 = ./my/dev/job1.hcl; + job2 = ./my/dev/job2.json; + }; + staging.jobs = { + job1 = ./my/staging/job1.hcl; + job2 = ./my/staging/job2.json; + }; + }; }; - }; - }; -} -``` + } + ``` -Example invocation: `$ m . /deployNomad/default/job1` +=== "Invocation" -Example invocation: `$ m . /deployNomad/staging/job2` + ```bash + m . /deployNomad/default/job1 + ``` [makes_environment]: ./environment.md [makes_secrets]: ./secrets.md diff --git a/docs/src/api/builtins/development.md b/docs/src/api/builtins/development.md index b3576fa9..b5a7b8d0 100644 --- a/docs/src/api/builtins/development.md +++ b/docs/src/api/builtins/development.md @@ -12,92 +12,96 @@ Types: Mapping of environment name to searchPaths. Defaults to `{ }`. -Example `makes.nix`: - -```nix -{ inputs -, ... -}: -{ - inputs = { - nixpkgs = fetchNixpkgs { - rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; - sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; - }; - }; - - dev = { - example = { - # A development environment with `hello` package - bin = [ - inputs.nixpkgs.hello - ]; - }; - }; -} -``` - -Example invocation: `$ m . /dev/example` +Example: + +=== "makes.nix" + + ```nix + { + inputs, + ... + }: { + inputs = { + nixpkgs = fetchNixpkgs { + rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; + sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; + }; + }; + + dev = { + example = { + # A development environment with `hello` package + bin = [ + inputs.nixpkgs.hello + ]; + }; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /dev/example + ``` --- -Example usage with direnv -on remote projects: +Example usage with direnv: -```bash -$ cat /path/to/some/dir/.envrc +=== "On a remote project" - source "$(m github:fluidattacks/makes@main /dev/example)/template" + ```bash + $ cat /path/to/some/dir/.envrc -# Now every time you enter /path/to/some/dir -# the shell will automatically load the environment -$ cd /path/to/some/dir + source "$(m github:fluidattacks/makes@main /dev/example)/template" - direnv: loading /path/to/some/dir/.envrc - direnv: export ~PATH + # Now every time you enter /path/to/some/dir + # the shell will automatically load the environment + $ cd /path/to/some/dir -/path/to/some/dir $ hello + direnv: loading /path/to/some/dir/.envrc + direnv: export ~PATH - Hello, world! + /path/to/some/dir $ hello -# If you exit the directory, the development environment is unloaded -/path/to/some/dir $ cd .. + Hello, world! - direnv: unloading + # If you exit the directory, the development environment is unloaded + /path/to/some/dir $ cd .. -/path/to/some $ hello + direnv: unloading - hello: command not found -``` + /path/to/some $ hello ---- + hello: command not found + ``` -Example usage with direnv -on a local project: +=== "On a local project" -```bash -$ cat /path/to/some/dir/.envrc + ```bash + $ cat /path/to/some/dir/.envrc - cd /path/to/my/project - source "$(m . /dev/example)/template" + cd /path/to/my/project + source "$(m . /dev/example)/template" -# Now every time you enter /path/to/some/dir -# the shell will automatically load the environment -$ cd /path/to/some/dir + # Now every time you enter /path/to/some/dir + # the shell will automatically load the environment + $ cd /path/to/some/dir - direnv: loading /path/to/some/dir/.envrc - direnv: export ~PATH + direnv: loading /path/to/some/dir/.envrc + direnv: export ~PATH -/path/to/some/dir $ hello + /path/to/some/dir $ hello - Hello, world! + Hello, world! -# If you exit the directory, the development environment is unloaded -/path/to/some/dir $ cd .. + # If you exit the directory, the development environment is unloaded + /path/to/some/dir $ cd .. - direnv: unloading + direnv: unloading -/path/to/some $ hello + /path/to/some $ hello - hello: command not found -``` + hello: command not found + ``` diff --git a/docs/src/api/builtins/environment.md b/docs/src/api/builtins/environment.md index 92145599..b3aaa018 100644 --- a/docs/src/api/builtins/environment.md +++ b/docs/src/api/builtins/environment.md @@ -1,7 +1,9 @@ ## envVars -:warning: Do not propagate sensitive information here, it's not safe. -Use [Makes Secrets][makes_secrets] instead. +???+ warning + + Do not propagate sensitive information here, it's not safe. + Use [Makes Secrets][makes_secrets] instead. Allows you to map environment variables from a name to a value. @@ -10,43 +12,49 @@ Types: - envVars (`attrsOf (attrsOf str)`): Optional. Defaults to `{ }`. -Example `makes.nix`: - -```nix -{ inputs -, outputs -, ... -}: -{ - envVars = { - example = { - # Equals to: export awsDefaultRegion=us-east-1 - awsDefaultRegion = "us-east-1"; - }; - otherExample = { - # Equals to: export license=/nix/store/...-my-license - license = outputs."/MyLicense"; - # Equals to: export bash=/nix/store/...-bash - bash = inputs.nixpkgs.bash; - }; - }; - inputs = { - nixpkgs = fetchNixpkgs { - rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; - sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; - }; - }; -} -``` - -Example invocation: `$ m . /envVars/example` - -Example invocation: `$ m . /envVars/otherExample` +Example: + +=== "makes.nix" + + ```nix + { + inputs, + outputs, + ... + }: { + envVars = { + example = { + # Equals to: export awsDefaultRegion=us-east-1 + awsDefaultRegion = "us-east-1"; + }; + otherExample = { + # Equals to: export license=/nix/store/...-my-license + license = outputs."/MyLicense"; + # Equals to: export bash=/nix/store/...-bash + bash = inputs.nixpkgs.bash; + }; + }; + inputs = { + nixpkgs = fetchNixpkgs { + rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; + sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; + }; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /envVars/example + ``` ## envVarsForTerraform -:warning: Do not propagate sensitive information here, it's not safe. -Use [Makes Secrets][makes_secrets] instead. +???+ warning + + Do not propagate sensitive information here, it's not safe. + Use [Makes Secrets][makes_secrets] instead. Allows you to map Terraform variables from a name to a value. @@ -55,43 +63,47 @@ Types: - envVarsForTerraform (`attrsOf (attrsOf str)`): Optional. Defaults to `{ }`. -Example `makes.nix`: - -```nix -{ inputs -, outputs -, ... -}: -{ - envVarsForTerraform = { - example = { - # Equals to: export TF_VAR_awsDefaultRegion=us-east-1 - awsDefaultRegion = "us-east-1"; - }; - otherExample = { - # Equals to: export TF_VAR_license=/nix/store/...-my-license - license = outputs."/MyLicense"; - # Equals to: export TF_VAR_bash=/nix/store/...-bash - bash = inputs.nixpkgs.bash; - }; - }; - inputs = { - nixpkgs = fetchNixpkgs { - rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; - sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; - }; - }; -} -``` - -Example `main.tf`: - -```tf -variable "awsDefaultRegion" {} -``` - -Example invocation: `$ m . /envVarsForTerraform/example` - -Example invocation: `$ m . /envVarsForTerraform/otherExample` +Example: + +=== "makes.nix" + + ```nix + { + inputs, + outputs, + ... + }: { + envVarsForTerraform = { + example = { + # Equals to: export TF_VAR_awsDefaultRegion=us-east-1 + awsDefaultRegion = "us-east-1"; + }; + otherExample = { + # Equals to: export TF_VAR_license=/nix/store/...-my-license + license = outputs."/MyLicense"; + # Equals to: export TF_VAR_bash=/nix/store/...-bash + bash = inputs.nixpkgs.bash; + }; + }; + inputs = { + nixpkgs = fetchNixpkgs { + rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; + sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; + }; + }; + } + ``` + +=== "main.tf" + + ```tf + variable "awsDefaultRegion" {} + ``` + +=== "Invocation" + + ```bash + m . /envVarsForTerraform/example + ``` [makes_secrets]: ./secrets.md diff --git a/docs/src/api/builtins/examples.md b/docs/src/api/builtins/examples.md index 9714009d..e2a1f0c7 100644 --- a/docs/src/api/builtins/examples.md +++ b/docs/src/api/builtins/examples.md @@ -10,15 +10,21 @@ Types: - name (`string`): Name of the user we should greet. -Example `makes.nix`: - -```nix -{ - helloWorld = { - enable = true; - name = "Jane Doe"; - }; -} -``` - -Example invocation: `$ m . /helloWorld 1 2 3` +Example: + +=== "makes.nix" + + ```nix + { + helloWorld = { + enable = true; + name = "Jane Doe"; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /helloWorld 1 2 3 + ``` diff --git a/docs/src/api/builtins/format.md b/docs/src/api/builtins/format.md index b407baf3..96304921 100644 --- a/docs/src/api/builtins/format.md +++ b/docs/src/api/builtins/format.md @@ -14,26 +14,34 @@ Types: Files or directories (relative to the project) to format. Defaults to the entire project. -Example `makes.nix`: - -```nix -{ - formatBash = { - enable = true; - targets = [ - "/" # Entire project - "/file.sh" # A file - "/directory" # A directory within the project - ]; - }; -} -``` - -Example invocation: `$ m . /formatBash` +Example: + +=== "makes.nix" + + ```nix + { + formatBash = { + enable = true; + targets = [ + "/" # Entire project + "/file.sh" # A file + "/directory" # A directory within the project + ]; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /formatBash + ``` ## formatMarkdown -:warning: This function is only available on Linux at the moment. +???+ warning + + This function is only available on Linux at the moment. Ensure that Markdown code is formatted according to [doctoc](https://github.com/thlorenz/doctoc). @@ -49,19 +57,25 @@ Types: - targets (`listOf str`): Files (relative to the project) to format. -Example `makes.nix`: +Example: -```nix -{ - formatMarkdown = { - enable = true; - doctocArgs = [ "--title" "# Contents" ]; - targets = [ "/README.md" ]; - }; -} -``` +=== "makes.nix" -Example invocation: `$ m . /formatMarkdown` + ```nix + { + formatMarkdown = { + enable = true; + doctocArgs = [ "--title" "# Contents" ]; + targets = [ "/README.md" ]; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /formatMarkdown + ``` ## formatNix @@ -77,22 +91,28 @@ Types: Files or directories (relative to the project) to format. Defaults to the entire project. -Example `makes.nix`: +Example: + +=== "makes.nix" + + ```nix + { + formatNix = { + enable = true; + targets = [ + "/" # Entire project + "/file.nix" # A file + "/directory" # A directory within the project + ]; + }; + } + ``` -```nix -{ - formatNix = { - enable = true; - targets = [ - "/" # Entire project - "/file.nix" # A file - "/directory" # A directory within the project - ]; - }; -} -``` +=== "Invocation" -Example invocation: `$ m . /formatNix` + ```bash + m . /formatNix + ``` ## formatPython @@ -109,22 +129,28 @@ Types: Files or directories (relative to the project) to format. Defaults to the entire project. -Example `makes.nix`: +Example: -```nix -{ - formatPython = { - enable = true; - targets = [ - "/" # Entire project - "/file.py" # A file - "/directory" # A directory within the project - ]; - }; -} -``` +=== "makes.nix" -Example invocation: `$ m . /formatPython` + ```nix + { + formatPython = { + enable = true; + targets = [ + "/" # Entire project + "/file.py" # A file + "/directory" # A directory within the project + ]; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /formatPython + ``` ## formatTerraform @@ -140,22 +166,28 @@ Types: Files or directories (relative to the project) to format. Defaults to the entire project. -Example `makes.nix`: +Example: + +=== "makes.nix" + + ```nix + { + formatTerraform = { + enable = true; + targets = [ + "/" # Entire project + "/main.tf" # A file + "/terraform/module" # A directory within the project + ]; + }; + } + ``` -```nix -{ - formatTerraform = { - enable = true; - targets = [ - "/" # Entire project - "/main.tf" # A file - "/terraform/module" # A directory within the project - ]; - }; -} -``` +=== "Invocation" -Example invocation: `$ m . /formatTerraform` + ```bash + m . /formatTerraform + ``` ## formatYaml @@ -171,19 +203,25 @@ Types: Files or directories (relative to the project) to format. Defaults to the entire project. -Example `makes.nix`: - -```nix -{ - formatYaml = { - enable = true; - targets = [ - "/" # Entire project - "/main.yaml" # A file - "/yamls/" # A directory within the project - ]; - }; -} -``` - -Example invocation: `$ m . /formatYaml` +Example: + +=== "makes.nix" + + ```nix + { + formatYaml = { + enable = true; + targets = [ + "/" # Entire project + "/main.yaml" # A file + "/yamls/" # A directory within the project + ]; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /formatYaml + ``` diff --git a/docs/src/api/builtins/framework-configuration.md b/docs/src/api/builtins/framework-configuration.md index ec9d3676..41234421 100644 --- a/docs/src/api/builtins/framework-configuration.md +++ b/docs/src/api/builtins/framework-configuration.md @@ -17,23 +17,25 @@ Types: - inputs (`attrOf anything`): Optional. Defaults to `{ }`. -Example `makes.nix`: - -```nix -{ fetchNixpkgs -, fetchUrl -, ... -}: -{ - inputs = { - license = fetchUrl { - rev = "https://raw.githubusercontent.com/fluidattacks/makes/1a595d8642ba98252cff7de3909fb879c54f8e59/LICENSE"; - sha256 = "11311l1apb1xvx2j033zlvbyb3gsqblyxq415qwdsd0db1hlwd52"; - }; - nixpkgs = fetchNixpkgs { - rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; - sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; - }; - }; -} -``` +Example: + +=== "makes.nix" + + ```nix + { + fetchNixpkgs, + fetchUrl, + ... + }: { + inputs = { + license = fetchUrl { + rev = "https://raw.githubusercontent.com/fluidattacks/makes/1a595d8642ba98252cff7de3909fb879c54f8e59/LICENSE"; + sha256 = "11311l1apb1xvx2j033zlvbyb3gsqblyxq415qwdsd0db1hlwd52"; + }; + nixpkgs = fetchNixpkgs { + rev = "f88fc7a04249cf230377dd11e04bf125d45e9abe"; + sha256 = "1dkwcsgwyi76s1dqbrxll83a232h9ljwn4cps88w9fam68rf8qv3"; + }; + }; + } + ``` diff --git a/docs/src/api/builtins/index.md b/docs/src/api/builtins/index.md index 39437624..fbc60a91 100644 --- a/docs/src/api/builtins/index.md +++ b/docs/src/api/builtins/index.md @@ -25,8 +25,7 @@ A `makes.nix` file should be: { argA , argB , ... - }: - { + }: { configOption1 = { # ... }; diff --git a/docs/src/api/builtins/lint.md b/docs/src/api/builtins/lint.md index 8b75c3f2..9f3d71e7 100644 --- a/docs/src/api/builtins/lint.md +++ b/docs/src/api/builtins/lint.md @@ -14,22 +14,28 @@ Types: Files or directories (relative to the project) to lint. Defaults to the entire project. -Example `makes.nix`: - -```nix -{ - lintBash = { - enable = true; - targets = [ - "/" # Entire project - "/file.sh" # A file - "/directory" # A directory within the project - ]; - }; -} -``` - -Example invocation: `$ m . /lintBash` +Example: + +=== "makes.nix" + + ```nix + { + lintBash = { + enable = true; + targets = [ + "/" # Entire project + "/file.sh" # A file + "/directory" # A directory within the project + ]; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /lintBash + ``` ## lintClojure @@ -41,29 +47,35 @@ Types: Mapping of custom names to lists of paths (relative to the project) to lint. Defaults to `{ }`. -Example `makes.nix`: +Example: + +=== "makes.nix" -```nix -{ - lintClojure = { - example1 = [ - "/" # Entire project - "/file.clj" # A file - ]; - example2 = [ - "/directory" # A directory within the project - ]; - }; -} -``` + ```nix + { + lintClojure = { + example1 = [ + "/" # Entire project + "/file.clj" # A file + ]; + example2 = [ + "/directory" # A directory within the project + ]; + }; + } + ``` -Example invocation: `$ m . /lintClojure/example1` +=== "Invocation" -Example invocation: `$ m . /lintClojure/example2` + ```bash + m . /lintClojure/example1` + ``` ## lintGitCommitMsg -:warning: This function is only available on Linux at the moment. +???+ warning + + This function is only available on Linux at the moment. It creates a commit diff between you current branch @@ -88,21 +100,27 @@ Types: Defaults to [parser.js](/src/evaluator/modules/lint-git-commit-msg/parser.js). -Example `makes.nix`: +Example: + +=== "makes.nix" -```nix -{ - lintGitCommitMsg = { - enable = true; - branch = "my-branch-name"; - # If you want to use custom configs or parsers you can do it like this: - # config = "/src/config/config.js"; - # parser = "/src/config/parser.js"; - }; -} -``` + ```nix + { + lintGitCommitMsg = { + enable = true; + branch = "my-branch-name"; + # If you want to use custom configs or parsers you can do it like this: + # config = "/src/config/config.js"; + # parser = "/src/config/parser.js"; + }; + } + ``` + +=== "Invocation" -Example invocation: `$ m . /lintGitCommitMsg` + ```bash + m . /lintGitCommitMsg + ``` ## lintGitMailMap @@ -116,17 +134,23 @@ Types: - enable (`boolean`): Optional. Defaults to `false`. -Example `makes.nix`: +Example: + +=== "makes.nix" + + ```nix + { + lintGitMailMap = { + enable = true; + }; + } + ``` -```nix -{ - lintGitMailMap = { - enable = true; - }; -} -``` +=== "Invocation" -Example invocation: `$ m . /lintGitMailMap` + ```bash + m . /lintGitMailMap + ``` ## lintMarkdown @@ -144,26 +168,30 @@ Types: - targets (`listOf str`): Required. paths to lint with `config`. -Example `makes.nix`: - -```nix -{ - lintMarkdown = { - all = { - # You can pass custom configs like this: - # config = "/src/config/markdown.rb"; - targets = [ "/" ]; - }; - others = { - targets = [ "/others" ]; - }; - }; -} -``` +Example: + +=== "makes.nix" + + ```nix + { + lintMarkdown = { + all = { + # You can pass custom configs like this: + # config = "/src/config/markdown.rb"; + targets = [ "/" ]; + }; + others = { + targets = [ "/others" ]; + }; + }; + } + ``` -Example invocation: `$ m . /lintMarkdown/all` +=== "Invocation" -Example invocation: `$ m . /lintMarkdown/others` + ```bash + m . /lintMarkdown/all + ``` ## lintNix @@ -178,22 +206,28 @@ Types: Files or directories (relative to the project) to lint. Defaults to the entire project. -Example `makes.nix`: +Example: -```nix -{ - lintNix = { - enable = true; - targets = [ - "/" # Entire project - "/file.nix" # A file - "/directory" # A directory within the project - ]; - }; -} -``` +=== "makes.nix" -Example invocation: `$ m . /lintNix` + ```nix + { + lintNix = { + enable = true; + targets = [ + "/" # Entire project + "/file.nix" # A file + "/directory" # A directory within the project + ]; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /lintNix + ``` ## lintPython @@ -238,38 +272,46 @@ Types: - src (`str`): Path to the package/module. -Example `makes.nix`: - -```nix -{ - lintPython = { - dirsOfModules = { - makes = { - python = "3.8"; - src = "/src/cli"; - }; - }; - imports = { - cli = { - config = "/src/cli/imports.cfg"; - src = "/src/cli"; +Example: + +=== "makes.nix" + + ```nix + { + lintPython = { + dirsOfModules = { + makes = { + python = "3.8"; + src = "/src/cli"; + }; + }; + imports = { + cli = { + config = "/src/cli/imports.cfg"; + src = "/src/cli"; + }; + }; + modules = { + cliMain = { + python = "3.8"; + src = "/src/cli/main"; + }; + }; }; - }; - modules = { - cliMain = { - python = "3.8"; - src = "/src/cli/main"; - }; - }; - }; -} -``` + } + ``` + +=== "Invocation dirOfModules" -Example invocation: `$ m . /lintPython/dirOfModules/makes` + ```bash + m . /lintPython/dirOfModules/makes/main + ``` -Example invocation: `$ m . /lintPython/dirOfModules/makes/main` +=== "Invocation module" -Example invocation: `$ m . /lintPython/module/cliMain` + ```bash + m . /lintPython/module/cliMain + ``` ## lintTerraform @@ -297,30 +339,34 @@ Types: - version (`enum [ "0.14" "0.15" "1.0" ]`): Terraform version your module is built with. -Example `makes.nix`: - -```nix -{ - lintTerraform = { - # You can use a custom configuration like this: - # config = "/src/config/tflint.hcl"; - modules = { - module1 = { - src = "/my/module1"; - version = "0.14"; +Example: + +=== "makes.nix" + + ```nix + { + lintTerraform = { + # You can use a custom configuration like this: + # config = "/src/config/tflint.hcl"; + modules = { + module1 = { + src = "/my/module1"; + version = "0.14"; + }; + module2 = { + src = "/my/module2"; + version = "0.15"; + }; + }; }; - module2 = { - src = "/my/module2"; - version = "0.15"; - }; - }; - }; -} -``` + } + ``` -Example invocation: `$ m . /lintTerraform/module1` +=== "Invocation" -Example invocation: `$ m . /lintTerraform/module2` + ```bash + m . /lintTerraform/module1 + ``` ## lintWithAjv @@ -342,32 +388,36 @@ Types: YAML or JSON data files to lint with `schema`. -Example `makes.nix`: - -```nix -{ - lintWithAjv = { - users = { - schema = "/users/schema.json"; - targets = [ - "/users/data1.json" - "/users/data.yaml" - ]; - }; - colors = { - schema = "/colors/schema.json"; - targets = [ - "/colors/data1.json" - "/colors/data2.yaml" - ]; - }; - }; -} -``` - -Example invocation: `$ m . /lintWithAjv/users` - -Example invocation: `$ m . /lintWithAjv/colors` +Example: + +=== "makes.nix" + + ```nix + { + lintWithAjv = { + users = { + schema = "/users/schema.json"; + targets = [ + "/users/data1.json" + "/users/data.yaml" + ]; + }; + colors = { + schema = "/colors/schema.json"; + targets = [ + "/colors/data1.json" + "/colors/data2.yaml" + ]; + }; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /lintWithAjv/users + ``` ## lintWithLizard @@ -381,22 +431,26 @@ Types: Mapping of custom names to lists of paths (relative to the project) to lint. Defaults to `{ }`. -Example `makes.nix`: - -```nix -{ - lintWithLizard = { - example1 = [ - "/" # Entire project - "/file.py" # A file - ]; - example2 = [ - "/directory" # A directory within the project - ]; - }; -} -``` - -Example invocation: `$ m . /lintWithLizard/example1` - -Example invocation: `$ m . /lintWithLizard/example2` +Example: + +=== "makes.nix" + + ```nix + { + lintWithLizard = { + example1 = [ + "/" # Entire project + "/file.py" # A file + ]; + example2 = [ + "/directory" # A directory within the project + ]; + }; + } + ``` + +=== "Invocation" + + ```bash + $ m . /lintWithLizard/example1 + ``` diff --git a/docs/src/api/builtins/monitoring.md b/docs/src/api/builtins/monitoring.md index ab0f3ced..66c3d33e 100644 --- a/docs/src/api/builtins/monitoring.md +++ b/docs/src/api/builtins/monitoring.md @@ -44,50 +44,54 @@ Types: - target (`str`): Mandatory, this is the repository url where you want to run scorecard. -Example usage: +Example: -```nix -{ - calculateScorecard = { - checks = [ "SAST" ]; - enable = true; - format = "json" - target = "github.com/fluidattacks/makes"; - }; -} -``` +=== "makes.nix" -Example output: + ```nix + { + calculateScorecard = { + checks = [ "SAST" ]; + enable = true; + format = "json" + target = "github.com/fluidattacks/makes"; + }; + } + ``` -```bash - [INFO] Calculating Scorecard - { - "date": "2022-02-28", - "repo": { - "name": "github.com/fluidattacks/makes", - "commit": "739dcdc0513c29de67406e543e1392ea194b3452" - }, - "scorecard": { - "version": "4.0.1", - "commit": "c60b66bbc8b85286416d6ab9ae9324a095e66c94" - }, - "score": 5, - "checks": [ - { - "details": [ - "Warn: 16 commits out of 30 are checked with a SAST tool", - "Warn: CodeQL tool not detected" - ], - "score": 5, - "reason": "SAST tool is not run on all commits -- score normalized to 5", - "name": "SAST", - "documentation": { - "url": "https://github.com/ossf/scorecard/blob/c60b66bbc8b85286416d6ab9ae9324a095e66c94/docs/checks.md#sast", - "short": "Determines if the project uses static code analysis." +=== "Invocation" + + ```bash + m . /calculateScorecard + ... + [INFO] Calculating Scorecard + { + "date": "2022-02-28", + "repo": { + "name": "github.com/fluidattacks/makes", + "commit": "739dcdc0513c29de67406e543e1392ea194b3452" + }, + "scorecard": { + "version": "4.0.1", + "commit": "c60b66bbc8b85286416d6ab9ae9324a095e66c94" + }, + "score": 5, + "checks": [ + { + "details": [ + "Warn: 16 commits out of 30 are checked with a SAST tool", + "Warn: CodeQL tool not detected" + ], + "score": 5, + "reason": "SAST tool is not run on all commits -- score normalized to 5", + "name": "SAST", + "documentation": { + "url": "https://github.com/ossf/scorecard/blob/c60b66bbc8b85286416d6ab9ae9324a095e66c94/docs/checks.md#sast", + "short": "Determines if the project uses static code analysis." + } } - } - ], - "metadata": null - } - [INFO] Aggregate score: 5 -``` + ], + "metadata": null + } + [INFO] Aggregate score: 5 + ``` diff --git a/docs/src/api/builtins/performance.md b/docs/src/api/builtins/performance.md index ffba9f00..ea3b7475 100644 --- a/docs/src/api/builtins/performance.md +++ b/docs/src/api/builtins/performance.md @@ -30,22 +30,24 @@ Required environment variables: - For private caches: If not set the cache won't be read, nor written to. -Example `makes.nix`: - -```nix -{ - cache = { - readNixos = true; - extra = { - main = { - enable = true; - pubKey = "makes.cachix.org-1:zO7UjWLTRR8Vfzkgsu1PESjmb6ymy1e4OE9YfMmCQR4="; - token = "CACHIX_AUTH_TOKEN"; - type = "nixos"; - url = "https://makes.cachix.org?priority=2"; - write = true; +Example: + +=== "makes.nix" + + ```nix + { + cache = { + readNixos = true; + extra = { + main = { + enable = true; + pubKey = "makes.cachix.org-1:zO7UjWLTRR8Vfzkgsu1PESjmb6ymy1e4OE9YfMmCQR4="; + token = "CACHIX_AUTH_TOKEN"; + type = "nixos"; + url = "https://makes.cachix.org?priority=2"; + write = true; + }; + }; }; - }; - }; -} -``` + } + ``` diff --git a/docs/src/api/builtins/secrets.md b/docs/src/api/builtins/secrets.md index 8d960a7c..9a34533a 100644 --- a/docs/src/api/builtins/secrets.md +++ b/docs/src/api/builtins/secrets.md @@ -43,45 +43,47 @@ Always available outputs: - secretAccessKey: "AWS_SECRET_ACCESS_KEY"; - sessionToken: "AWS_SESSION_TOKEN"; -Example `makes.nix`: - -```nix -{ outputs -, lintTerraform -, secretsForAwsFromEnv -, ... -}: -{ - secretsForAwsFromEnv = { - makesDev = { - accessKeyId = "ENV_VAR_FOR_MAKES_DEV_AWS_ACCESS_KEY_ID"; - secretAccessKey = "ENV_VAR_FOR_MAKES_DEV_AWS_SECRET_ACCESS_KEY"; - }; - makesProd = { - accessKeyId = "ENV_VAR_FOR_MAKES_PROD_AWS_ACCESS_KEY_ID"; - secretAccessKey = "ENV_VAR_FOR_MAKES_PROD_AWS_SECRET_ACCESS_KEY"; - }; - }; - lintTerraform = { - modules = { - moduleDev = { - setup = [ - outputs."/secretsForAwsFromEnv/makesDev" - ]; - src = "/my/module1"; - version = "0.14"; +Example: + +=== "makes.nix" + + ```nix + { + outputs, + lintTerraform, + secretsForAwsFromEnv, + ... + }: { + secretsForAwsFromEnv = { + makesDev = { + accessKeyId = "ENV_VAR_FOR_MAKES_DEV_AWS_ACCESS_KEY_ID"; + secretAccessKey = "ENV_VAR_FOR_MAKES_DEV_AWS_SECRET_ACCESS_KEY"; + }; + makesProd = { + accessKeyId = "ENV_VAR_FOR_MAKES_PROD_AWS_ACCESS_KEY_ID"; + secretAccessKey = "ENV_VAR_FOR_MAKES_PROD_AWS_SECRET_ACCESS_KEY"; + }; }; - moduleProd = { - setup = [ - outputs."/secretsForAwsFromEnv/makesProd" - ]; - src = "/my/module2"; - version = "0.14"; + lintTerraform = { + modules = { + moduleDev = { + setup = [ + outputs."/secretsForAwsFromEnv/makesDev" + ]; + src = "/my/module1"; + version = "0.14"; + }; + moduleProd = { + setup = [ + outputs."/secretsForAwsFromEnv/makesProd" + ]; + src = "/my/module2"; + version = "0.14"; + }; + }; }; - }; - }; -} -``` + } + ``` ## secretsForAwsFromGitlab @@ -106,47 +108,49 @@ Types: One retry per second. Defaults to `15`. -Example `makes.nix`: - -```nix -{ outputs -, lintTerraform -, secretsForAwsFromGitlab -, ... -}: -{ - secretsForAwsFromGitlab = { - makesDev = { - roleArn = "arn:aws:iam::123456789012:role/dev"; - duration = 3600; - retries = 30; - }; - makesProd = { - roleArn = "arn:aws:iam::123456789012:role/prod"; - duration = 7200; - retries = 30; - }; - }; - lintTerraform = { - modules = { - moduleDev = { - setup = [ - outputs."/secretsForAwsFromGitlab/makesDev" - ]; - src = "/my/module1"; - version = "0.14"; +Example: + +=== "makes.nix" + + ```nix + { + outputs, + lintTerraform, + secretsForAwsFromGitlab, + ... + }: { + secretsForAwsFromGitlab = { + makesDev = { + roleArn = "arn:aws:iam::123456789012:role/dev"; + duration = 3600; + retries = 30; + }; + makesProd = { + roleArn = "arn:aws:iam::123456789012:role/prod"; + duration = 7200; + retries = 30; + }; }; - moduleProd = { - setup = [ - outputs."/secretsForAwsFromGitlab/makesProd" - ]; - src = "/my/module2"; - version = "0.14"; + lintTerraform = { + modules = { + moduleDev = { + setup = [ + outputs."/secretsForAwsFromGitlab/makesDev" + ]; + src = "/my/module1"; + version = "0.14"; + }; + moduleProd = { + setup = [ + outputs."/secretsForAwsFromGitlab/makesProd" + ]; + src = "/my/module2"; + version = "0.14"; + }; + }; }; - }; - }; -} -``` + } + ``` ## secretsForEnvFromSops @@ -163,35 +167,37 @@ Types: - vars (`listOf str`): Names of the values to export out of the manifest. -Example `makes.nix`: - -```nix -{ outputs -, ... -}: -{ - secretsForEnvFromSops = { - cloudflare = { - # Manifest contains inside: - # CLOUDFLARE_ACCOUNT_ID: ... ciphertext ... - # CLOUDFLARE_API_TOKEN: ... ciphertext ... - manifest = "/infra/secrets/prod.yaml"; - vars = [ "CLOUDFLARE_ACCOUNT_ID" "CLOUDFLARE_API_TOKEN" ]; - }; - }; - lintTerraform = { - modules = { - moduleProd = { - setup = [ - outputs."/secretsForEnvFromSops/cloudflare" - ]; - src = "/my/module1"; - version = "0.14"; +Example: + +=== "makes.nix" + + ```nix + { + outputs, + ... + }: { + secretsForEnvFromSops = { + cloudflare = { + # Manifest contains inside: + # CLOUDFLARE_ACCOUNT_ID: ... ciphertext ... + # CLOUDFLARE_API_TOKEN: ... ciphertext ... + manifest = "/infra/secrets/prod.yaml"; + vars = [ "CLOUDFLARE_ACCOUNT_ID" "CLOUDFLARE_API_TOKEN" ]; + }; + }; + lintTerraform = { + modules = { + moduleProd = { + setup = [ + outputs."/secretsForEnvFromSops/cloudflare" + ]; + src = "/my/module1"; + version = "0.14"; + }; + }; }; - }; - }; -} -``` + } + ``` ## secretsForGpgFromEnv @@ -213,60 +219,69 @@ Types: Example: -```nix -# /path/to/my/project/makes.nix -{ outputs -, ... -}: -{ - # Load keys into an ephemeral GPG keyring - secretsForGpgFromEnv = { - example = [ - "ENV_VAR_FOR_PRIVATE_KEY_CONTENT" - "ENV_VAR_FOR_PUB_KEY_CONTENT" - ]; - }; - # Use sops to decrypt an encrypted file - secretsForEnvFromSops = { - example = { - manifest = "/secrets.yaml"; - vars = [ "password" ]; - }; - }; -} -``` - -```nix -# /path/to/my/project/makes/example/main.nix -{ makeScript -, outputs -, ... -}: -makeScript { - name = "example"; - searchPaths.source = [ - # First setup an ephemeral GPG keyring - outputs."/secretsForGpgFromEnv/example" - # Now sops will decrypt secrets using the GPG keys in the ring - outputs."/secretsForEnvFromSops/example" - ]; - entrypoint = '' - echo Decrypted password: $password - ''; -} -``` - -```yaml -# /path/to/my/project/secrets.yaml -password: ENC[AES256_GCM,data:cLbgzNHgBN5drfsDAS+RTV5fL6I=,iv:2YHhHxKg+lbGqdB5nhhG2YemeKB6XWvthGfNNkVgytQ=,tag:cj/el3taq1w7UOp/JQSNwA==,type:str] -# ... -``` - -```bash -$ m . /example - - Decrypted password: 123 -``` +=== "secrets.yaml" + + ```yaml + # /path/to/my/project/secrets.yaml + password: ENC[AES256_GCM,data:cLbgzNHgBN5drfsDAS+RTV5fL6I=,iv:2YHhHxKg+lbGqdB5nhhG2YemeKB6XWvthGfNNkVgytQ=,tag:cj/el3taq1w7UOp/JQSNwA==,type:str] + # ... + ``` + +=== "makes.nix" + + ```nix + # /path/to/my/project/makes.nix + { + outputs, + ... + }: { + # Load keys into an ephemeral GPG keyring + secretsForGpgFromEnv = { + example = [ + "ENV_VAR_FOR_PRIVATE_KEY_CONTENT" + "ENV_VAR_FOR_PUB_KEY_CONTENT" + ]; + }; + # Use sops to decrypt an encrypted file + secretsForEnvFromSops = { + example = { + manifest = "/secrets.yaml"; + vars = [ "password" ]; + }; + }; + } + ``` + +=== "main.nix" + + ```nix + # /path/to/my/project/makes/example/main.nix + { + makeScript, + outputs, + ... + }: + makeScript { + name = "example"; + searchPaths.source = [ + # First setup an ephemeral GPG keyring + outputs."/secretsForGpgFromEnv/example" + # Now sops will decrypt secrets using the GPG keys in the ring + outputs."/secretsForEnvFromSops/example" + ]; + entrypoint = '' + echo Decrypted password: $password + ''; + } + ``` + +=== "Invocation" + + ```bash + $ m . /example + + Decrypted password: 123 + ``` ## secretsForKubernetesConfigFromAws @@ -286,32 +301,34 @@ Types: - region (`str`): AWS Region the EKS cluster is located in. -Example `makes.nix`: - -```nix -{ outputs -, ... -}: -{ - secretsForKubernetesConfigFromAws = { - myCluster = { - cluster = "makes-k8s"; - region = "us-east-1"; - }; - }; - deployTerraform = { - modules = { - moduleProd = { - setup = [ - outputs."/secretsForKubernetesConfigFromAws/myCluster" - ]; - src = "/my/module1"; - version = "0.14"; +Example: + +=== "makes.nix" + + ```nix + { + outputs, + ... + }: { + secretsForKubernetesConfigFromAws = { + myCluster = { + cluster = "makes-k8s"; + region = "us-east-1"; + }; }; - }; - }; -} -``` + deployTerraform = { + modules = { + moduleProd = { + setup = [ + outputs."/secretsForKubernetesConfigFromAws/myCluster" + ]; + src = "/my/module1"; + version = "0.14"; + }; + }; + }; + } + ``` ## secretsForTerraformFromEnv @@ -326,27 +343,29 @@ Types: to environment variable names. Defaults to `{ }`. -Example `makes.nix`: - -```nix -{ outputs -, ... -}: -{ - secretsForTerraformFromEnv = { - example = { - # Equivalent in Bash to: - # export TF_VAR_cloudflareAccountId=$ENV_VAR_FOR_CLOUDFLARE_ACCOUNT_ID - # export TF_VAR_cloudflareApiToken=$ENV_VAR_FOR_CLOUDFLARE_API_TOKEN - cloudflareAccountId = "ENV_VAR_FOR_CLOUDFLARE_ACCOUNT_ID"; - cloudflareApiToken = "ENV_VAR_FOR_CLOUDFLARE_API_TOKEN"; - }; - }; -} -``` - -Example `main.tf`: - -```tf -variable "cloudflareAccountId" {} -``` +Example: + +=== "makes.nix" + + ```nix + { + outputs, + ... + }: { + secretsForTerraformFromEnv = { + example = { + # Equivalent in Bash to: + # export TF_VAR_cloudflareAccountId=$ENV_VAR_FOR_CLOUDFLARE_ACCOUNT_ID + # export TF_VAR_cloudflareApiToken=$ENV_VAR_FOR_CLOUDFLARE_API_TOKEN + cloudflareAccountId = "ENV_VAR_FOR_CLOUDFLARE_ACCOUNT_ID"; + cloudflareApiToken = "ENV_VAR_FOR_CLOUDFLARE_API_TOKEN"; + }; + }; + } + ``` + +=== "main.tf" + + ```tf + variable "cloudflareAccountId" {} + ``` diff --git a/docs/src/api/builtins/security.md b/docs/src/api/builtins/security.md index ab6ae00e..4cd96131 100644 --- a/docs/src/api/builtins/security.md +++ b/docs/src/api/builtins/security.md @@ -22,42 +22,48 @@ Types: before anything else. Defaults to `[ ]`. -Example `makes.nix`: - -```nix -{ outputs -, secretsForAwsFromGitlab -, secretsForKubernetesConfigFromAws -, secureKubernetesWithRbacPolice -, ... -}: -{ - secretsForAwsFromGitlab = { - makesProd = { - roleArn = "arn:aws:iam::123456789012:role/prod"; - duration = 7200; - retries = 30; - }; - }; - secretsForKubernetesConfigFromAws = { - makes = { - cluster = "makes-k8s"; - region = "us-east-1"; - }; - }; - secureKubernetesWithRbacPolice = { - makes = { - severity = "Low"; - setup = [ - outputs."/secretsForAwsFromGitlab/makesProd" - outputs."/secretsForKubernetesConfigFromAws/makes" - ]; - }; - }; -} -``` - -Example invocation: `$ m . /secureKubernetesWithRbacPolice/makes` +Example: + +=== "makes.nix" + + ```nix + { + outputs, + secretsForAwsFromGitlab, + secretsForKubernetesConfigFromAws, + secureKubernetesWithRbacPolice, + ... + }: { + secretsForAwsFromGitlab = { + makesProd = { + roleArn = "arn:aws:iam::123456789012:role/prod"; + duration = 7200; + retries = 30; + }; + }; + secretsForKubernetesConfigFromAws = { + makes = { + cluster = "makes-k8s"; + region = "us-east-1"; + }; + }; + secureKubernetesWithRbacPolice = { + makes = { + severity = "Low"; + setup = [ + outputs."/secretsForAwsFromGitlab/makesProd" + outputs."/secretsForKubernetesConfigFromAws/makes" + ]; + }; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /secureKubernetesWithRbacPolice/makes + ``` ## securePythonWithBandit @@ -75,17 +81,23 @@ Types: - target (`str`): Relative path to the package/module. -Example `makes.nix`: +Example: -```nix -{ - securePythonWithBandit = { - cli = { - python = "3.8"; - target = "/src/cli"; - }; - }; -} -``` +=== "makes.nix" -Example invocation: `$ m . /securePythonWithBandit/cli` + ```nix + { + securePythonWithBandit = { + cli = { + python = "3.8"; + target = "/src/cli"; + }; + }; + } + ``` + +=== "Invocation" + + ```bash + m . /securePythonWithBandit/cli + ``` diff --git a/docs/src/api/builtins/test.md b/docs/src/api/builtins/test.md index 7d9bd82d..a7db00ba 100644 --- a/docs/src/api/builtins/test.md +++ b/docs/src/api/builtins/test.md @@ -39,36 +39,46 @@ Types: And we will run pytest like this: - `$ pytest /tmp/some-random-unique-dir/__project__/path/to/src` + ```{ .bash, linenums=0} + pytest /tmp/some-random-unique-dir/__project__/path/to/src + ``` Defaults to `{ }`. -Example `makes.nix`: +Example: + +=== "makes.nix" + + ```nix + { + testPython = { + example = { + python = "3.9"; + src = "/test/test-python"; + }; + }; + } + ``` -```nix -{ - testPython = { - example = { - python = "3.9"; - src = "/test/test-python"; - }; - }; -} -``` +=== "Invocation" -```bash -$ tree test/test-python/ + ```bash + m . /testPython/example + ``` - test/test-python/ - └── test_something.py +=== "Directory" -$ cat test/test-python/test_something.py + ```bash + $ tree test/test-python/ - 1 def test_one_plus_one_equals_two() -> None: - 2 assert (1 + 1) == 2 -``` + test/test-python/ + └── test_something.py -Example invocation: `$ m . /testPython/example` + $ cat test/test-python/test_something.py + + 1 def test_one_plus_one_equals_two() -> None: + 2 assert (1 + 1) == 2 + ``` ## testTerraform @@ -98,25 +108,29 @@ Types: and remove parallelism so logs are clean. Defaults to `false`. -Example `makes.nix`: - -```nix -{ - testTerraform = { - modules = { - module1 = { - src = "/my/module1"; - version = "0.14"; - }; - module2 = { - src = "/my/module2"; - version = "1.0"; +Example: + +=== "makes.nix" + + ```nix + { + testTerraform = { + modules = { + module1 = { + src = "/my/module1"; + version = "0.14"; + }; + module2 = { + src = "/my/module2"; + version = "1.0"; + }; + }; }; - }; - }; -} -``` + } + ``` -Example invocation: `$ m . /testTerraform/module1` +=== "Invocation" -Example invocation: `$ m . /testTerraform/module2` + ```bash + $ m . /testTerraform/module1 + ``` diff --git a/docs/src/api/builtins/utilities.md b/docs/src/api/builtins/utilities.md index e957f3c0..fc609dc4 100644 --- a/docs/src/api/builtins/utilities.md +++ b/docs/src/api/builtins/utilities.md @@ -38,13 +38,12 @@ m github:fluidattacks/makes@23.04 /utils/makePythonLock \ - Supported `python_version`s are: `3.8`, `3.9`, `3.10` and `3.11`. - `dependencies_yaml` is the **absolute path** to a YAML file mapping [PyPI](https://pypi.org/) packages to version constraints. + Example: -Example: - -```yaml -Django: "3.2.*" -psycopg2: "2.9.1" -``` + ```yaml + Django: "3.2.*" + psycopg2: "2.9.1" + ``` - `sources_yaml` is the **absolute path** to a file were the script will output results. @@ -65,13 +64,12 @@ m github:fluidattacks/makes@23.04 /utils/makeRubyLock \ - Supported `ruby_version`s are: `2.7`, `3.0` and `3.1`. - `dependencies_yaml` is the **absolute path** to a YAML file mapping [RubyGems](https://rubygems.org/) gems to version constraints. + Example: -Example: - -```yaml -rubocop: "1.43.0" -slim: "~> 4.1" -``` + ```yaml + rubocop: "1.43.0" + slim: "~> 4.1" + ``` - `sources_yaml` is the **absolute path** to a file were the script will output results. @@ -117,29 +115,31 @@ Types: - version (`enum [ "0.14" "0.15" "1.0" ]`): Terraform version your module is built with. -Example `makes.nix`: - -```nix -{ - testTerraform = { - modules = { - module1 = { - setup = [ - outputs."/workspaceForTerraformFromEnv/module1" - ]; - src = "/my/module1"; - version = "0.14"; +Example: + +=== "makes.nix" + + ```nix + { + testTerraform = { + modules = { + module1 = { + setup = [ + outputs."/workspaceForTerraformFromEnv/module1" + ]; + src = "/my/module1"; + version = "0.14"; + }; + }; }; - }; - }; - workspaceForTerraformFromEnv = { - modules = { - module1 = { - src = "/my/module1"; - variable = "CI_COMMIT_REF_NAME"; - version = "0.14"; + workspaceForTerraformFromEnv = { + modules = { + module1 = { + src = "/my/module1"; + variable = "CI_COMMIT_REF_NAME"; + version = "0.14"; + }; + }; }; - }; - }; -} -``` + } + ``` diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md index a8b2afab..1dd57112 100644 --- a/docs/src/getting-started.md +++ b/docs/src/getting-started.md @@ -11,7 +11,7 @@ 1. Install Makes: - ```bash + ```{ .bash, linenums=0} nix-env -if https://github.com/fluidattacks/makes/archive/23.04.tar.gz ``` @@ -21,8 +21,8 @@ The Makes command has the following syntax: -```bash -$ m +```{ .bash, linenums=0} +m ``` where: @@ -72,7 +72,7 @@ makes.makePythonPypiEnvironment { Most functions documented in the [api/extensions](api/extensions/) section are available. -For a defailed list check out +For a detailed list check out [Makes' agnostic args](https://github.com/fluidattacks/makes/blob/main/src/args/agnostic.nix). ## Want to get your hands dirty?