chg: [doc] shorten README + link to githubio

documentation/generate_documentation.py

@@ -7,6 +7,7 @@
 module_types = ['expansion', 'export_mod', 'import_mod', 'action_mod']
 titles = ['Expansion Modules', 'Export Modules', 'Import Modules', 'Action Modules']
 githublink = 'https://github.com/MISP/misp-modules/tree/main/misp_modules/modules'
+githubiolink = 'https://misp.github.io/misp-modules'
 
 moduleinfo_to_ignore = ['module-type', 'author', 'version']
 
@@ -63,6 +64,7 @@ def generate_doc(module_type, root_path, logo_path='logos'):
             markdown.append(f"\n<img src={logo} height=60>\n")
         if 'description' in moduleinfo:
             markdown.append(f"\n{moduleinfo.pop('description')}\n")
+        markdown.append(f"[[source code]({githubref})]\n")
         if 'features' in moduleinfo:
             markdown.append(get_single_value('features', str(moduleinfo.pop('features')).replace('\n', '\n>')))
         for field, value in sorted(moduleinfo.items()):
@@ -78,27 +80,26 @@ def generate_doc(module_type, root_path, logo_path='logos'):
 
 def generate_index_doc(module_type, root_path):
     markdown = []
-    githubpath = f'{githublink}/{module_type}'
     for module_name, moduleinfo in get_all_moduleinfo()[module_type].items():
         module_name_pretty = moduleinfo.get('name')
         if module_name_pretty == '':
             module_name_pretty = module_name
 
-        githubref = f'{githubpath}/{module_name}.py'
+        anchor_ref = f"{githubiolink}/{module_type}/#{module_name_pretty.replace(' ', '-').lower()}"
         description_without_newlines = moduleinfo.get("description").replace('\n', ' ')
-        markdown.append(f'* [{module_name_pretty}]({githubref}) - {description_without_newlines}\n')
+        markdown.append(f'* [{module_name_pretty}]({anchor_ref}) - {description_without_newlines}\n')
     return markdown
 
 
 def get_single_value(field, value):
-    return f"- **{field}**:\n>{value}\n"
+    return f"\n- **{field}**:\n>{value}\n"
 
 
 def handle_list(field, values):
     if len(values) == 1:
         return get_single_value(field, values[0])
     values = '\n> - '.join(values)
-    return f"- **{field}**:\n> - {values}\n"
+    return f"\n- **{field}**:\n> - {values}\n"
 
 
 def write_doc_for_readme(root_path):
@@ -150,34 +151,19 @@ def update_readme(root_path):
     new_doc = []
     skip = False
     for line in old_readme:
-        if skip and not line.startswith('# Existing MISP modules') and not line.startswith('# How to add your own MISP modules?') and not line.startswith('# Installation'):  # find next title
+        if skip and not line.startswith('# List of MISP modules'):  # find next title
             continue   # skip lines, as we're in the block that we're auto-generating
 
         new_doc.append(line)
 
-        if line.startswith('# Existing MISP modules'):
+        if line.startswith('# List of MISP modules'):
             skip = True
             # generate the updated content
             for _path, title in zip(module_types, titles):
                 new_doc.append(f'\n## {title}\n')
                 new_doc.extend(generate_index_doc(_path, root_path))
             new_doc.append('\n\n')
 
-        elif line.startswith('# How to add your own MISP modules?'):
-            skip = True
-            # copy over the contribute.md file
-            with open(root_path / 'documentation' / 'mkdocs' / 'contribute.md', 'r') as f:
-                f.readline()  # skip the title
-                new_doc.extend(f.readlines())
-
-        elif line.startswith('# Installation'):
-            skip = True
-            new_doc.append('\n')
-            # copy over the install.md file
-            with open(root_path / 'documentation' / 'mkdocs' / 'install.md', 'r') as f:
-                new_doc.extend(f.readlines())
-            new_doc.append('\n')
-
     with open(root_path / 'README.md', 'w') as w:
         w.write(''.join(new_doc))
     pass

documentation/mkdocs/action_mod.md

@@ -2,8 +2,11 @@
 #### [Mattermost](https://github.com/MISP/misp-modules/tree/main/misp_modules/modules/action_mod/mattermost.py)
 
 Simplistic module to send message to a Mattermost channel.
+[[source code](https://github.com/MISP/misp-modules/tree/main/misp_modules/modules/action_mod/mattermost.py)]
+
 - **features**:
 >
+
 - **config**:
 >{'params': {'mattermost_hostname': {'type': 'string', 'description': 'The Mattermost domain or URL', 'value': 'example.mattermost.com'}, 'bot_access_token': {'type': 'string', 'description': 'Access token generated when you created the bot account'}, 'channel_id': {'type': 'string', 'description': 'The channel you added the bot to'}, 'message_template': {'type': 'large_string', 'description': 'The template to be used to generate the message to be posted', 'value': 'The **template** will be rendered using *Jinja2*!', 'jinja_supported': True}}, 'blocking': False, 'support_filters': True, 'expect_misp_core_format': False}
 
@@ -12,8 +15,11 @@ Simplistic module to send message to a Mattermost channel.
 #### [Slack](https://github.com/MISP/misp-modules/tree/main/misp_modules/modules/action_mod/slack.py)
 
 Simplistic module to send messages to a Slack channel.
+[[source code](https://github.com/MISP/misp-modules/tree/main/misp_modules/modules/action_mod/slack.py)]
+
 - **features**:
 >
+
 - **config**:
 >{'params': {'slack_bot_token': {'type': 'string', 'description': 'The Slack bot token generated when you created the bot account'}, 'channel_id': {'type': 'string', 'description': 'The channel ID you want to post messages to'}, 'message_template': {'type': 'large_string', 'description': 'The template to be used to generate the message to be posted', 'value': 'The **template** will be rendered using *Jinja2*!', 'jinja_supported': True}}, 'blocking': False, 'support_filters': True, 'expect_misp_core_format': False}
 
@@ -22,8 +28,11 @@ Simplistic module to send messages to a Slack channel.
 #### [Test action](https://github.com/MISP/misp-modules/tree/main/misp_modules/modules/action_mod/testaction.py)
 
 This module is merely a test, always returning true. Triggers on event publishing.
+[[source code](https://github.com/MISP/misp-modules/tree/main/misp_modules/modules/action_mod/testaction.py)]
+
 - **features**:
 >
+
 - **config**:
 >{'params': {'foo': {'type': 'string', 'description': 'blablabla', 'value': 'xyz'}, 'Data extraction path': {'type': 'hash_path', 'description': 'Only post content extracted from this path', 'value': 'Attribute.{n}.AttributeTag.{n}.Tag.name'}}, 'blocking': False, 'support_filters': False, 'expect_misp_core_format': False}
 

documentation/mkdocs/contribute.md

@@ -384,7 +384,7 @@ cd ../
 
 In order to provide documentation about some modules that require specific input / output / configuration, the [index.md](docs/index.md) file within the [docs](docs) directory contains detailed information about the general purpose, requirements, features, input and ouput of each of these modules:
 
-- ***description** - quick description of the general purpose of the module, as the one given by the moduleinfo
+- **description** - quick description of the general purpose of the module, as the one given by the moduleinfo
 - **requirements** - special libraries needed to make the module work
 - **features** - description of the way to use the module, with the required MISP features to make the module give the intended result
 - **references** - link(s) giving additional information about the format concerned in the module