Skip to content

Commit

Permalink
Added Synopsis block support.
Browse files Browse the repository at this point in the history
revarbat committed Mar 24, 2023
1 parent b2b0e27 commit 509cc33
Showing 3 changed files with 62 additions and 34 deletions.
55 changes: 39 additions & 16 deletions openscad_docsgen/blocks.py
Original file line number Diff line number Diff line change
@@ -39,19 +39,21 @@ def __str__(self):

def sort_children(self, front_blocks=(), back_blocks=()):
children = []
for child in self.children:
found = [block for blocks in front_blocks for block in blocks if block in child.title]
if found:
children.append(child)
for blocks in front_blocks:
for block in blocks:
for child in self.children:
if child.title.startswith(block):
children.append(child)
blocks = flatten(front_blocks + back_blocks)
for child in self.children:
found = [block for block in blocks if block in child.title]
found = [block for block in blocks if child.title.startswith(block)]
if not found:
children.append(child)
for child in self.children:
found = [block for blocks in back_blocks for block in blocks if block in child.title]
if found:
children.append(child)
for blocks in back_blocks:
for block in blocks:
for child in self.children:
if child.title.startswith(block):
children.append(child)
return children

def get_children_by_title(self, titles):
@@ -162,14 +164,27 @@ def get_file_lines(self, controller, target):
return out


class SynopsisBlock(LabelBlock):
def __init__(self, title, subtitle, body, origin, parent=None):
parent.synopsis = subtitle
super().__init__(title, subtitle, body, origin, parent=parent)

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)
return out


class SeeAlsoBlock(LabelBlock):
def __init__(self, title, subtitle, body, origin, parent=None):
self.see_also = [x.strip() for x in subtitle.split(",")]
parent.see_also = self.see_also
super().__init__(title, subtitle, body, origin, parent=parent)

def get_file_lines(self, controller, target):
names = [name.strip() for name in self.subtitle.split(",")]
items = []
for name in names:
for name in self.see_also:
if name not in controller.items_by_name:
msg = "Invalid Link '{0}'".format(name)
errorlog.add_entry(self.origin.file, self.origin.line, msg, ErrorLog.FAIL)
@@ -600,6 +615,7 @@ def __init__(self, title, subtitle, body, origin, parent=None):
self.topics = []
self.aliases = []
self.see_also = []
self.synopsis = ""

def __str__(self):
return "{}: {}".format(
@@ -626,6 +642,7 @@ def get_data(self):
d["deprecated"] = True
d["topics"] = self.topics
d["aliases"] = self.aliases
d["synopsis"] = self.synopsis
d["see_also"] = self.see_also
d["description"] = [
line
@@ -648,7 +665,7 @@ def get_data(self):
item.body
for item in self.children if item.title.startswith("Example")
]
skip_titles = ["Alias", "Aliases", "Arguments", "Description", "See Also", "Status", "Topics", "Usage"]
skip_titles = ["Alias", "Aliases", "Arguments", "Description", "See Also", "Synopsis", "Status", "Topics", "Usage"]
d["children"] = list(filter(lambda x: x["name"] not in skip_titles and not x["name"].startswith("Example"), d["children"]))
return d

@@ -657,7 +674,13 @@ def get_tocfile_lines(self, target, n=1, currfile=""):
return out

def get_toc_lines(self, target, n=1, currfile=""):
out = target.bullet_list_item(self.get_link(target, currfile=currfile))
out = target.bullet_list_item(
"{}{}{}".format(
self.get_link(target, currfile=currfile),
" – " if self.synopsis else "",
target.escape_entities(self.synopsis),
)
)
return out

def get_cheatsheet_lines(self, controller, target):
@@ -698,14 +721,14 @@ def get_cheatsheet_lines(self, controller, target):

def get_file_lines(self, controller, target):
front_blocks = [
["Alias"],
["Aliases"],
["Status"],
["Alias"],
["Synopsis"],
["Topics"],
["See Also"],
["Usage"]
]
back_blocks = [
["See Also"],
["Example"]
]
children = self.sort_children(front_blocks, back_blocks)
39 changes: 22 additions & 17 deletions openscad_docsgen/parser.py
Original file line number Diff line number Diff line change
@@ -157,11 +157,9 @@ def _define_blocktype(self, title, meta):
else:
raise DocsGenException("DefineHeader", "Could not parse target block type, while declaring block:")

def _mkfilenode(self, origin):
def _check_filenode(self, title, origin):
if not self.curr_file_block:
self.curr_file_block = FileBlock("LibFile", origin.file, [], origin)
self.curr_parent = self.curr_file_block
self.file_blocks.append(self.curr_file_block)
raise DocsGenException(title, "Must declare File or Libfile block before declaring block:")

def _parse_block(self, lines, line_num=0, src_file=None):
line_num = self._skip_lines(lines, line_num)
@@ -290,7 +288,7 @@ def _parse_block(self, lines, line_num=0, src_file=None):
raise DocsGenException(title, "Must declare File or LibFile block before declaring block:")

elif title == "Section":
self._mkfilenode(origin)
self._check_filenode(title, origin)
self.curr_section = SectionBlock(title, subtitle, body, origin, parent=self.curr_file_block)
self.curr_subsection = None
self.curr_parent = self.curr_section
@@ -302,38 +300,38 @@ def _parse_block(self, lines, line_num=0, src_file=None):
self.curr_subsection = SubsectionBlock(title, subtitle, body, origin, parent=self.curr_section)
self.curr_parent = self.curr_subsection
elif title == "Includes":
self._mkfilenode(origin)
self._check_filenode(title, origin)
IncludesBlock(title, subtitle, body, origin, parent=self.curr_file_block)
elif title == "FileSummary":
if not subtitle:
raise DocsGenException(title, "Must provide a subtitle when declaring block:")
self._mkfilenode(origin)
self._check_filenode(title, origin)
self.curr_file_block.summary = subtitle.strip()
elif title == "FileGroup":
if not subtitle:
raise DocsGenException(title, "Must provide a subtitle when declaring block:")
self._mkfilenode(origin)
self._check_filenode(title, origin)
self.curr_file_block.group = subtitle.strip()
elif title == "FileFootnotes":
if not subtitle:
raise DocsGenException(title, "Must provide a subtitle when declaring block:")
self._mkfilenode(origin)
self._check_filenode(title, origin)
self.curr_file_block.footnotes = []
for part in subtitle.split(";"):
fndata = [x.strip() for x in part.strip().split('=',1)]
fndata.append(origin)
self.curr_file_block.footnotes.append(fndata)
elif title == "CommonCode":
self._mkfilenode(origin)
self._check_filenode(title, origin)
self.curr_file_block.common_code.extend(body)
elif title == "Figure":
self._mkfilenode(origin)
self._check_filenode(title, origin)
FigureBlock(title, subtitle, body, origin, parent=parent, meta=meta, use_apngs=self.opts.png_animation)
elif title == "Example":
if self.curr_item:
ExampleBlock(title, subtitle, body, origin, parent=parent, meta=meta, use_apngs=self.opts.png_animation)
elif title == "Figures":
self._mkfilenode(origin)
self._check_filenode(title, origin)
for lnum, line in enumerate(body):
FigureBlock("Figure", subtitle, [line], origin, parent=parent, meta=meta, use_apngs=self.opts.png_animation)
subtitle = ""
@@ -355,7 +353,7 @@ def _parse_block(self, lines, line_num=0, src_file=None):
cb(title, subtitle, body, origin, meta)

elif title in ["Constant", "Function", "Module", "Function&Module"]:
self._mkfilenode(origin)
self._check_filenode(title, origin)
if not self.curr_section:
self.curr_section = SectionBlock("Section", "", [], origin, parent=self.curr_file_block)
parent = self.curr_parent = self.curr_section
@@ -373,6 +371,9 @@ def _parse_block(self, lines, line_num=0, src_file=None):
elif title == "See Also":
if self.curr_item:
SeeAlsoBlock(title, subtitle, body, origin, parent=parent)
elif title == "Synopsis":
if self.curr_item:
SynopsisBlock(title, subtitle, body, origin, parent=parent)
else:
raise DocsGenException(title, "Unrecognized block:")

@@ -408,6 +409,7 @@ def get_indexed_data(self, name):
"topics": ["Testing", "Metasyntactic"],
"aliases": ["foob()", "feeb()"],
"see_also": ["barbaz()", "bazqux()"],
"synopsis": "This function does bar.",
"usages": [
{
"subtitle": "As function",
@@ -496,6 +498,7 @@ def get_all_data(self):
"topics": ["Testing", "Metasyntactic"],
"aliases": ["foob()", "feeb()"],
"see_also": ["barbaz()", "bazqux()"],
"synopsis": "This function does bar.",
"usages": [
{
"subtitle": "As function",
@@ -785,9 +788,10 @@ def write_topics_file(self):
for name, item in sorted_items:
out.extend(
target.bullet_list_item(
"{} (in {})".format(
"{}{}{}".format(
item.get_link(target, label=name, currfile=self.TOPICFILE),
target.escape_entities(item.origin.file)
" – " if item.synopsis else "",
target.escape_entities(item.synopsis)
)
)
)
@@ -837,9 +841,10 @@ def write_index_file(self):
]))
for ltr in ltrs_found:
items = [
"{} (in {})".format(
"{}{}{}".format(
item.get_link(target, label=name, currfile=self.INDEXFILE),
target.escape_entities(item.origin.file)
" – " if item.synopsis else "",
target.escape_entities(item.synopsis)
)
for name, item in index_by_letter[ltr]
]
2 changes: 1 addition & 1 deletion setup.py
Original file line number Diff line number Diff line change
@@ -2,7 +2,7 @@

from setuptools import setup

VERSION = "2.0.33"
VERSION = "2.0.34"


with open('README.rst') as f:

0 comments on commit 509cc33

Please sign in to comment.