From f9e374d84fb1a86860bfad91d989715106a08944 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se>
Date: Mon, 25 Sep 2023 17:17:43 +0200
Subject: [PATCH] Repair doc files.
---
muppet/output/__init__.py | 88 +++++++++++++++++++++++++++------------
1 file changed, 62 insertions(+), 26 deletions(-)
diff --git a/muppet/output/__init__.py b/muppet/output/__init__.py
index 3e1b59a..4677c94 100644
--- a/muppet/output/__init__.py
+++ b/muppet/output/__init__.py
@@ -172,7 +172,7 @@ class Templates:
Each element should be a pair of
- The idealized name of the file
- The relative path to the document inside the output
- (the HTML generated version)
+ (the HTML generated version, e.g. "{module}/{filename}/")
:param left_sidebar:
Free form content of the left sidebar.
@@ -515,6 +515,10 @@ class PuppetModule:
toc = self._build_module_toc()
+ doc_files_toc = [(os.path.splitext(k)[0],
+ os.path.join(self.name, os.path.join(os.path.splitext(k)[0])))
+ for (k, v) in read_doc_files(self.doc_files).items()]
+
with open(os.path.join(destination, 'index.html'), 'w') as f:
f.write(templates.module_index(
module_name=self.name,
@@ -522,9 +526,7 @@ class PuppetModule:
breadcrumbs=crumbs,
content=toc,
path_base=self.output_prefix,
- # TODO
- # doc_files=self.doc_files,
- doc_files=[],
+ doc_files=doc_files_toc,
# left_sidebar=(),
right_sidebar=''.join([
'<ul class="toc">',
@@ -533,7 +535,6 @@ class PuppetModule:
])))
def _generate_classes(self, destination: str) -> None:
- """TODO test document private."""
for puppet_class in self.strings_output.puppet_classes \
+ self.strings_output.defined_types:
logger.info('Formamting %s', puppet_class.name)
@@ -614,32 +615,26 @@ class PuppetModule:
content=body,
path_base=self.output_prefix))
- def _documentation_files(self, destination: str) -> None:
- 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 _output_doc_files(self, destination: str, files: dict[str, str]) -> None:
"""
+ Generate and output each documentation file.
+
+ :param destination:
+ Directory where the files should end up.
+
+ This should be the root output directory of the module, e.g.
- files: dict[str, str] = {}
- # TODO is this set?
- for file in self.doc_files:
- logger.debug('Formamting %s', file)
-
- 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
+ /var/www/muppet/{environment}/{module}/
+ :param files:
+ A set of files as returned by :func:`read_doc_files`.
+
+ Each key should be the basename of the file, each value should
+ be an absolute path to an (existing) file on disk.
+ """
doc_files: dict[str, str] = {}
for filename, filepath in files.items():
- logger.debug('Formamting %s', filename)
+ # logger.debug('Formamting %s', filename)
name, _ = os.path.splitext(filename)
with open(filepath) as f:
@@ -679,6 +674,7 @@ class PuppetModule:
pathlib.Path(destination).mkdir(exist_ok=True)
self.index_page(destination)
+ self._output_doc_files(destination, read_doc_files(self.doc_files))
self._generate_classes(destination)
self._generate_type_aliases(destination)
# data_type_aliases
@@ -1103,3 +1099,43 @@ def format_puppet_task() -> str:
def format_puppet_plan() -> str:
"""Format Puppet plan."""
return 'TODO format_puppet_plan not implemented'
+
+
+def read_doc_files(files: list[str]) -> dict[str, str]:
+ """
+ Locate the source path of all given files.
+
+ :param files:
+ A list of absolute filenames, locating the documentation files
+ for a given directory.
+
+ Files named 'REFERENCE.md' might get skipped, if they are the
+ output from ``puppet strings``.
+
+ :return:
+ A dictionary mapping the base filename of each item in
+ ``files`` onto it's absolute path.
+ """
+ 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.
+ """
+
+ _files: dict[str, str] = {}
+ # TODO is this set?
+ for file in files:
+ # logger.debug('Formamting %s', file)
+
+ 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
+
+ return _files
--
GitLab