Include module documentation files.

muppet/gather.py

@@ -13,6 +13,7 @@ from typing import (
 import json
 import os.path
 import hashlib
+from glob import glob
 from .puppet.strings import puppet_strings
 from .cache import Cache
 
@@ -34,6 +35,7 @@ class ModuleEntry:
     path: str
     strings_output: bytes
     metadata: dict[str, Any]
+    doc_files: list[str]
 
     def file(self, path: str) -> str:
         """Return the absolute path of a path inside the module."""
@@ -96,7 +98,13 @@ def get_module(cache: Cache,
     except FileNotFoundError:
         metadata = {}
 
-    return ModuleEntry(name, path, strings_data, metadata)
+    doc_files = glob(os.path.join(path, '*.md'))
+
+    return ModuleEntry(name=name,
+                       path=path,
+                       strings_output=strings_data,
+                       metadata=metadata,
+                       doc_files=doc_files)
 
 
 def get_modules(cache: Cache, dir: str) -> list[ModuleEntry]:

muppet/output.py

@@ -31,6 +31,7 @@ from .util import group_by
 from .puppet.strings import isprivate
 
 
+# TODO replace 'output' with base, or put this somewhere else
 pathlib.Path('output').mkdir(exist_ok=True)
 jinja = Environment(
     loader=FileSystemLoader('templates'),
@@ -193,10 +194,13 @@ def type_aliases_index(alias_list: list) -> IndexCategory:
 #     return {}
 
 
-def setup_module_index(base: str,
+def setup_module_index(*,
+                       base: str,
                        module: ModuleEntry,
                        data: dict[str, Any],
-                       path_base: str) -> None:
+                       path_base: str,
+                       doc_files: dict[str, str],
+                       ) -> None:
     """Create the index file for a specific module."""
     template = jinja.get_template('module_index.html')
 
@@ -219,7 +223,16 @@ def setup_module_index(base: str,
     with open(os.path.join(base, 'index.html'), 'w') as f:
         f.write(template.render(module_name=module.name,
                                 content=content,
-                                path_base=path_base))
+                                path_base=path_base,
+                                doc_files=doc_files.items()))
+
+
+GENERATED_MESSAGE = '<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n'
+"""
+REFERENCE.md files generated by Puppet Strings include this string on
+their third line. We use this to ignore auto-generated files, since we
+replace that output.
+"""
 
 
 def setup_module(base: str, module: ModuleEntry, *, path_base: str) -> None:
@@ -241,8 +254,6 @@ def setup_module(base: str, module: ModuleEntry, *, path_base: str) -> None:
         return
     data = json.loads(module.strings_output)
 
-    setup_module_index(path, module, data, path_base=path_base)
-
     for puppet_class in data['puppet_classes'] + data['defined_types']:
         # localpath = puppet_class['name'].split('::')
         localpath, _ = os.path.splitext(puppet_class['file'])
@@ -289,3 +300,36 @@ def setup_module(base: str, module: ModuleEntry, *, path_base: str) -> None:
     # data['data_type_aliases']
     # data['defined_types']
     # data['resource_types']
+
+    files: dict[str, str] = {}
+    for file in module.doc_files:
+        basename = os.path.basename(file)
+        if basename == 'REFERENCE.md':
+            with open(file) as f:
+                f.readline()
+                f.readline()
+                line3 = f.readline()
+                if line3 == GENERATED_MESSAGE:
+                    continue
+        files[basename] = file
+
+    doc_files: dict[str, str] = {}
+    for filename, filepath in files.items():
+        name, _ = os.path.splitext(filename)
+        with open(filepath) as f:
+            raw_content = f.read()
+        content = commonmark(raw_content)
+
+        out_path = os.path.join(path, f'{name}.html')
+
+        with open(out_path, 'w') as f:
+            f.write(content)
+
+        doc_files[name] = os.path.join(module.name, f'{name}.html')
+
+    setup_module_index(base=path,
+                       module=module,
+                       data=data,
+                       path_base=path_base,
+                       doc_files=doc_files,
+                       )

templates/module_index.html

@@ -2,6 +2,12 @@
 {% block content %}
 <h1>{{ module_name }}</h1>
 
+<ul>
+	{% for name, path in doc_files %}
+		<li><a href="{{ path_base }}/{{ path }}">{{ name }}</a></li>
+	{% endfor %}
+</ul>
+
 {% for entry in content %}
 	<h2>{{ entry['title'] }}</h2>
 	{% for subentry in entry['list'] %}