Skip to content

Commit

Permalink
Improve documentation pages split (#2688)
Browse files Browse the repository at this point in the history 
* Split install into different pages

* Update build

* Build

* Config split

* Build

* typos

* [MegaLinter] Apply linters fixes

* Manage deprecation in JSON Schema

* Mark variables as deprecated

* Removed

* format

* [MegaLinter] Apply linters fixes

* Fix generation

* formatting

* Formatting

* Fix links

* build doc

* [MegaLinter] Apply linters fixes

---------

Co-authored-by: nvuillam <nvuillam@users.noreply.github.com>
  • Loading branch information
@nvuillam
nvuillam and nvuillam authored May 26, 2023
1 parent a1adf83 commit 86a8394
Show file tree
Hide file tree
Showing 33 changed files with 1,339 additions and 219 deletions.
135 changes: 100 additions & 35 deletions .automation/build.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -118,6 +118,17 @@
"vscode": {"label": "Visual Studio Code", "url": "https://code.visualstudio.com/"},
}

DEPRECATED_LINTERS = [
"CREDENTIALS_SECRETLINT", # Removed in v6
"DOCKERFILE_DOCKERFILELINT", # Removed in v6
"GIT_GIT_DIFF", # Removed in v6
"PHP_BUILTIN", # Removed in v6
"KUBERNETES_KUBEVAL", # Removed in v7
"REPOSITORY_GOODCHECK", # Removed in v7
"SPELL_MISSPELL", # Removed in v7
"TERRAFORM_CHECKOV", # Removed in v7
]

DESCRIPTORS_FOR_BUILD_CACHE = None


Expand Down Expand Up @@ -1135,7 +1146,9 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
linter_doc_md += [f"# {linter.linter_name}\n{md_individual_extra}"]

# Indicate that a linter is disabled in this version
title_prefix = ""
if hasattr(linter, "deprecated") and linter.deprecated is True:
title_prefix = "(deprecated) "
linter_doc_md += [""]
linter_doc_md += ["> This linter has been deprecated.", ">"]

Expand Down Expand Up @@ -1314,15 +1327,15 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
{
"$id": f"#/properties/{linter.name}_FILTER_REGEX_INCLUDE",
"type": "string",
"title": f"{linter.name}: Including Regex",
"title": f"{title_prefix}{linter.name}: Including Regex",
},
],
[
f"{linter.name}_FILTER_REGEX_EXCLUDE",
{
"$id": f"#/properties/{linter.name}_FILTER_REGEX_EXCLUDE",
"type": "string",
"title": f"{linter.name}: Excluding Regex",
"title": f"{title_prefix}{linter.name}: Excluding Regex",
},
],
]
Expand Down Expand Up @@ -1362,7 +1375,7 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
{
"$id": f"#/properties/{linter.name}_CLI_LINT_MODE",
"type": "string",
"title": f"{linter.name}: Override default cli lint mode",
"title": f"{title_prefix}{linter.name}: Override default cli lint mode",
"default": linter.cli_lint_mode,
"enum": enum,
},
Expand Down Expand Up @@ -1395,7 +1408,10 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
{
"$id": f"#/properties/{linter.name}_FILE_EXTENSIONS",
"type": "array",
"title": f"{linter.name}: Override descriptor/linter matching files extensions",
"title": (
title_prefix
+ f"{linter.name}: Override descriptor/linter matching files extensions"
),
"examples:": [".py", ".myext"],
"items": {"type": "string"},
},
Expand All @@ -1405,7 +1421,10 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
{
"$id": f"#/properties/{linter.name}_FILE_NAMES_REGEX",
"type": "array",
"title": f"{linter.name}: Override descriptor/linter matching file name regex",
"title": (
title_prefix
+ f"{linter.name}: Override descriptor/linter matching file name regex"
),
"examples": ["Dockerfile(-.+)?", "Jenkinsfile"],
"items": {"type": "string"},
},
Expand All @@ -1430,7 +1449,7 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
{
"$id": f"#/properties/{linter.name}_ARGUMENTS",
"type": ["array", "string"],
"title": f"{linter.name}: Custom arguments",
"title": f"{title_prefix}{linter.name}: Custom arguments",
"description": f"{linter.name}: User custom arguments to add in linter CLI call",
"examples:": ["--foo", "bar"],
"items": {"type": "string"},
Expand All @@ -1441,7 +1460,10 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
{
"$id": f"#/properties/{linter.name}_PRE_COMMANDS",
"type": "array",
"title": f"{linter.name}: Define or override a list of bash commands to run before the linter",
"title": (
title_prefix
+ f"{linter.name}: Define or override a list of bash commands to run before the linter"
),
"examples": [
[
{
Expand All @@ -1459,7 +1481,10 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
{
"$id": f"#/properties/{linter.name}_POST_COMMANDS",
"type": "array",
"title": f"{linter.name}: Define or override a list of bash commands to run after the linter",
"title": (
title_prefix
+ f"{linter.name}: Define or override a list of bash commands to run after the linter"
),
"examples": [
[
{
Expand All @@ -1478,7 +1503,10 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
"$id": f"#/properties/{linter.name}_DISABLE_ERRORS",
"type": "boolean",
"default": False,
"title": f"{linter.name}: Linter doesn't make MegaLinter fail even if errors are found",
"title": (
title_prefix
+ f"{linter.name}: Linter doesn't make MegaLinter fail even if errors are found"
),
},
],
[
Expand All @@ -1487,7 +1515,7 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
"$id": f"#/properties/{linter.name}_DISABLE_ERRORS_IF_LESS_THAN",
"type": "number",
"default": 0,
"title": f"{linter.name}: Maximum number of errors allowed",
"title": f"{title_prefix}{linter.name}: Maximum number of errors allowed",
},
],
[
Expand All @@ -1496,7 +1524,7 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
"$id": f"#/properties/{linter.name}_CLI_EXECUTABLE",
"type": "array",
"default": [linter.cli_executable],
"title": f"{linter.name}: CLI Executable",
"title": f"{title_prefix}{linter.name}: CLI Executable",
"items": {"type": "string"},
},
],
Expand All @@ -1518,7 +1546,7 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
{
"$id": f"#/properties/{linter.name}_CONFIG_FILE",
"type": "string",
"title": f"{linter.name}: Custom config file name",
"title": f"{title_prefix}{linter.name}: Custom config file name",
"default": linter.config_file_name,
"description": f"{linter.name}: User custom config file name if different from default",
},
Expand All @@ -1528,7 +1556,7 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
{
"$id": f"#/properties/{linter.name}_RULES_PATH",
"type": "string",
"title": f"{linter.name}: Custom config file path",
"title": f"{title_prefix}{linter.name}: Custom config file path",
"description": f"{linter.name}: Path where to find linter configuration file",
},
],
Expand Down Expand Up @@ -1556,7 +1584,7 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
{
"$id": f"#/properties/{linter.name}_DIRECTORY",
"type": "string",
"title": f"{linter.name}: Directory containing {linter.descriptor_id} files",
"title": f"{title_prefix}{linter.name}: Directory containing {linter.descriptor_id} files",
"default": linter.files_sub_directory,
},
],
Expand Down Expand Up @@ -2252,14 +2280,22 @@ def move_to_file(file_path, start, end, target_file, keep_in_source=False):
with open(file_path, "w", encoding="utf-8") as file:
file.write(file_content)
logging.info("Updated " + file.name + " between " + start + " and " + end)
bracket_content = (
bracket_content.replace("####", "#THREE#")
.replace("###", "#TWO#")
.replace("##", "#ONE#")
.replace("#THREE#", "###")
.replace("#TWO#", "##")
.replace("#ONE#", "#")
)
if "<!-- install-" in start or "<!-- config-" in start:
bracket_content = (
bracket_content.replace("####", "#TWO#")
.replace("###", "#ONE#")
.replace("#TWO#", "##")
.replace("#ONE#", "#")
)
else:
bracket_content = (
bracket_content.replace("####", "#THREE#")
.replace("###", "#TWO#")
.replace("##", "#ONE#")
.replace("#THREE#", "###")
.replace("#TWO#", "##")
.replace("#ONE#", "#")
)

if not os.path.isfile(target_file):
mdl_disable = "<!-- markdownlint-disable MD013 -->"
Expand Down Expand Up @@ -2291,7 +2327,14 @@ def replace_anchors_by_links(file_path, moves):
["formats", "supported-linters.md#formats"],
["tooling-formats", "supported-linters.md#tooling-formats"],
["other", "supported-linters.md#other"],
["apply-fixes", "configuration.md#apply-fixes"],
["apply-fixes", "config-apply-fixes.md"],
["installation", "install-assisted.md"],
["configuration", "config-file.md"],
["activation-and-deactivation", "config-activation.md"],
["filter-linted-files", "config-filtering.md"],
["pre-commands", "config-precommands.md"],
["post-commands", "config-postcommands.md"],
["environment-variables-security", "config-variables-security.md"],
]:
file_content_new = file_content_new.replace(f"(#{pair[0]})", f"({pair[1]})")
if file_content_new != file_content:
Expand Down Expand Up @@ -2357,8 +2400,27 @@ def finalize_doc_build():
# 'format',
# 'tooling-formats',
# 'other',
"installation",
"configuration",
"install-assisted",
"install-version",
"install-github",
"install-gitlab",
"install-azure",
"install-bitbucket",
"install-jenkins",
"install-concourse",
"install-drone",
"install-docker",
"install-locally",
"config-file",
"config-variables",
"config-activation",
"config-filtering",
"config-apply-fixes",
"config-linters",
"config-precommands",
"config-postcommands",
"config-variables-security",
"config-cli-lint-mode",
"reporters",
"flavors",
"badge",
Expand Down Expand Up @@ -2420,6 +2482,18 @@ def finalize_doc_build():
"<!-- table-of-contents-end -->",
"",
)
replace_in_file(
target_file,
"<!-- configuration-section-start -->",
"<!-- configuration-section-end -->",
"",
)
replace_in_file(
target_file,
"<!-- installation-section-start -->",
"<!-- installation-section-end -->",
"",
)
# Remove link to online doc
replace_in_file(
target_file,
Expand Down Expand Up @@ -2523,16 +2597,7 @@ def generate_json_schema_enums():
json_schema["definitions"]["enum_descriptor_keys"]["enum"] += ["CREDENTIALS", "GIT"]
json_schema["definitions"]["enum_linter_keys"]["enum"] = [x.name for x in linters]
# Deprecated linters
json_schema["definitions"]["enum_linter_keys"]["enum"] += [
"CREDENTIALS_SECRETLINT", # Removed in v6
"DOCKERFILE_DOCKERFILELINT", # Removed in v6
"GIT_GIT_DIFF", # Removed in v6
"PHP_BUILTIN", # Removed in v6
"KUBERNETES_KUBEVAL", # Removed in v7
"REPOSITORY_GOODCHECK", # Removed in v7
"SPELL_MISSPELL", # Removed in v7
"TERRAFORM_CHECKOV", # Removed in v7
]
json_schema["definitions"]["enum_linter_keys"]["enum"] += DEPRECATED_LINTERS
with open(CONFIG_JSON_SCHEMA, "w", encoding="utf-8") as outfile:
json.dump(json_schema, outfile, indent=2, sort_keys=True)
outfile.write("\n")
Expand Down
2 changes: 2 additions & 0 deletions .cspell.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -962,11 +962,13 @@
"pnpm",
"poptabs",
"posix",
"postcommands",
"posteriori",
"postgres",
"postvalid",
"prantlf",
"precommand",
"precommands",
"preemptible",
"preid",
"premption",
Expand Down
1 change: 1 addition & 0 deletions .mega-linter.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ DISABLE_LINTERS:
- JSON_PRETTIER
- REPOSITORY_GITLEAKS
- SPELL_PROSELINT
- SPELL_MISSPELL
DISABLE_ERRORS_LINTERS:
- PYTHON_BANDIT
- PYTHON_PYRIGHT
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ Note: Can be used with `oxsecurity/megalinter@beta` in your GitHub Action mega-l
- Exclude licenses from search results
- Automate External Plugins table generation using **.automation/plugins.yml** file
- Add `--stats` argument to `build.sh` to update docker pull stats only when requested (manually, or from CI job Auto-Update-Linters), by @echoix in [#2677](https://github.com/oxsecurity/megalinter/pull/2677)
- Manage deprecation in JSON Schema variables

- Linter versions upgrades
- [cfn-lint](https://github.com/aws-cloudformation/cfn-lint) from 0.76.1 to **0.76.2** on 2023-04-04
Expand Down
Loading

0 comments on commit 86a8394

Please sign in to comment.