From 0e0df50ea87fa6c8ecceb4445b6d3d51987ced67 Mon Sep 17 00:00:00 2001 From: Casper Welzel Andersen <43357585+CasperWA@users.noreply.github.com> Date: Tue, 29 Aug 2023 14:16:42 +0200 Subject: [PATCH] Parse `pylint_options` depending on newlines (#170) Clarify when single space-separated line is accepted If it not accepted: Remove the mention of single line in the description of the input, leaving only "multi-line". And always parse as if it is a multi-line input. If it is accepted: Update the parsing to check for newline characters before actually parsing the input. Also add "(space-separated)" to describe a multi-valued single-line input. A new section "General information" has been added in the documentation under the overview of the workflows. A section about single vs multi-line values have been added, including examples. This section has then been referenced throughout the documentation for specific input parameters that mention "single og multi-line values". --- .github/workflows/cd_release.yml | 32 ++++-- .../ci_cd_updated_default_branch.yml | 42 ++++--- .github/workflows/ci_tests.yml | 76 ++++++++----- docs/workflows/cd_release.md | 8 +- docs/workflows/ci_automerge_prs.md | 4 +- .../workflows/ci_cd_updated_default_branch.md | 18 +-- .../ci_check_pyproject_dependencies.md | 2 +- docs/workflows/ci_tests.md | 46 ++++---- docs/workflows/ci_update_dependencies.md | 2 +- docs/workflows/index.md | 103 ++++++++++++++++++ 10 files changed, 243 insertions(+), 90 deletions(-) diff --git a/.github/workflows/cd_release.yml b/.github/workflows/cd_release.yml index 352c203a..4dadcdd1 100644 --- a/.github/workflows/cd_release.yml +++ b/.github/workflows/cd_release.yml @@ -47,12 +47,12 @@ on: type: string default: "3.9" package_dirs: - description: "A single or multi-line string of paths to Python package directories relative to the repository directory to have its `__version__` value updated. Example: `'src/my_package'`. **Important**: This is _required_ if 'python_package' is 'true', which is the default." + description: "A multi-line string of paths to Python package directories relative to the repository directory to have its `__version__` value updated. Example: `'src/my_package'`. **Important**: This is _required_ if 'python_package' is 'true', which is the default." required: false type: string default: "" version_update_changes: - description: "A single or multi-line string of changes to be implemented in the repository files upon updating the version. The string should be made up of three parts: 'file path', 'pattern', and 'replacement string'. These are separated by the 'version_update_changes_separator' value. The 'file path' must _always_ either be relative to the repository root directory or absolute. The 'pattern' should be given as a 'raw' Python string." + description: "A multi-line string of changes to be implemented in the repository files upon updating the version. The string should be made up of three parts: 'file path', 'pattern', and 'replacement string'. These are separated by the 'version_update_changes_separator' value. The 'file path' must _always_ either be relative to the repository root directory or absolute. The 'pattern' should be given as a 'raw' Python string." required: false type: string default: "" @@ -339,10 +339,16 @@ jobs: - name: Install system dependencies if: inputs.system_dependencies != '' run: | - SYSTEM_PACKAGES=() - while IFS= read -r line; do - if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi - done <<< "${{ inputs.system_dependencies }}" + if [[ "${{ inputs.system_dependencies }}" =~ \n ]]; then + # Expected to be a multi-line string + SYSTEM_PACKAGES=() + while IFS= read -r line; do + if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi + done <<< "${{ inputs.system_dependencies }}" + else + # Expected to be a single-line string + SYSTEM_PACKAGES=(${{ inputs.system_dependencies }}) + fi sudo apt update && sudo apt install -y "${SYSTEM_PACKAGES[@]}" @@ -365,10 +371,16 @@ jobs: REF=${{ github.ref }} if [ "${{ inputs.docs_framework }}" == "sphinx" ]; then - SPHINX_OPTIONS=() - while IFS= read -r line; do - if [ -n "${line}" ]; then SPHINX_OPTIONS+=("${line}"); fi - done <<< "${{ inputs.sphinx-build_options }}" + if [[ "${{ inputs.sphinx-build_options }}" =~ \n ]]; then + # Expected to be a multi-line string + SPHINX_OPTIONS=() + while IFS= read -r line; do + if [ -n "${line}" ]; then SPHINX_OPTIONS+=("${line}"); fi + done <<< "${{ inputs.sphinx-build_options }}" + else + # Expected to be a single-line string + SPHINX_OPTIONS=(${{ inputs.sphinx-build_options }}) + fi fi if [ "${{ inputs.test }}" == "true" ]; then diff --git a/.github/workflows/ci_cd_updated_default_branch.yml b/.github/workflows/ci_cd_updated_default_branch.yml index 54989792..2bf9c46d 100644 --- a/.github/workflows/ci_cd_updated_default_branch.yml +++ b/.github/workflows/ci_cd_updated_default_branch.yml @@ -49,7 +49,7 @@ on: type: boolean default: true package_dirs: - description: "A single or multi-line string of paths to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation. Example: `'src/my_package'`. **Important**: This is _required_ if 'update_docs' and 'update_python_api_ref' are 'true'." + description: "A multi-line string of paths to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation. Example: `'src/my_package'`. **Important**: This is _required_ if 'update_docs' and 'update_python_api_ref' are 'true'." required: false type: string default: "" @@ -74,32 +74,32 @@ on: type: boolean default: false exclude_dirs: - description: "A single or multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`. Important: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories." + description: "A multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`. Important: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories." required: false type: string default: "__pycache__" exclude_files: - description: "A single or multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`. Important: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files." + description: "A multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`. Important: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files." required: false type: string default: "__init__.py" full_docs_dirs: - description: "A single or multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed." + description: "A multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed." required: false type: string default: "" full_docs_files: - description: "A single or multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed." + description: "A multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed." required: false type: string default: "" special_file_api_ref_options: - description: "A single or multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation. Example: 'my_module/py_file.py,show_bases:false'. Encapsulate the value in double quotation marks (\") if including spaces ( ). Important: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., '\"my_package/my_module/py_file.py,show_bases: false\"'." + description: "A multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation. Example: 'my_module/py_file.py,show_bases:false'. Encapsulate the value in double quotation marks (\") if including spaces ( ). Important: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., '\"my_package/my_module/py_file.py,show_bases: false\"'." required: false type: string default: "" landing_page_replacements: - description: "A single or multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list ALWAYS includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`." + description: "A multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list ALWAYS includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`." required: false type: string default: "(LICENSE),(LICENSE.md)" @@ -201,10 +201,16 @@ jobs: - name: Install system dependencies if: env.RELEASE_RUN == 'false' && inputs.system_dependencies != '' run: | - SYSTEM_PACKAGES=() - while IFS= read -r line; do - if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi - done <<< "${{ inputs.system_dependencies }}" + if [[ "${{ inputs.system_dependencies }}" =~ \n ]]; then + # Expected to be a multi-line string + SYSTEM_PACKAGES=() + while IFS= read -r line; do + if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi + done <<< "${{ inputs.system_dependencies }}" + else + # Expected to be a single-line string + SYSTEM_PACKAGES=(${inputs.system_dependencies}) + fi sudo apt update && sudo apt install -y "${SYSTEM_PACKAGES[@]}" @@ -357,10 +363,16 @@ jobs: if: env.RELEASE_RUN == 'false' && ( ! inputs.test ) run: | if [ "${{ inputs.docs_framework }}" == "sphinx" ]; then - SPHINX_OPTIONS=() - while IFS= read -r line; do - if [ -n "${line}" ]; then SPHINX_OPTIONS+=("${line}"); fi - done <<< "${{ inputs.sphinx-build_options }}" + if [[ "${{ inputs.sphinx-build_options }}" =~ \n ]]; then + # Expected to be a multi-line string + SPHINX_OPTIONS=() + while IFS= read -r line; do + if [ -n "${line}" ]; then SPHINX_OPTIONS+=("${line}"); fi + done <<< "${{ inputs.sphinx-build_options }}" + else + # Expected to be a single-line string + SPHINX_OPTIONS=(${{ inputs.sphinx-build_options }}) + fi fi if [ "${{ inputs.test }}" == "true" ]; then diff --git a/.github/workflows/ci_tests.yml b/.github/workflows/ci_tests.yml index 2f8ae534..a211cb41 100644 --- a/.github/workflows/ci_tests.yml +++ b/.github/workflows/ci_tests.yml @@ -40,7 +40,7 @@ on: type: boolean default: true pylint_options: - description: "Single space-separated or multi-line string of pylint command line options. Note, this is only valid if 'pylint_runs' is not defined." + description: "Single (space-separated) or multi-line string of pylint command line options. Note, this is only valid if 'pylint_runs' is not defined." required: false type: string default: "" @@ -50,7 +50,7 @@ on: type: string default: "" pylint_runs: - description: "Single or multi-line string with each line representing a separate pylint run/execution. This should include all desired options and targets. Important, the inputs 'pylint_options' and 'pylint_targets' will be ignored if this is defined." + description: "Multi-line string with each line representing a separate pylint run/execution. This should include all desired options and targets. Important, the inputs 'pylint_options' and 'pylint_targets' will be ignored if this is defined." required: false type: string default: "" @@ -61,7 +61,7 @@ on: type: boolean default: true safety_options: - description: "Single space-separated or multi-line string of safety command line options." + description: "Single (space-separated) or multi-line string of safety command line options." required: false type: string default: "" @@ -127,7 +127,7 @@ on: type: boolean default: true package_dirs: - description: "A single or multi-line string of paths to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation. Example: `'src/my_package'`. **Important**: This is _required_ if 'run_build_docs' and 'update_python_api_ref' are 'true'." + description: "A multi-line string of paths to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation. Example: `'src/my_package'`. **Important**: This is _required_ if 'run_build_docs' and 'update_python_api_ref' are 'true'." required: false type: string default: "" @@ -137,32 +137,32 @@ on: type: boolean default: true exclude_dirs: - description: "A single or multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`. Important: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories." + description: "A multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`. Important: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories." required: false type: string default: "__pycache__" exclude_files: - description: "A single or multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`. Important: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files." + description: "A multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`. Important: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files." required: false type: string default: "__init__.py" full_docs_dirs: - description: "A single or multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed." + description: "A multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed." required: false type: string default: "" full_docs_files: - description: "A single or multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed." + description: "A multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed." required: false type: string default: "" special_file_api_ref_options: - description: "A single or multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation. Example: 'my_module/py_file.py,show_bases:false'. Encapsulate the value in double quotation marks (\") if including spaces ( ). Important: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., '\"my_package/my_module/py_file.py,show_bases: false\"'." + description: "A multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation. Example: 'my_module/py_file.py,show_bases:false'. Encapsulate the value in double quotation marks (\") if including spaces ( ). Important: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., '\"my_package/my_module/py_file.py,show_bases: false\"'." required: false type: string default: "" landing_page_replacements: - description: "A single or multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list ALWAYS includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`." + description: "A multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list ALWAYS includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`." required: false type: string default: "(LICENSE),(LICENSE.md)" @@ -263,10 +263,16 @@ jobs: echo "Please supply the 'pylint_targets' input, since you are not using the 'pylint_runs' input." fi - PYLINT_OPTIONS=() - while IFS= read -r line; do - if [ -n "${line}" ]; then PYLINT_OPTIONS+=("${line}"); fi - done <<< "${{ inputs.pylint_options }}" + if [[ "${{ inputs.pylint_options }}" =~ \n ]]; then + # Expected to be a multi-line string + PYLINT_OPTIONS=() + while IFS= read -r line; do + if [ -n "${line}" ]; then PYLINT_OPTIONS+=("${line}"); fi + done <<< "${{ inputs.pylint_options }}" + else + # Expected to be a single-line string + PYLINT_OPTIONS=(${{ inputs.pylint_options }}) + fi pylint "${PYLINT_OPTIONS[@]}" ${{ inputs.pylint_targets }} fi @@ -274,10 +280,16 @@ jobs: - name: Run `safety` if: inputs.run_safety run: | - SAFETY_OPTIONS=() - while IFS= read -r line; do - if [ -n "${line}" ]; then SAFETY_OPTIONS+=("${line}"); fi - done <<< "${{ inputs.safety_options }}" + if [[ "${{ inputs.safety_options }}" =~ \n ]]; then + # Expected to be a multi-line string + SAFETY_OPTIONS=() + while IFS= read -r line; do + if [ -n "${line}" ]; then SAFETY_OPTIONS+=("${line}"); fi + done <<< "${{ inputs.safety_options }}" + else + # Expected to be a single-line string + SAFETY_OPTIONS=(${{ inputs.safety_options }}) + fi pip freeze | safety check --stdin "${SAFETY_OPTIONS[@]}" @@ -346,10 +358,16 @@ jobs: - name: Install system dependencies if: inputs.system_dependencies != '' run: | - SYSTEM_PACKAGES=() - while IFS= read -r line; do - if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi - done <<< "${{ inputs.system_dependencies }}" + if [[ "${{ inputs.system_dependencies }}" =~ \n ]]; then + # Expected to be a multi-line string + SYSTEM_PACKAGES=() + while IFS= read -r line; do + if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi + done <<< "${{ inputs.system_dependencies }}" + else + # Expected to be a single-line string + SYSTEM_PACKAGES=(${{ inputs.system_dependencies }}) + fi sudo apt update && sudo apt install -y "${SYSTEM_PACKAGES[@]}" @@ -456,10 +474,16 @@ jobs: mkdocs build ${STRICT} elif [ "${{ env.framework }}" == "sphinx" ]; then - SPHINX_OPTIONS=() - while IFS= read -r line; do - if [ -n "${line}" ]; then SPHINX_OPTIONS+=("${line}"); fi - done <<< "${{ inputs.sphinx-build_options }}" + if [[ "${{ inputs.sphinx-build_options }}" =~ \n ]]; then + # Expected to be a multi-line string + SPHINX_OPTIONS=() + while IFS= read -r line; do + if [ -n "${line}" ]; then SPHINX_OPTIONS+=("${line}"); fi + done <<< "${{ inputs.sphinx-build_options }}" + else + # Expected to be a single-line string + SPHINX_OPTIONS=(${{ inputs.sphinx-build_options }}) + fi sphinx-build ${STRICT} \ "${SPHINX_OPTIONS[@]}" \ diff --git a/docs/workflows/cd_release.md b/docs/workflows/cd_release.md index de9a98ac..0dfe1478 100644 --- a/docs/workflows/cd_release.md +++ b/docs/workflows/cd_release.md @@ -80,8 +80,8 @@ Inputs related to updating the version, building and releasing the Python packag |:--- |:--- |:---:|:---:|:---:| | `python_package` | Whether or not this is a Python package, where the version should be updated in the `'package_dir'/__init__.py` for the possibly several 'package_dir' lines given in the `package_dirs` input and a build and release to PyPI should be performed. | No | `true` | _boolean_ | | `python_version_build` | The Python version to use for the workflow when building the package. | No | 3.9 | _string_ | -| `package_dirs` | single or multi-line string of paths to Python package directories relative to the repository directory to have its `__version__` value updated.

Example: `'src/my_package'`.

**Important**: This is _required_ if 'python_package' is 'true', which is the default. | **_Yes_ (if 'python_package' is 'true'** | | _string_ | -| `version_update_changes` | A single or multi-line string of changes to be implemented in the repository files upon updating the version. The string should be made up of three parts: 'file path', 'pattern', and 'replacement string'. These are separated by the 'version_update_changes_separator' value.
The 'file path' must _always_ either be relative to the repository root directory or absolute.
The 'pattern' should be given as a 'raw' Python string. | No | _Empty string_ | _string_ | +| `package_dirs` | A multi-line string of paths to Python package directories relative to the repository directory to have its `__version__` value updated.

Example: `'src/my_package'`.

**Important**: This is _required_ if 'python_package' is 'true', which is the default.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | **_Yes_ (if 'python_package' is 'true'** | | _string_ | +| `version_update_changes` | A multi-line string of changes to be implemented in the repository files upon updating the version. The string should be made up of three parts: 'file path', 'pattern', and 'replacement string'. These are separated by the 'version_update_changes_separator' value.
The 'file path' must _always_ either be relative to the repository root directory or absolute.
The 'pattern' should be given as a 'raw' Python string.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | | `version_update_changes_separator` | The separator to use for 'version_update_changes' when splitting the three parts of each string. | No | , | _string_ | | `build_libs` | A space-separated list of packages to install via PyPI (`pip install`). | No | _Empty string_ | _string_ | | `build_cmd` | The package build command, e.g., `'flit build'` or `'python -m build'` (default). | No | `python -m build` | _string_ | @@ -98,13 +98,13 @@ Inputs related to building and releasing the documentation. | `python_version_docs` | The Python version to use for the workflow when building the documentation. | No | 3.9 | _string_ | | `doc_extras` | Any extras to install from the local repository through 'pip'. Must be encapsulated in square parentheses (`[]`) and be separated by commas (`,`) without any spaces.

Note, if this is empty, 'install_extras' will be used as a fallback.

Example: `'[docs]'`. | No | _Empty string_ | _string_ | | `docs_framework` | The documentation framework to use. This can only be either `'mkdocs'` or `'sphinx'`. | No | mkdocs | _string_ | -| `system_dependencies` | A single (space-separated) or multi-line string of Ubuntu APT packages to install prior to building the documentation. | No | _Empty string_ | _string_ | +| `system_dependencies` | A single (space-separated) or multi-line string of Ubuntu APT packages to install prior to building the documentation.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | Finally, inputs related _only_ to the Sphinx framework when building and releasing the documentation. | **Name** | **Description** | **Required** | **Default** | **Type** | |:--- |:--- |:---:|:---:|:---:| -| `sphinx-build_options` | Single (space-separated) or multi-line string of command-line options to use when calling `sphinx-build`. | No | _Empty string_ | _string_ | +| `sphinx-build_options` | Single (space-separated) or multi-line string of command-line options to use when calling `sphinx-build`.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | | `docs_folder` | The path to the root documentation folder relative to the repository root. | No | docs | _string_ | | `build_target_folder` | The path to the target folder for the documentation build relative to the repository root. | No | site | _string_ | diff --git a/docs/workflows/ci_automerge_prs.md b/docs/workflows/ci_automerge_prs.md index 0473cb63..297618af 100644 --- a/docs/workflows/ci_automerge_prs.md +++ b/docs/workflows/ci_automerge_prs.md @@ -8,7 +8,7 @@ It is possible to introduce changes to the PR head branch prior to activating th This is done by setting `perform_changes` to `'true'` and setting the other inputs accordingly, as they are now required. See [Inputs](#inputs) below for a full overview of the available inputs. -The `changes` input can be both a path to a bash file that should be run, or a single or multi-line string of bash commands to run. +The `changes` input can be both a path to a bash file that should be run, or a multi-line string of bash commands to run. Afterwards any and all changes in the repository will be committed and pushed to the PR head branch. The motivation for being able to run changes prior to auto-merging, is to update or affect the repository files according to the specific PR being auto-merged. @@ -31,7 +31,7 @@ This workflow can _only_ be called if the triggering event from the caller workf | `perform_changes` | Whether or not to perform and commit changes to the PR branch prior to activating auto-merge. | No | | _boolean_ | | `git_username` | A git username (used to set the 'user.name' config option).
**Required** if `perform_changes` is 'true'. | No | | _string_ | | `git_email` | A git user's email address (used to set the 'user.email' config option).
**Required** if `perform_changes` is 'true'. | No | | _string_ | -| `changes` | A file to run in the local repository (relative path from the root of the repository) or a multi-line string of bash commands to run.
**Required** if `perform_changes` is 'true'. | No | | _string_ | +| `changes` | A file to run in the local repository (relative path from the root of the repository) or a multi-line string of bash commands to run.
**Required** if `perform_changes` is 'true'.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | | _string_ | ## Secrets diff --git a/docs/workflows/ci_cd_updated_default_branch.md b/docs/workflows/ci_cd_updated_default_branch.md index 288d16a2..b7805844 100644 --- a/docs/workflows/ci_cd_updated_default_branch.md +++ b/docs/workflows/ci_cd_updated_default_branch.md @@ -55,28 +55,28 @@ Inputs related to building and releasing the documentation. |:--- |:--- |:---:|:---:|:---:| | `update_docs` | Whether or not to also run the 'docs' workflow job. | No | `false` | _boolean_ | | `update_python_api_ref` | Whether or not to update the Python API documentation reference.

**Note**: If this is 'true', 'package_dirs' is _required_. | No | `true` | _boolean_ | -| `package_dirs` | A single or multi-line string of paths to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation.

Example: `'src/my_package'`.

**Important**: This is _required_ if 'update_docs' and 'update_python_api_ref' are 'true'. | **_Yes_ (if 'update_docs' and 'update_python_api_ref' are 'true')** | | _string_ | +| `package_dirs` | A multi-line string of paths to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation.

Example: `'src/my_package'`.

**Important**: This is _required_ if 'update_docs' and 'update_python_api_ref' are 'true'.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | **_Yes_ (if 'update_docs' and 'update_python_api_ref' are 'true')** | | _string_ | | `update_docs_landing_page` | Whether or not to update the documentation landing page. The landing page will be based on the root README.md file. | No | `true` | _boolean_ | | `python_version` | The Python version to use for the workflow.

**Note**: This is only relevant if `update_pre-commit` is `true`. | No | 3.9 | _string_ | | `doc_extras` | Any extras to install from the local repository through 'pip'. Must be encapsulated in square parentheses (`[]`) and be separated by commas (`,`) without any spaces.

Example: `'[docs]'`. | No | _Empty string_ | _string_ | | `relative` | Whether or not to use install the local Python package(s) as an editable. | No | `false` | _boolean_ | -| `exclude_dirs` | A single or multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories. | No | \_\_pycache\_\_ | _string_ | -| `exclude_files` | A single or multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files. | No | \_\_init\_\_.py | _string_ | -| `full_docs_dirs` | A single or multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed. | No | _Empty string_ | _string_ | -| `full_docs_files` | A single or multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed. | No | _Empty string_ | _string_ | -| `special_file_api_ref_options` | A single or multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation.
Example: `my_module/py_file.py,show_bases:false`.

Encapsulate the value in double quotation marks (`"`) if including spaces ( ).

**Important**: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., `"my_package/my_module/py_file.py,show_bases: false"`. | No | _Empty string_ | _string_ | -| `landing_page_replacements` | A single or multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list _always_ includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`. | No | (LICENSE),(LICENSE.md) | _string_ | +| `exclude_dirs` | A multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | \_\_pycache\_\_ | _string_ | +| `exclude_files` | A multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | \_\_init\_\_.py | _string_ | +| `full_docs_dirs` | A multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | +| `full_docs_files` | A multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | +| `special_file_api_ref_options` | A multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation.
Example: `my_module/py_file.py,show_bases:false`.

Encapsulate the value in double quotation marks (`"`) if including spaces ( ).

**Important**: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., `"my_package/my_module/py_file.py,show_bases: false"`.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | +| `landing_page_replacements` | A multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list _always_ includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | (LICENSE),(LICENSE.md) | _string_ | | `landing_page_replacement_separator` | String to separate a mapping's 'old' to 'new' parts. Defaults to a comma (`,`). | No | , | _string_ | | `changelog_exclude_tags_regex` | A regular expression matching any tags that should be excluded from the CHANGELOG.md. | No | _Empty string_ | _string_ | | `changelog_exclude_labels` | Comma-separated list of labels to exclude from the CHANGELOG.md. | No | _Empty string_ | _string_ | | `docs_framework` | The documentation framework to use. This can only be either `'mkdocs'` or `'sphinx'`. | No | mkdocs | _string_ | -| `system_dependencies` | A single (space-separated) or multi-line string of Ubuntu APT packages to install prior to building the documentation. | No | _Empty string_ | _string_ | +| `system_dependencies` | A single (space-separated) or multi-line string of Ubuntu APT packages to install prior to building the documentation.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | Finally, inputs related _only_ to the Sphinx framework when building and releasing the documentation. | **Name** | **Description** | **Required** | **Default** | **Type** | |:--- |:--- |:---:|:---:|:---:| -| `sphinx-build_options` | Single (space-separated) or multi-line string of command-line options to use when calling `sphinx-build`. | No | _Empty string_ | _string_ | +| `sphinx-build_options` | Single (space-separated) or multi-line string of command-line options to use when calling `sphinx-build`.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | | `docs_folder` | The path to the root documentation folder relative to the repository root. | No | docs | _string_ | | `build_target_folder` | The path to the target folder for the documentation build relative to the repository root. | No | site | _string_ | diff --git a/docs/workflows/ci_check_pyproject_dependencies.md b/docs/workflows/ci_check_pyproject_dependencies.md index 702836b7..ce0064d2 100644 --- a/docs/workflows/ci_check_pyproject_dependencies.md +++ b/docs/workflows/ci_check_pyproject_dependencies.md @@ -64,7 +64,7 @@ The repository contains the following: | `pr_body_file` | Relative path to PR body file from the root of the repository.

Example: `'.github/utils/pr_body_deps_check.txt'`. | No | _Empty string_ | _string_ | | `fail_fast` | Whether the task to update dependencies should fail if any error occurs. | No | `false` | _boolean_ | | `pr_labels` | A comma separated list of strings of GitHub labels to use for the created PR. | No | _Empty string_ | _string_ | -| `ignore` | Create ignore conditions for certain dependencies. A multi-line string of ignore rules, where each line is an ellipsis-separated (`...`) string of key/value-pairs. One line per dependency. This option is similar to [the `ignore` option of Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#ignore). | No | _Empty string_ | _string_ +| `ignore` | Create ignore conditions for certain dependencies. A multi-line string of ignore rules, where each line is an ellipsis-separated (`...`) string of key/value-pairs. One line per dependency. This option is similar to [the `ignore` option of Dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#ignore).

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ ## Secrets diff --git a/docs/workflows/ci_tests.md b/docs/workflows/ci_tests.md index eafa9d78..4e77b4d4 100644 --- a/docs/workflows/ci_tests.md +++ b/docs/workflows/ci_tests.md @@ -60,9 +60,9 @@ There are no expectations or pre-requisites. | `python_version_pylint_safety` | The Python version to use for the `pylint` and `safety` test jobs. | No | 3.9 | _string_ | | `install_extras` | Any extras to install from the local repository through 'pip'. Must be encapsulated in square parentheses (`[]`) and be separated by commas (`,`) without any spaces.

Example: `'[dev,pre-commit]'`. | No | _Empty string_ | _string_ | | `pylint_targets` | Space-separated string of pylint file and folder targets.

**Note**: This is only valid if `pylint_runs` is not defined. | **Yes, if `pylint_runs` is not defined** | _Empty string_ | _string_ | -| `pylint_options` | Single space-separated or multi-line string of pylint command line options.

**Note**: This is only valid if `pylint_runs` is not defined. | No | _Empty string_ | _string_ | -| `pylint_runs` | Single or multi-line string with each line representing a separate pylint run/execution. This should include all desired options and targets.

**Important**: The inputs `pylint_options` and `pylint_targets` will be ignored if this is defined. | No | _Empty string_ | _string_ | -| `safety_options` | Single space-separated or multi-line string of safety command line options. | No | _Empty string_ | _string_ | +| `pylint_options` | Single (space-separated) or multi-line string of pylint command line options.

**Note**: This is only valid if `pylint_runs` is not defined.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | +| `pylint_runs` | Multi-line string with each line representing a separate pylint run/execution. This should include all desired options and targets.

**Important**: The inputs `pylint_options` and `pylint_targets` will be ignored if this is defined.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | +| `safety_options` | Single (space-separated) or multi-line string of safety command line options.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | ### Build distribution package @@ -116,7 +116,7 @@ General inputs for building the documentation: | `run_build_docs` | Run the `build package` test job. | No | `true` | _boolean_ | | `python_version_docs` | The Python version to use for the `build documentation` test job. | No | 3.9 | _string_ | | `relative` | Whether or not to use the locally installed Python package(s), and install it as an editable. | No | `false` | _boolean_ | -| `system_dependencies` | A single or multi-line string of Ubuntu APT packages to install prior to building the documentation. | No | _Empty string_ | _string_ | +| `system_dependencies` | A single (space-separated) or multi-line string of Ubuntu APT packages to install prior to building the documentation.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | | `warnings_as_errors` | Build the documentation in 'strict' mode, treating warnings as errors.

**Important**: If this is set to `false`, beware that the documentation may _not_ be rendered or built as one may have intended.

Default: `true`. | No | `true` | _boolean_ | | `use_mkdocs` | Whether or not to build the documentation using the MkDocs framework. Mutually exclusive with `use_sphinx`. | No | `false` | _boolean_ | | `use_sphinx` | Whether or not to build the documentation using the Sphinx framework. Mutually exclusive with `use_mkdocs`. | No | `false` | _boolean_ | @@ -128,13 +128,13 @@ MkDocs-specific inputs: | `update_python_api_ref` | Whether or not to update the Python API documentation reference.

**Note**: If this is `true`, `package_dirs` is _required_. | No | `true` | _boolean_ | | `update_docs_landing_page` | Whether or not to update the documentation landing page. The landing page will be based on the root README.md file. | No | `true` | _boolean_ | | `install_extras` | Any extras to install from the local repository through 'pip'. Must be encapsulated in square parentheses (`[]`) and be separated by commas (`,`) without any spaces.

**Example**: `'[dev,docs]'`. | No | _Empty string_ | _string_ | -| `package_dirs` | A single or multi-line string of path to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation.

**Example**: `'src/my_package'`. | **Yes, if `update_python_api_ref` is `true` (default)** | _Empty string_ | _string_ | -| `exclude_dirs` | A single or multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories. | No | \_\_pycache\_\_ | _string_ | -| `exclude_files` | A single or multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files. | No | \_\_init\_\_.py | _string_ | -| `full_docs_dirs` | A single or multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed. | No | _Empty string_ | _string_ | -| `full_docs_files` | A single or multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed. | No | _Empty string_ | _string_ | -| `special_file_api_ref_options` | A single or multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation.
Example: `my_module/py_file.py,show_bases:false`.

Encapsulate the value in double quotation marks (`"`) if including spaces ( ).

**Important**: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., `"my_package/my_module/py_file.py,show_bases: false"`. | No | _Empty string_ | _string_ | -| `landing_page_replacements` | A single or multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list _always_ includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`. | No | (LICENSE),(LICENSE.md) | _string_ | +| `package_dirs` | A multi-line string of path to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation.

**Example**: `'src/my_package'`.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | **Yes, if `update_python_api_ref` is `true` (default)** | _Empty string_ | _string_ | +| `exclude_dirs` | A multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | \_\_pycache\_\_ | _string_ | +| `exclude_files` | A multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | \_\_init\_\_.py | _string_ | +| `full_docs_dirs` | A multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | +| `full_docs_files` | A multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | +| `special_file_api_ref_options` | A multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation.
Example: `my_module/py_file.py,show_bases:false`.

Encapsulate the value in double quotation marks (`"`) if including spaces ( ).

**Important**: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., `"my_package/my_module/py_file.py,show_bases: false"`.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | +| `landing_page_replacements` | A multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list _always_ includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | (LICENSE),(LICENSE.md) | _string_ | | `landing_page_replacement_separator` | String to separate a mapping's 'old' to 'new' parts. Defaults to a comma (`,`). | No | , | _string_ | | `debug` | Whether to do print extra debug statements. | No | `false` | _boolean_ | @@ -142,7 +142,7 @@ Sphinx-specific inputs: | **Name** | **Description** | **Required** | **Default** | **Type** | |:--- |:--- |:---:|:---:|:---:| -| `sphinx-build_options` | Single or multi-line string of command-line options to use when calling `sphinx-build`.

**Note**: The `-W` option will be added if `warnings_as_errors` is `true` (default). | No | _Empty string_ | _string_ | +| `sphinx-build_options` | Single (space-separated) or multi-line string of command-line options to use when calling `sphinx-build`.

**Note**: The `-W` option will be added if `warnings_as_errors` is `true` (default).

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | | `docs_folder` | The path to the root documentation folder relative to the repository root. | No | docs | _string_ | | `build_target_folder` | The path to the target folder for the documentation build relative to the repository root. | No | site | _string_ | @@ -211,6 +211,8 @@ jobs: Here follows the full list of inputs available for this workflow. However, it is recommended to instead refer to the job-specific tables of inputs when considering which inputs to provide. +See also [General information](index.md#general-information). + | **Name** | **Description** | **Required** | **Default** | **Type** | |:--- |:--- |:---:|:---:|:---:| | `install_extras` | Any extras to install from the local repository through 'pip'. Must be encapsulated in square parentheses (`[]`) and be separated by commas (`,`) without any spaces.

Example: `'[dev,pre-commit]'`. | No | _Empty string_ | _string_ | @@ -219,28 +221,28 @@ However, it is recommended to instead refer to the job-specific tables of inputs | `run_pylint` | Run the `pylint` test job. | No | `true` | _boolean_ | | `run_safety` | Run the `safety` test job. | No | `true` | _boolean_ | | `pylint_targets` | Space-separated string of pylint file and folder targets.

**Note**: This is only valid if `pylint_runs` is not defined. | **Yes, if `pylint_runs` is not defined** | _Empty string_ | _string_ | -| `pylint_options` | Single space-separated or multi-line string of pylint command line options.

**Note**: This is only valid if `pylint_runs` is not defined. | No | _Empty string_ | _string_ | +| `pylint_options` | Single (space-separated) or multi-line string of pylint command line options.

**Note**: This is only valid if `pylint_runs` is not defined. | No | _Empty string_ | _string_ | | `pylint_runs` | Single or multi-line string with each line representing a separate pylint run/execution. This should include all desired options and targets.

**Important**: The inputs `pylint_options` and `pylint_targets` will be ignored if this is defined. | No | _Empty string_ | _string_ | -| `safety_options` | Single space-separated or multi-line string of safety command line options. | No | _Empty string_ | _string_ | +| `safety_options` | Single (space-separated) or multi-line string of safety command line options. | No | _Empty string_ | _string_ | | `run_build_package` | Run the `build package` test job. | No | `true` | _boolean_ | | `build_libs` | A space-separated list of packages to install via PyPI (`pip install`). | No | _Empty string_ | _string_ | | `build_cmd` | The package build command, e.g., `'flit build'` or `'python -m build'` (default). | No | `python -m build` | _string_ | | `run_build_docs` | Run the `build package` test job. | No | `true` | _boolean_ | | `python_version_docs` | The Python version to use for the `build documentation` test job. | No | 3.9 | _string_ | | `relative` | Whether or not to use the locally installed Python package(s), and install it as an editable. | No | `false` | _boolean_ | -| `system_dependencies` | A single or multi-line string of Ubuntu APT packages to install prior to building the documentation. | No | _Empty string_ | _string_ | +| `system_dependencies` | A single (space-separated) or multi-line string of Ubuntu APT packages to install prior to building the documentation. | No | _Empty string_ | _string_ | | `warnings_as_errors` | Build the documentation in 'strict' mode, treating warnings as errors.

**Important**: If this is set to `false`, beware that the documentation may _not_ be rendered or built as one may have intended.

Default: `true`. | No | `true` | _boolean_ | | `use_mkdocs` | Whether or not to build the documentation using the MkDocs framework. Mutually exclusive with `use_sphinx`. | No | `false` | _boolean_ | | `use_sphinx` | Whether or not to build the documentation using the Sphinx framework. Mutually exclusive with `use_mkdocs`. | No | `false` | _boolean_ | | `update_python_api_ref` | Whether or not to update the Python API documentation reference.

**Note**: If this is `true`, `package_dirs` is _required_. | No | `true` | _boolean_ | | `update_docs_landing_page` | Whether or not to update the documentation landing page. The landing page will be based on the root README.md file. | No | `true` | _boolean_ | -| `package_dirs` | A single or multi-line string of path to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation.

**Example**: `'src/my_package'`. | **Yes, if `update_python_api_ref` is `true` (default)** | _Empty string_ | _string_ | -| `exclude_dirs` | A single or multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories. | No | \_\_pycache\_\_ | _string_ | -| `exclude_files` | A single or multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files. | No | \_\_init\_\_.py | _string_ | -| `full_docs_dirs` | A single or multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed. | No | _Empty string_ | _string_ | -| `full_docs_files` | A single or multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed. | No | _Empty string_ | _string_ | -| `special_file_api_ref_options` | A single or multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation.
Example: `my_module/py_file.py,show_bases:false`.

Encapsulate the value in double quotation marks (`"`) if including spaces ( ).

**Important**: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., `"my_package/my_module/py_file.py,show_bases: false"`. | No | _Empty string_ | _string_ | -| `landing_page_replacements` | A single or multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list _always_ includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`. | No | (LICENSE),(LICENSE.md) | _string_ | +| `package_dirs` | A multi-line string of path to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation.

**Example**: `'src/my_package'`. | **Yes, if `update_python_api_ref` is `true` (default)** | _Empty string_ | _string_ | +| `exclude_dirs` | A multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories. | No | \_\_pycache\_\_ | _string_ | +| `exclude_files` | A multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`.

**Important**: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files. | No | \_\_init\_\_.py | _string_ | +| `full_docs_dirs` | A multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed. | No | _Empty string_ | _string_ | +| `full_docs_files` | A multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed. | No | _Empty string_ | _string_ | +| `special_file_api_ref_options` | A multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation.
Example: `my_module/py_file.py,show_bases:false`.

Encapsulate the value in double quotation marks (`"`) if including spaces ( ).

**Important**: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., `"my_package/my_module/py_file.py,show_bases: false"`. | No | _Empty string_ | _string_ | +| `landing_page_replacements` | A multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list _always_ includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`. | No | (LICENSE),(LICENSE.md) | _string_ | | `landing_page_replacement_separator` | String to separate a mapping's 'old' to 'new' parts. Defaults to a comma (`,`). | No | , | _string_ | | `debug` | Whether to do print extra debug statements. | No | `false` | _boolean_ | | `sphinx-build_options` | Single or multi-line string of command-line options to use when calling `sphinx-build`.

**Note**: The `-W` option will be added if `warnings_as_errors` is `true` (default). | No | _Empty string_ | _string_ | diff --git a/docs/workflows/ci_update_dependencies.md b/docs/workflows/ci_update_dependencies.md index 8b2ed35c..370868c5 100644 --- a/docs/workflows/ci_update_dependencies.md +++ b/docs/workflows/ci_update_dependencies.md @@ -37,7 +37,7 @@ There are no expectations of the repo when using this workflow. | `default_repo_branch` | The branch name of the repository's default branch. More specifically, the branch the PR should target. | No | main | _string_ | | `pr_body_file` | Relative path to PR body file from the root of the repository.

Example: `'.github/utils/pr_body_update_deps.txt'`. | No | _Empty string_ | _string_ | | `pr_labels` | A comma separated list of strings of GitHub labels to use for the created PR. | No | _Empty string_ | _string_ | -| `extra_to_dos` | A multi-line string (insert `\n` to create line breaks) with extra 'to do' checks. Should start with `- [ ] `. | No | _Empty string_ | _string_ | +| `extra_to_dos` | A multi-line string (insert `\n` to create line breaks) with extra 'to do' checks. Should start with `- [ ] `.

See also [Single vs multi-line input](index.md#single-vs-multi-line-input). | No | _Empty string_ | _string_ | | `update_pre-commit` | Whether or not to update pre-commit hooks as part of creating the PR. | No | `false` | _boolean_ | | `python_version` | The Python version to use for the workflow.

**Note**: This is only relevant if `update_pre-commit` is `true`. | No | 3.9 | _string_ | | `install_extras` | Any extras to install from the local repository through 'pip'. Must be encapsulated in square parentheses (`[]`) and be separated by commas (`,`) without any spaces.

Example: `'[dev,pre-commit]'`.

**Note**: This is only relevant if `update_pre-commit` is `true`. | No | _Empty string_ | _string_ | diff --git a/docs/workflows/index.md b/docs/workflows/index.md index 498ac859..79ef2684 100644 --- a/docs/workflows/index.md +++ b/docs/workflows/index.md @@ -1,5 +1,7 @@ # GitHub Actions callable/reusable Workflows + + This section contains all the available callable/reusable workflows: - [CD - Release (`cd_release.yml`)](./cd_release.md) @@ -8,3 +10,104 @@ This section contains all the available callable/reusable workflows: - [CI - Check pyproject.toml dependencies (`ci_check_pyproject_dependencies.yml`)](./ci_check_pyproject_dependencies.md) - [CI - Tests (`ci_tests.yml`)](./ci_tests.md) - [CI - Update dependencies PR (`ci_update_dependencies.yml`)](./ci_update_dependencies.md) + +## General information + +### Single vs multi-line input + +For inputs specifying single or multi-line input values, the following rules apply: + +1. If only "multi-line" is mentioned, it means that the input value _can_ be a single line, but it **must not** be a multi-valued single line (see [examples below](#multi-line-input)). +2. If only "single" is mentioned, it means that the input value **must** be a single line (the workflow might fail if it is not). + + !!! note + + There is currently no input parameter that is explicitly single line only. + Instead, one should consider the input parameter to be single line only if it is not explicitly mentioned as multi-line. + +3. If both "single" and "multi-line" is mentioned, it means that multiple values can be specified, but they must be separated _either_ over several, separate lines **or** within a single line by a space. + +Here are some examples: + +#### Multi-line input + +**Accepted** input styles: + +```yaml +# Two separate version update changes: +version_update_changes: | + "file/path,pattern,replacement string" + "another/file/path,pattern,replacement string" + +# A single version update change +version_update_changes: | + "file/path,pattern,replacement string" + +# A single version update change, different formatting for input +version_update_changes: "file/path,pattern,replacement string" +``` + +**Disallowed** input styles: + +```yaml +# Two separate version update changes: +version_update_changes: "file/path,pattern,replacement string another/file/path,pattern,replacement string" +``` + +#### Single line input + +**Accepted** input styles: + +```yaml +# A single git username: +git_username: "Casper Welzel Andersen" + +# A single git username, different formatting for input +git_username: | + "Casper Welzel Andersen" +``` + +**Disallowed** input styles: + +```yaml +# Two separate git usernames: +git_username: | + "Casper Welzel Andersen" + "Francesca L. Bleken" + +# Two separate git usernames, different formatting for input +git_username: "Casper Welzel Andersen Francesca L. Bleken" +``` + +!!! warning + + It is important to note that the disallowed examples will work without fault in this case (might not always be true for other parameters). + But the git username will be a single string, combining the names in succession, instead of being two separate values. + +#### Single or multi-line input + +**Accepted** input styles: + +```yaml +# A single system dependency: +system_dependencies: "graphviz" + +# A single system dependency, different formatting for input +system_dependencies: | + "graphviz" + +# Two separate system dependencies: +system_dependencies: | + "graphviz" + "Sphinx" + +# Two separate system dependencies, different formatting for input +system_dependencies: "graphviz Sphinx" +``` + +**Disallowed** input styles: + +```yaml +# Use of custom separator: +system_dependencies: "graphviz,Sphinx" +```