From 635865a2199e79613105d5c25154763798980835 Mon Sep 17 00:00:00 2001 From: Julian Stirling Date: Wed, 15 Jan 2025 18:33:18 +0000 Subject: [PATCH 1/2] Started basic compatibility with MKDocs: - New mkdocs target profile - The filenames for the special files are now set by the target Other things fixed - No longer indenting TOC when there is no subtitle (as this causes the bullets to be in a code block) - TOC links to file in subdirectories correctly --- openscad_docsgen/__init__.py | 2 +- openscad_docsgen/blocks.py | 16 ++++++------- openscad_docsgen/parser.py | 28 ++++++++-------------- openscad_docsgen/target.py | 2 ++ openscad_docsgen/target_mkdocs.py | 39 +++++++++++++++++++++++++++++++ openscad_docsgen/target_wiki.py | 20 ++++++++++++++++ 6 files changed, 79 insertions(+), 28 deletions(-) create mode 100644 openscad_docsgen/target_mkdocs.py diff --git a/openscad_docsgen/__init__.py b/openscad_docsgen/__init__.py index 5795a51..cc03a05 100644 --- a/openscad_docsgen/__init__.py +++ b/openscad_docsgen/__init__.py @@ -100,7 +100,7 @@ def processFiles(opts): def main(): - target_profiles = ["githubwiki", "stdwiki"] + target_profiles = ["githubwiki", "stdwiki", "mkdocs"] parser = argparse.ArgumentParser(prog='openscad-docsgen') parser.add_argument('-D', '--docs-dir', default="docs", diff --git a/openscad_docsgen/blocks.py b/openscad_docsgen/blocks.py index f5e0231..63d1281 100644 --- a/openscad_docsgen/blocks.py +++ b/openscad_docsgen/blocks.py @@ -464,15 +464,13 @@ def get_tocfile_lines(self, controller, target, n=1, currfile=""): for child in self.get_children_by_title("Subsection"): out.extend(child.get_tocfile_lines(controller, target, currfile=currfile)) out.extend( - target.indent_lines( - target.bullet_list( - flatten([ - child.get_tocfile_lines(controller, target, currfile=currfile) - for child in self.get_children_by_title( - ["Constant","Function","Module","Function&Module"] - ) - ]) - ) + target.bullet_list( + flatten([ + child.get_tocfile_lines(controller, target, currfile=currfile) + for child in self.get_children_by_title( + ["Constant","Function","Module","Function&Module"] + ) + ]) ) ) return out diff --git a/openscad_docsgen/parser.py b/openscad_docsgen/parser.py index 8b789ea..4c552f9 100644 --- a/openscad_docsgen/parser.py +++ b/openscad_docsgen/parser.py @@ -19,8 +19,6 @@ def __init__(self, file, line): @property def md_file(self): - if self._md_in_links: - return self.file+".md" return self.file @@ -46,13 +44,6 @@ def __init__(self, opts): self.items_by_name = {} self.syntags_data = {} - sfx = self.target.get_suffix() - self.TOCFILE = "TOC" + sfx - self.TOPICFILE = "Topics" + sfx - self.INDEXFILE = "AlphaIndex" + sfx - self.CHEATFILE = "CheatSheet" + sfx - self.SIDEBARFILE = "_Sidebar" + sfx - self._reset_header_defs() def _reset_header_defs(self): @@ -746,9 +737,10 @@ def write_toc_file(self): if fblock.group != group: continue file = fblock.subtitle + fullfilepath = fblock.origin.md_file anch = target.header_link("{}. {}".format(fnum+1, file)) link = target.get_link(file, anchor=anch, literalize=False) - filelink = target.get_link("docs", file=file, literalize=False) + filelink = target.get_link("docs", file=fullfilepath, literalize=False) tags = {tag: text for tag, text, origin in fblock.footnotes} marks = target.mouseover_tags(tags, "#file-footnotes") out.extend(target.bullet_list_item("{} ({}){}".format(link, filelink, marks))) @@ -773,10 +765,10 @@ def write_toc_file(self): out.append("") for fnum, fblock in enumerate(prifiles): - out.extend(fblock.get_tocfile_lines(self, self.opts.target, n=fnum+1, currfile=self.TOCFILE)) + out.extend(fblock.get_tocfile_lines(self, self.opts.target, n=fnum+1, currfile=self.target.TOCFILE)) out = target.postprocess(out) - outfile = os.path.join(target.docs_dir, self.TOCFILE) + outfile = os.path.join(target.docs_dir, self.target.TOCFILE) if not self.quiet: print("Writing {}...".format(outfile)) with open(outfile, "w") as f: @@ -836,13 +828,13 @@ def write_topics_file(self): for name, item in sorted_items: out.extend( target.bullet_list_item( - item.get_index_line(self, target, self.TOPICFILE) + item.get_index_line(self, target, self.target.TOPICFILE) ) ) out.extend(target.bullet_list_end()) out = target.postprocess(out) - outfile = os.path.join(target.docs_dir, self.TOPICFILE) + outfile = os.path.join(target.docs_dir, self.target.TOPICFILE) if not self.quiet: print("Writing {}...".format(outfile)) with open(outfile, "w") as f: @@ -885,14 +877,14 @@ def write_index_file(self): ])) for ltr in ltrs_found: items = [ - item.get_index_line(self, target, self.INDEXFILE) + item.get_index_line(self, target, self.target.INDEXFILE) for name, item in index_by_letter[ltr] ] out.extend(target.header(ltr, lev=target.SUBSECTION)) out.extend(target.bullet_list(items)) out = target.postprocess(out) - outfile = os.path.join(target.docs_dir, self.INDEXFILE) + outfile = os.path.join(target.docs_dir, self.target.INDEXFILE) if not self.quiet: print("Writing {}...".format(outfile)) with open(outfile, "w") as f: @@ -913,7 +905,7 @@ def write_cheatsheet_file(self): out.extend(file_block.get_cheatsheet_lines(self, self.opts.target)) out = target.postprocess(out) - outfile = os.path.join(target.docs_dir, self.CHEATFILE) + outfile = os.path.join(target.docs_dir, self.target.CHEATFILE) if not self.quiet: print("Writing {}...".format(outfile)) with open(outfile, "w") as f: @@ -981,7 +973,7 @@ def write_sidebar_file(self): out.extend(self.opts.sidebar_footer) out = target.postprocess(out) - outfile = os.path.join(target.docs_dir, self.SIDEBARFILE) + outfile = os.path.join(target.docs_dir, self.target.SIDEBARFILE) if not self.quiet: print("Writing {}...".format(outfile)) with open(outfile, "w") as f: diff --git a/openscad_docsgen/target.py b/openscad_docsgen/target.py index 1778609..fed8ee2 100644 --- a/openscad_docsgen/target.py +++ b/openscad_docsgen/target.py @@ -2,12 +2,14 @@ from .target_githubwiki import Target_GitHubWiki from .target_wiki import Target_Wiki +from .target_mkdocs import Target_MKDocs default_target = "githubwiki" target_classes = { "githubwiki": Target_GitHubWiki, "wiki": Target_Wiki, + "mkdocs": Target_MKDocs, } diff --git a/openscad_docsgen/target_mkdocs.py b/openscad_docsgen/target_mkdocs.py new file mode 100644 index 0000000..ec4a4d6 --- /dev/null +++ b/openscad_docsgen/target_mkdocs.py @@ -0,0 +1,39 @@ +from __future__ import print_function + +import re + +from .target_wiki import Target_Wiki + + +class Target_MKDocs(Target_Wiki): + + @property + def TOCFILE(self): + return "index" + self.get_suffix() + + @property + def TOPICFILE(self): + return "topics" + self.get_suffix() + + @property + def INDEXFILE(self): + return "alphaindex" + self.get_suffix() + + @property + def CHEATFILE(self): + return "cheatsheet" + self.get_suffix() + + @property + def SIDEBARFILE(self): + return "_sidebar" + self.get_suffix() + + def get_link(self, label, anchor="", file="", literalize=True): + if literalize: + label = "`{0}`".format(label) + else: + label = self.escape_entities(label) + if file: + file += '.md' + if anchor: + anchor = "#" + anchor + return "[{0}]({1}{2})".format(label, file, anchor) \ No newline at end of file diff --git a/openscad_docsgen/target_wiki.py b/openscad_docsgen/target_wiki.py index 0cc960e..a91ad8e 100644 --- a/openscad_docsgen/target_wiki.py +++ b/openscad_docsgen/target_wiki.py @@ -15,6 +15,26 @@ def __init__(self, project_name=None, docs_dir="docs"): def get_suffix(self): return ".md" + @property + def TOCFILE(self): + return "TOC" + self.get_suffix() + + @property + def TOPICFILE(self): + return "Topics" + self.get_suffix() + + @property + def INDEXFILE(self): + return "AlphaIndex" + self.get_suffix() + + @property + def CHEATFILE(self): + return "CheatSheet" + self.get_suffix() + + @property + def SIDEBARFILE(self): + return "_Sidebar" + self.get_suffix() + def postprocess(self, lines): return lines From be794d4836d6d17c00c715ad31f95329a56488ed Mon Sep 17 00:00:00 2001 From: Julian Stirling Date: Wed, 15 Jan 2025 23:04:06 +0000 Subject: [PATCH 2/2] Stop double escaping subtitles of bulleted blocks --- openscad_docsgen/blocks.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/openscad_docsgen/blocks.py b/openscad_docsgen/blocks.py index 63d1281..7dc3762 100644 --- a/openscad_docsgen/blocks.py +++ b/openscad_docsgen/blocks.py @@ -247,7 +247,6 @@ def __init__(self, title, subtitle, body, origin, parent=None): def get_file_lines(self, controller, target): sub = self.parse_links(self.subtitle, controller, target) - sub = target.escape_entities(sub) out = target.block_header(self.title, sub) out.extend(target.bullet_list(self.body)) return out @@ -259,7 +258,6 @@ def __init__(self, title, subtitle, body, origin, parent=None): def get_file_lines(self, controller, target): sub = self.parse_links(self.subtitle, controller, target) - sub = target.escape_entities(sub) out = target.block_header(self.title, sub) out.extend(target.numbered_list(self.body)) return out