Skip to content

Commit

Permalink
Add link to doc in GithubComment reporter (#4)
Browse files Browse the repository at this point in the history 
* Add link to doc in GithubComment reporter

* Generate MD doc for descriptors

* #readme

* Add link to Artifacts on error cells

* markdownlint disable for doc mds
  • Loading branch information
@nvuillam
nvuillam authored Oct 21, 2020
1 parent 351a490 commit 399d672
Show file tree
Hide file tree
Showing 52 changed files with 1,443 additions and 143 deletions.
142 changes: 114 additions & 28 deletions .automation/build.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -142,13 +142,20 @@ class {lang_lower}_{linter_name_lower}_test(TestCase, LinterTestRoot):


# Automatically generate README linters table and a MD file for each linter
def generate_linter_documentation():
def generate_documentation():
descriptor_files = megalinter.utils.list_descriptor_files()
linters_by_type = {'language': [], 'format': [], 'tooling_format': []}
descriptors = []
for descriptor_file in descriptor_files:
descriptor = megalinter.utils.build_descriptor_info(descriptor_file)
descriptors += [descriptor]
descriptor_linters = megalinter.utils.build_descriptor_linters(
descriptor_file)
linters_by_type[descriptor_linters[0].descriptor_type] += descriptor_linters
# Build descriptors documentation
for descriptor in descriptors:
generate_descriptor_documentation(descriptor)
# Build README linters table and linters documentation
linters_tables_md = []
process_type(linters_by_type, 'language', 'Languages', linters_tables_md)
process_type(linters_by_type, 'format', 'Formats', linters_tables_md)
Expand All @@ -161,7 +168,78 @@ def generate_linter_documentation():
"<!-- linters-table-end -->", linters_tables_md_str)


# Build a MD table for a type of linter (language, format, tooling_format )SSS
# Generate a MD page for a descriptor (language, format, tooling_format)
def generate_descriptor_documentation(descriptor):
descriptor_md = [
"<!-- markdownlint-disable MD003 MD020 MD033 MD041 -->",
"<!-- Generated by .automation/build.py, please do not update manually -->"
]
# Title
descriptor_md += [f"# {descriptor.get('descriptor_label', descriptor.get('descriptor_id'))}",
""]
# Criteria used by the descriptor to identify files to lint
descriptor_md += [
"## Linted files",
""]
if descriptor.get('active_only_if_file_found', None) is not None:
descriptor_md += [
f"- Activated only if file is found: `{descriptor.get('active_only_if_file_found')}`"]
if len(descriptor.get('file_extensions', [])) > 0:
descriptor_md += ['- File extensions:']
for file_extension in descriptor.get('file_extensions'):
descriptor_md += [f" - `{file_extension}`"]
descriptor_md += [""]
if len(descriptor.get('file_names', [])) > 0:
descriptor_md += ['- File names:']
for file_name in descriptor.get('file_names'):
descriptor_md += [f" - `{file_name}`"]
descriptor_md += [""]
if len(descriptor.get('file_contains', [])) > 0:
descriptor_md += ['- Detected file content:']
for file_contains_expr in descriptor.get('file_contains'):
descriptor_md += [f" - `{file_contains_expr}`"]
descriptor_md += [""]
# Mega-linter variables
descriptor_md += [
"## Mega-linter configuration",
"",
"| Variable | Description | Default value |",
"| ----------------- | -------------- | -------------- |"]
descriptor_md += [
f"| {descriptor.get('descriptor_id')}_FILTER_REGEX_INCLUDE | Custom regex including filter | |",
f"| {descriptor.get('descriptor_id')}_FILTER_REGEX_EXCLUDE | Custom regex excluding filter | |",
""
]
# List of linters
lang_lower = descriptor.get('descriptor_id').lower()
descriptor_md += [
"## Linters",
"",
"| Linter | Configuration key |",
"| ------ | ----------------- |"]
for linter in descriptor.get('linters', []):
linter_name_lower = linter.get('linter_name').lower().replace('-', '_')
linter_doc_url = f"{DOCS_URL_DESCRIPTORS_ROOT}/{lang_lower}_{linter_name_lower}.md"
descriptor_md += [
f"| [{linter.get('linter_name')}]({doc_url(linter_doc_url)}) | "
f"[{linter.get('name', descriptor.get('descriptor_id'))}]({doc_url(linter_doc_url)}) |"]
# Add install info
if descriptor.get('install', None) is not None:
descriptor_md += ["",
"## Behind the scenes"]
descriptor_md += ["",
"### Installation",
""]
descriptor_md += get_install_md(descriptor)
# Write MD file
file = open(
f"{REPO_HOME}/docs/descriptors/{lang_lower}.md", 'w')
file.write("\n".join(descriptor_md) + "\n")
file.close()
logging.info('Updated ' + file.name)


# Build a MD table for a type of linter (language, format, tooling_format), and a MD file for each linter
def process_type(linters_by_type, type1, type_label, linters_tables_md):
linters_tables_md += [
f"### {type_label}",
Expand All @@ -173,7 +251,8 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
for linter in descriptor_linters:
lang_lower = linter.descriptor_id.lower()
linter_name_lower = linter.linter_name.lower().replace('-', '_')
# Append in general linter tables

# Append in general linter tables (for README)
descriptor_label = f"**{linter.descriptor_label}** ({linter.descriptor_id})" \
if hasattr(linter, 'descriptor_label') else f"**{linter.descriptor_id}**"
if prev_lang != linter.descriptor_id and \
Expand All @@ -186,12 +265,14 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
'', '', descriptor_label, 32)
else:
icon_html = '<!-- -->'
descriptor_id_cell = descriptor_label if prev_lang != linter.descriptor_id else ''
descriptor_url = doc_url(f"{DOCS_URL_DESCRIPTORS_ROOT}/{lang_lower}.md")
descriptor_id_cell = f"[{descriptor_label}]({descriptor_url})" if prev_lang != linter.descriptor_id else ''
prev_lang = linter.descriptor_id
linter_doc_url = f"{DOCS_URL_DESCRIPTORS_ROOT}/{lang_lower}_{linter_name_lower}.md"
linters_tables_md += [
f"| {icon_html} | {descriptor_id_cell} | [{linter.linter_name}]({doc_url(linter_doc_url)})"
f"| [{linter.name}]({doc_url(linter_doc_url)}) |"]

# Build individual linter doc
linter_doc_md = [
"<!-- markdownlint-disable MD033 MD041 -->",
Expand Down Expand Up @@ -312,29 +393,7 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
""]
item = vars(linter)
merge_install_attr(item)
if 'dockerfile' in item['install']:
linter_doc_md += ["- Dockerfile commands :"]
linter_doc_md += ['```dockerfile']
linter_doc_md += item['install']['dockerfile']
linter_doc_md += ['```',
""]
if 'apk' in item['install']:
linter_doc_md += ["- APK packages (Linux):"]
linter_doc_md += md_package_list(item['install']['apk'], " ",
"https://pkgs.alpinelinux.org/packages?branch=edge&name=")
if 'npm' in item['install']:
linter_doc_md += ["- NPM packages (node.js):"]
linter_doc_md += md_package_list(item['install']
['npm'], " ", "https://www.npmjs.com/package/")
if 'pip' in item['install']:
linter_doc_md += ["- PIP packages (Python):"]
linter_doc_md += md_package_list(item['install']
['pip'], " ", "https://pypi.org/project/")
if 'gem' in item['install']:
linter_doc_md += ["- GEM packages (Ruby) :"]
linter_doc_md += md_package_list(item['install']
['gem'], " ", "https://rubygems.org/gems/")

linter_doc_md += get_install_md(item)
linter_doc_md += [
"",
"### Linter web site",
Expand All @@ -350,6 +409,33 @@ def process_type(linters_by_type, type1, type_label, linters_tables_md):
return linters_tables_md


def get_install_md(item):
linter_doc_md = []
if 'dockerfile' in item['install']:
linter_doc_md += ["- Dockerfile commands :"]
linter_doc_md += ['```dockerfile']
linter_doc_md += item['install']['dockerfile']
linter_doc_md += ['```',
""]
if 'apk' in item['install']:
linter_doc_md += ["- APK packages (Linux):"]
linter_doc_md += md_package_list(item['install']['apk'], " ",
"https://pkgs.alpinelinux.org/packages?branch=edge&name=")
if 'npm' in item['install']:
linter_doc_md += ["- NPM packages (node.js):"]
linter_doc_md += md_package_list(item['install']
['npm'], " ", "https://www.npmjs.com/package/")
if 'pip' in item['install']:
linter_doc_md += ["- PIP packages (Python):"]
linter_doc_md += md_package_list(item['install']
['pip'], " ", "https://pypi.org/project/")
if 'gem' in item['install']:
linter_doc_md += ["- GEM packages (Ruby) :"]
linter_doc_md += md_package_list(item['install']
['gem'], " ", "https://rubygems.org/gems/")
return linter_doc_md


def doc_url(href):
if href.startswith('https://github') and "#" not in href:
return href + "#readme"
Expand Down Expand Up @@ -450,5 +536,5 @@ def copy_files():
validate_descriptors()
generate_dockerfile()
generate_linter_test_classes()
generate_linter_documentation()
generate_documentation()
copy_files()
2 changes: 1 addition & 1 deletion .github/workflows/mega-linter.yml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
# Mega-Linter GitHub Action configuration file
# More info at https://github.com/nvuillam/mega-linter#mega-linter
# More info at https://github.com/nvuillam/mega-linter#readme
name: Mega-Linter

# Start lint on any push and on pull requests
Expand Down
Loading

0 comments on commit 399d672

Please sign in to comment.