pyact-cli 0.8.0__tar.gz → 0.9.0__tar.gz

{pyact_cli-0.8.0 → pyact_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyact-cli
-Version: 0.8.0
+Version: 0.9.0
 Summary: A CLI tool to compile .pamd files to Markdown.
 Home-page: https://github.com/Abstergo2003/PyAct
 Author: Abstergo2003
@@ -112,4 +112,11 @@ title = Monthly Report
 
 PyAct will automatically detect `pamd.conf` in your directory, inject dynamic page numbers (`{page}` / `{pages}`), configure tab stops, and populate document metadata!
 
+### 7. Scaffolding New Projects with `pyact init`
+Quickly spin up a new project ready to compile:
+```bash
+pyact init my_project --template engineering
+```
+Templates: `default`, `engineering`, `academic`.
+
 That's it! You now have documents ready to be shared, published, or distributed.

{pyact_cli-0.8.0 → pyact_cli-0.9.0}/README.md

@@ -89,4 +89,11 @@ title = Monthly Report
 
 PyAct will automatically detect `pamd.conf` in your directory, inject dynamic page numbers (`{page}` / `{pages}`), configure tab stops, and populate document metadata!
 
+### 7. Scaffolding New Projects with `pyact init`
+Quickly spin up a new project ready to compile:
+```bash
+pyact init my_project --template engineering
+```
+Templates: `default`, `engineering`, `academic`.
+
 That's it! You now have documents ready to be shared, published, or distributed.

{pyact_cli-0.8.0 → pyact_cli-0.9.0}/pamd_helpers/__init__.py

@@ -52,6 +52,75 @@ def image(link: str, caption: str) -> str:
     caption_html = f"<span style='text-align: center; display: block; font-style: italic;'>{caption}</span>"
     return f"{image_link} \n {caption_html}"
 
+def plot(fig_or_plt: Any, caption: str = "", filename: str = None, dpi: int = 300, output_dir: str = "images") -> str:
+    """
+    Saves a Matplotlib/Seaborn figure or pyplot module to an image file and returns a styled Markdown image string.
+    
+    Why it is needed:
+    Allows data analysts and engineers to generate plots directly in Python code cells and 
+    seamlessly embed them into both Markdown and Word (DOCX) documents without manual file saving.
+    
+    Inputs:
+        fig_or_plt: A matplotlib Figure object or the matplotlib.pyplot module.
+        caption (str): Caption text to display below the plot.
+        filename (str): Optional file name (e.g. 'beam_deflection.png'). If omitted, a name is automatically generated.
+        dpi (int): Resolution of the exported image (default 300 dpi for sharp printing).
+        output_dir (str): Directory where the image should be saved (default 'images').
+        
+    Outputs:
+        str: A Markdown image tag with an italicized caption span, ready for injection into the document.
+    """
+    import os
+    import time
+    
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir, exist_ok=True)
+        
+    if not filename:
+        if caption:
+            import re
+            clean_name = re.sub(r'[^a-zA-Z0-9_-]', '_', caption.strip().lower())[:30].strip('_')
+            filename = f"{clean_name}.png" if clean_name else f"plot_{int(time.time()*1000)}.png"
+        else:
+            filename = f"plot_{int(time.time()*1000)}.png"
+            
+    if not filename.endswith(('.png', '.jpg', '.jpeg', '.svg')):
+        filename += '.png'
+        
+    filepath = os.path.join(output_dir, filename)
+    norm_path = filepath.replace('\\', '/')
+    
+    if hasattr(fig_or_plt, 'savefig'):
+        fig_or_plt.savefig(filepath, dpi=dpi, bbox_inches='tight')
+    elif hasattr(fig_or_plt, 'figure') and hasattr(fig_or_plt.figure, 'savefig'):
+        fig_or_plt.figure.savefig(filepath, dpi=dpi, bbox_inches='tight')
+    elif hasattr(fig_or_plt, 'save'):
+        fig_or_plt.save(filepath)
+    else:
+        raise TypeError(f"Expected a matplotlib Figure or image object with a 'savefig' or 'save' method, got {type(fig_or_plt)}")
+        
+    return image(norm_path, caption)
+
+def callout(text: str, callout_type: str = "note", title: str = None) -> str:
+    """
+    Generates a GitHub-flavored Markdown alert/callout box.
+    
+    Inputs:
+        text (str): The body text of the alert.
+        callout_type (str): 'note', 'tip', 'important', 'warning', or 'caution'.
+        title (str): Optional title overriding the default alert header.
+        
+    Outputs:
+        str: A blockquote formatted alert.
+    """
+    c_type = callout_type.upper()
+    lines = text.strip().split('\n')
+    header = f"> [!{c_type}]"
+    if title:
+        header += f" {title}"
+    body = "\n".join(f"> {line}" for line in lines)
+    return f"{header}\n{body}\n"
+
 def table(headers: List[str], values: List[List[Any]], caption: str, add_no: bool = False, starting_number: int = 1) -> str:
     """
     Generates a Markdown table from Python lists, including a caption.

pyact_cli-0.9.0/pyact/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.9.0"

{pyact_cli-0.8.0 → pyact_cli-0.9.0}/pyact/cli.py

@@ -2,7 +2,7 @@ import argparse
 import sys
 import os
 import time
-from .core import map_content, process_content, build_logs
+from .core import map_content, process_content, build_logs, generate_markdown_toc
 
 def is_cache_valid(build_tree, cache_mtime, root_dir=None):
     if root_dir is not None:
@@ -38,6 +38,16 @@ def main():
         Writes the generated `.md` and `.docx` files to the filesystem and prints 
         status messages to stdout/stderr.
     """
+    if len(sys.argv) > 1 and sys.argv[1] == "init":
+        init_parser = argparse.ArgumentParser(description="PyAct Project Initializer")
+        init_parser.add_argument("command", choices=["init"])
+        init_parser.add_argument("name", nargs="?", default=".", help="Project folder name (default: current directory)")
+        init_parser.add_argument("--template", choices=["default", "engineering", "academic"], default="default", help="Project template to scaffold")
+        init_args = init_parser.parse_args()
+        from .scaffold import init_project
+        init_project(init_args.name, init_args.template)
+        return
+
     parser = argparse.ArgumentParser(description="PyAct CLI - PAMD to Markdown compiler")
     parser.add_argument("input", help="Path to the main .pamd file")
     parser.add_argument("-o", "--output", help="Output file path (default prints to stdout)")
@@ -101,13 +111,14 @@ def main():
                     f.write(f"- {log['file']}: {log['time_ms']:.2f} ms\n")
                 f.write(f"\nTotal Build Time: {total_ms:.2f} ms\n")
         
+        md_output = generate_markdown_toc(content)
         if args.output:
             with open(args.output, "w", encoding="utf-8") as f:
-                f.write(content)
+                f.write(md_output)
             print(f"Successfully compiled to {args.output}")
         else:
             if not args.docx:
-                print(content)
+                print(md_output)
             
         if args.docx:
             from .mdTOword import style_parser, markdown_parser, docx_writer

{pyact_cli-0.8.0 → pyact_cli-0.9.0}/pyact/core.py

@@ -257,4 +257,83 @@ def process_content(build_tree: dict, globals_dict: dict = None):
         "time_ms": elapsed_ms
     })
         
-    return file_text
+    return file_text
+
+def make_github_slug(heading: str) -> str:
+    """Creates a GitHub-compatible anchor slug from heading text."""
+    clean = re.sub(r'\[([^\]]+)\]\([^\)]+\)', r'\1', heading)
+    clean = re.sub(r'[*_`]', '', clean)
+    clean = clean.lower().strip()
+    clean = re.sub(r'[^\w\s-]', '', clean, flags=re.UNICODE)
+    clean = re.sub(r'\s', '-', clean)
+    return clean
+
+def generate_markdown_toc(text: str) -> str:
+    """
+    Replaces `<toc/>`, `<toc>`, `[toc]`, or `<toc title="..."/>` with a GitHub-compatible
+    Markdown Table of Contents.
+    """
+    toc_pattern = r'<(?:toc|TOC)(?:\s+title=["\'](.*?)["\'])?\s*/?>|\[toc\]|\[TOC\]'
+    m = re.search(toc_pattern, text)
+    if not m:
+        return text
+        
+    toc_pos = m.start()
+    title_override = m.group(1)
+    
+    # Scan headings after the TOC tag
+    text_after = text[toc_pos:]
+    lines = text_after.split('\n')
+    
+    in_code = False
+    headings = []
+    for line in lines:
+        ls = line.strip()
+        if ls.startswith('```'):
+            in_code = not in_code
+            continue
+        if in_code:
+            continue
+        h_match = re.match(r'^(#{1,6})\s+(.*)$', ls)
+        if h_match:
+            level = len(h_match.group(1))
+            h_text = h_match.group(2).strip()
+            headings.append((level, h_text))
+            
+    if not headings:
+        # Fallback to scanning whole document if no headings were found after TOC tag
+        lines = text.split('\n')
+        in_code = False
+        for line in lines:
+            ls = line.strip()
+            if ls.startswith('```'):
+                in_code = not in_code
+                continue
+            if in_code:
+                continue
+            h_match = re.match(r'^(#{1,6})\s+(.*)$', ls)
+            if h_match:
+                level = len(h_match.group(1))
+                h_text = h_match.group(2).strip()
+                headings.append((level, h_text))
+                
+    if not headings:
+        return re.sub(toc_pattern, '', text, count=1)
+        
+    base_level = min(h[0] for h in headings)
+    toc_lines = []
+    for level, h_text in headings:
+        indent = "  " * (level - base_level)
+        clean_title = re.sub(r'[*_`]', '', h_text).strip()
+        slug = make_github_slug(h_text)
+        toc_lines.append(f"{indent}- [{clean_title}](#{slug})")
+        
+    toc_header = ""
+    if title_override:
+        if title_override.lower() not in ('none', 'false', 'no'):
+            toc_header = f"## {title_override}\n"
+    else:
+        toc_header = "## Table of Contents\n"
+        
+    full_toc = toc_header + "\n".join(toc_lines) + "\n"
+    return re.sub(toc_pattern, lambda _: full_toc, text, count=1)

{pyact_cli-0.8.0 → pyact_cli-0.9.0}/pyact/css2json.py

@@ -36,7 +36,8 @@ def css_to_dict(css_string: str) -> dict:
                 continue
             if ':' in line:
                 key, val = line.split(':', 1)
-                rules[key.strip()] = val.strip()
+                val_clean = re.sub(r'\s*!important\s*$', '', val.strip(), flags=re.IGNORECASE).strip()
+                rules[key.strip()] = val_clean
         
         # Handle comma-separated selectors (e.g., 'h1, h2, h3')
         for sel in selector.split(','):

{pyact_cli-0.8.0 → pyact_cli-0.9.0}/pyact/mdTOword.py

@@ -1,7 +1,9 @@
+import os
 import re
 from docx import Document
 from docx.shared import Pt, RGBColor, Inches, Cm, Mm
-from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_TAB_ALIGNMENT
+from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_TAB_ALIGNMENT, WD_TAB_LEADER
+from docx.enum.section import WD_SECTION, WD_ORIENT
 from docx.oxml import parse_xml, OxmlElement
 from docx.oxml.ns import nsdecls, qn
 import math2docx
@@ -31,35 +33,48 @@ def style_parser(css_path: str) -> dict:
         print(f"Warning: Could not parse CSS ({e})")
         return {}
 
+def _parse_quote_block(quote_lines: list) -> tuple:
+    """Parses a group of quote lines into an alert callout or standard blockquote."""
+    clean_lines = [re.sub(r'^>\s?', '', ql).strip() for ql in quote_lines]
+    first_line = clean_lines[0] if clean_lines else ""
+    m = re.match(r'^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\](?:\s+(.*))?$', first_line, re.IGNORECASE)
+    if m:
+        c_type = m.group(1).upper()
+        header_text = m.group(2).strip() if m.group(2) else ""
+        if len(clean_lines) > 1:
+            title = header_text if header_text else c_type.capitalize()
+            body = clean_lines[1:]
+        else:
+            title = c_type.capitalize()
+            body = [header_text] if header_text else []
+        return ('callout', c_type, title, body)
+    else:
+        return ('callout', 'BLOCKQUOTE', '', clean_lines)
+
 def markdown_parser(md_text: str) -> list:
     """
     Parses raw Markdown text into a structured list of block tuples.
-    
-    Why it is needed:
-    Because python-docx generates documents block-by-block (paragraphs, tables, headings), 
-    we need to break down the raw string of Markdown text into distinct, classified chunks 
-    that our DOCX writer can loop through and translate into native Word elements.
-    
-    Inputs:
-        md_text (str): The complete raw Markdown text string.
-        
-    Outputs:
-        list: A list of tuples where each tuple represents a block element.
-              Examples: 
-              - ('heading', 2, 'Title Text')
-              - ('paragraph', 'Some plain text')
-              - ('list', 'List item text', 'ordered')
-              - ('math', 'x = 2')
-              - ('table', ['|Header|', '|---|', '|Data|'])
     """
     blocks = []
     lines = md_text.split('\n')
     
     current_table = []
+    current_quote = []
     
     for line in lines:
         line_s = line.strip()
         
+        # Blockquote / Callout Parsing
+        if line_s.startswith('>'):
+            if current_table:
+                blocks.append(('table', current_table))
+                current_table = []
+            current_quote.append(line_s)
+            continue
+        elif current_quote:
+            blocks.append(_parse_quote_block(current_quote))
+            current_quote = []
+            
         # Table Parsing
         if line_s.startswith('|') and line_s.endswith('|'):
             current_table.append(line_s)
@@ -71,8 +86,31 @@ def markdown_parser(md_text: str) -> list:
         if not line_s:
             continue
             
+        # Table of Contents Parsing
+        if line_s.lower() in ('<toc/>', '<toc>', '[toc]'):
+            blocks.append(('toc', 'Table of Contents'))
+            
+        elif re.match(r'^<toc\s+title=["\'](.*?)["\']\s*/?>', line_s, re.IGNORECASE):
+            m = re.match(r'^<toc\s+title=["\'](.*?)["\']\s*/?>', line_s, re.IGNORECASE)
+            blocks.append(('toc', m.group(1)))
+            
+        # Page Break Parsing
+        elif line_s.lower() in ('<pagebreak/>', '<pagebreak>', '<page-break/>', '<pb/>', '<pb>', '<div style="page-break-after: always;"></div>'):
+            blocks.append(('pagebreak',))
+            
+        # Section Break Parsing
+        elif line_s.lower() in ('<sectionbreak/>', '<sectionbreak>', '<sb/>', '<sb>'):
+            blocks.append(('sectionbreak',))
+            
+        # Landscape Orientation Blocks
+        elif line_s.lower() in ('<landscape>', '<landscape/>'):
+            blocks.append(('landscape_start',))
+            
+        elif line_s.lower() in ('</landscape>',):
+            blocks.append(('landscape_end',))
+
         # Heading Parsing
-        if line_s.startswith('#'):
+        elif line_s.startswith('#'):
             level = len(line_s) - len(line_s.lstrip('#'))
             text = line_s.lstrip('#').strip()
             blocks.append(('heading', level, text))
@@ -96,6 +134,8 @@ def markdown_parser(md_text: str) -> list:
             
     if current_table:
         blocks.append(('table', current_table))
+    if current_quote:
+        blocks.append(_parse_quote_block(current_quote))
         
     return blocks
 
@@ -288,24 +328,39 @@ def _add_hyperlink(paragraph, text, url, styles, tag):
     paragraph._p.append(hyperlink)
 
 def _add_image(paragraph, url, caption, styles):
-    """Adds an inline image fetched from URL."""
+    """Adds an inline image fetched from URL or local file path."""
     try:
-        req = urllib.request.Request(url, headers={'User-Agent': 'Mozilla/5.0'})
-        with urllib.request.urlopen(req) as response:
-            image_stream = io.BytesIO(response.read())
-        
+        image_stream = None
+        if url.startswith(('http://', 'https://')):
+            req = urllib.request.Request(url, headers={'User-Agent': 'Mozilla/5.0'})
+            with urllib.request.urlopen(req) as response:
+                image_stream = io.BytesIO(response.read())
+        elif os.path.exists(url):
+            with open(url, 'rb') as f:
+                image_stream = io.BytesIO(f.read())
+        elif os.path.exists(os.path.abspath(url)):
+            with open(os.path.abspath(url), 'rb') as f:
+                image_stream = io.BytesIO(f.read())
+                
+        if image_stream is None:
+            paragraph.add_run(f"[Image Failed: {url}]")
+            return
+            
         run = paragraph.add_run()
         
         # Apply CSS dimensions if available
         width = None
         if 'image' in styles and 'width' in styles['image']:
-            w_str = styles['image']['width']
-            if 'in' in w_str: width = docx.shared.Inches(float(w_str.replace('in', '').strip()))
+            w_str = str(styles['image']['width']).strip().lower()
+            if 'in' in w_str: width = Inches(float(w_str.replace('in', '').strip()))
+            elif 'cm' in w_str: width = Cm(float(w_str.replace('cm', '').strip()))
+            elif 'mm' in w_str: width = Mm(float(w_str.replace('mm', '').strip()))
+            elif 'pt' in w_str: width = Pt(float(w_str.replace('pt', '').strip()))
             
         if width:
             run.add_picture(image_stream, width=width)
         else:
-            run.add_picture(image_stream, width=docx.shared.Inches(4))
+            run.add_picture(image_stream, width=Inches(4))
             
     except Exception as e:
         paragraph.add_run(f"[Image Failed: {url}]")
@@ -705,23 +760,213 @@ def _apply_docx_config(doc: Document, config: dict):
         if footer_conf:
             _configure_header_or_footer(section.footer, footer_conf, section)
 
-def docx_writer(blocks: list, styles: dict, output_file: str, config: dict = None):
-    """
-    Translates parsed markdown blocks into a Word document and applies CSS styling.
+def _add_callout_box(doc, callout_type: str, title: str, body_lines: list, styles: dict):
+    """Renders an alert callout box or blockquote as a styled 1x1 table."""
+    table = doc.add_table(rows=1, cols=1)
+    table.autofit = False
     
-    Why it is needed:
-    This is the core generation engine. It takes the abstract syntax structure generated 
-    by `markdown_parser()` and the style rules from `style_parser()`, loops through them, 
-    and issues the corresponding `python-docx` commands to physically build the `.docx` file.
+    theme = {
+        'NOTE': {'border': '0969DA', 'bg': 'F0F7FF', 'title_col': (9, 105, 218)},
+        'TIP': {'border': '1A7F37', 'bg': 'F0FFF4', 'title_col': (26, 127, 55)},
+        'IMPORTANT': {'border': '8250DF', 'bg': 'F8F5FF', 'title_col': (130, 80, 223)},
+        'WARNING': {'border': '9A6700', 'bg': 'FFFBEB', 'title_col': (154, 103, 0)},
+        'CAUTION': {'border': 'CF222E', 'bg': 'FFF1F2', 'title_col': (207, 34, 46)},
+        'BLOCKQUOTE': {'border': 'D0D7DE', 'bg': 'F6F8FA', 'title_col': (87, 96, 106)},
+    }
+    cfg = theme.get(callout_type.upper(), theme['NOTE'])
     
-    Inputs:
-        blocks (list): The list of parsed Markdown block tuples (from `markdown_parser`).
-        styles (dict): The nested dictionary of CSS rules (from `style_parser`).
-        output_file (str): The absolute or relative file path where the resulting .docx should be saved.
-        config (dict): Optional dictionary of global settings parsed from pamd.conf (header, footer, metadata).
+    tblPr = table._tbl.tblPr
+    tblW = parse_xml(f'<w:tblW {nsdecls("w")} w:w="5000" w:type="pct"/>')
+    tblPr.append(tblW)
+    
+    tblBorders = parse_xml(f'''
+        <w:tblBorders {nsdecls("w")}>
+            <w:top w:val="none"/>
+            <w:left w:val="none"/>
+            <w:bottom w:val="none"/>
+            <w:right w:val="none"/>
+            <w:insideH w:val="none"/>
+            <w:insideV w:val="none"/>
+        </w:tblBorders>
+    ''')
+    tblPr.append(tblBorders)
+    
+    cell = table.cell(0, 0)
+    tcPr = cell._tc.get_or_add_tcPr()
+    
+    shd = parse_xml(f'<w:shd {nsdecls("w")} w:fill="{cfg["bg"]}"/>')
+    tcPr.append(shd)
+    
+    tcBorders = parse_xml(f'''
+        <w:tcBorders {nsdecls("w")}>
+            <w:top w:val="none"/>
+            <w:left w:val="single" w:sz="36" w:space="0" w:color="{cfg['border']}"/>
+            <w:bottom w:val="none"/>
+            <w:right w:val="none"/>
+        </w:tcBorders>
+    ''')
+    tcPr.append(tcBorders)
+    
+    tcMar = parse_xml(f'''
+        <w:tcMar {nsdecls("w")}>
+            <w:top w:w="120" w:type="dxa"/>
+            <w:bottom w:w="120" w:type="dxa"/>
+            <w:left w:w="180" w:type="dxa"/>
+            <w:right w:w="180" w:type="dxa"/>
+        </w:tcMar>
+    ''')
+    tcPr.append(tcMar)
+    
+    p = cell.paragraphs[0]
+    p.paragraph_format.space_before = Pt(2)
+    p.paragraph_format.space_after = Pt(3)
+    
+    if title:
+        run_title = p.add_run()
+        if callout_type != 'BLOCKQUOTE':
+            if title.upper() == callout_type:
+                run_title.text = callout_type
+            else:
+                run_title.text = f"{callout_type}: {title}"
+        else:
+            run_title.text = title
+        run_title.bold = True
+        r, g, b = cfg['title_col']
+        run_title.font.color.rgb = RGBColor(r, g, b)
         
-    Outputs:
-        None: This function does not return a value, but it writes a binary .docx file to disk.
+    for idx, line in enumerate(body_lines):
+        if not title and idx == 0:
+            p_body = p
+        else:
+            p_body = cell.add_paragraph()
+        p_body.paragraph_format.space_before = Pt(0)
+        p_body.paragraph_format.space_after = Pt(2)
+        _process_inline(p_body, line, styles, 'p')
+        
+    p_spacer = doc.add_paragraph()
+    p_spacer.paragraph_format.space_before = Pt(0)
+    p_spacer.paragraph_format.space_after = Pt(4)
+
+def _add_table_of_contents(doc, title="Table of Contents", headings=None, styles=None):
+    """Inserts a native Word Table of Contents with dynamic updating and pre-populated entries."""
+    if headings is None:
+        headings = []
+    if styles is None:
+        styles = {}
+        
+    try:
+        settings = doc.settings.element
+        if not settings.xpath('w:updateFields'):
+            update_fields = OxmlElement('w:updateFields')
+            update_fields.set(qn('w:val'), 'true')
+            settings.append(update_fields)
+    except Exception:
+        pass
+        
+    if title and title.lower() not in ('none', 'false', 'no'):
+        p_title = doc.add_heading(title, level=1)
+        if 'h1' in styles:
+            _apply_paragraph_formatting(p_title, styles['h1'])
+        
+    p_first = doc.add_paragraph()
+    p_first.paragraph_format.space_before = Pt(2)
+    p_first.paragraph_format.space_after = Pt(2)
+    
+    r_begin = p_first.add_run()
+    fld1 = OxmlElement('w:fldChar')
+    fld1.set(qn('w:fldCharType'), 'begin')
+    r_begin._r.append(fld1)
+    
+    r_instr = p_first.add_run()
+    instr = OxmlElement('w:instrText')
+    instr.set(qn('xml:space'), 'preserve')
+    instr.text = ' TOC \\o "1-3" \\h \\z \\u '
+    r_instr._r.append(instr)
+    
+    r_sep = p_first.add_run()
+    fld2 = OxmlElement('w:fldChar')
+    fld2.set(qn('w:fldCharType'), 'separate')
+    r_sep._r.append(fld2)
+    
+    if headings:
+        base_level = min(h[1] for h in headings)
+        section = doc.sections[-1]
+        content_width = section.page_width - section.left_margin - section.right_margin
+        
+        for i, h_block in enumerate(headings):
+            h_level, h_text = h_block[1], h_block[2]
+            bm_name = f"_Toc_{i}"
+            rel_level = h_level - base_level
+            indent_in = max(0, rel_level * 0.25)
+            
+            p = p_first if i == 0 else doc.add_paragraph()
+            p.paragraph_format.space_before = Pt(1)
+            p.paragraph_format.space_after = Pt(2)
+            if indent_in > 0:
+                p.paragraph_format.left_indent = Inches(indent_in)
+                
+            tab_pos = content_width - Inches(indent_in)
+            p.paragraph_format.tab_stops.add_tab_stop(tab_pos, WD_TAB_ALIGNMENT.RIGHT, WD_TAB_LEADER.DOTS)
+            
+            hyperlink = OxmlElement('w:hyperlink')
+            hyperlink.set(qn('w:anchor'), bm_name)
+            
+            r_text = OxmlElement('w:r')
+            t = OxmlElement('w:t')
+            t.text = h_text
+            r_text.append(t)
+            hyperlink.append(r_text)
+            
+            r_tab = OxmlElement('w:r')
+            tab = OxmlElement('w:tab')
+            r_tab.append(tab)
+            hyperlink.append(r_tab)
+            
+            fld_p1 = OxmlElement('w:fldChar')
+            fld_p1.set(qn('w:fldCharType'), 'begin')
+            r_p1 = OxmlElement('w:r')
+            r_p1.append(fld_p1)
+            
+            instr_p = OxmlElement('w:instrText')
+            instr_p.set(qn('xml:space'), 'preserve')
+            instr_p.text = f' PAGEREF {bm_name} \\h '
+            r_pinstr = OxmlElement('w:r')
+            r_pinstr.append(instr_p)
+            
+            fld_p2 = OxmlElement('w:fldChar')
+            fld_p2.set(qn('w:fldCharType'), 'separate')
+            r_p2 = OxmlElement('w:r')
+            r_p2.append(fld_p2)
+            
+            r_pnum = OxmlElement('w:r')
+            t_pnum = OxmlElement('w:t')
+            t_pnum.text = str(max(1, h_level))
+            r_pnum.append(t_pnum)
+            
+            fld_p3 = OxmlElement('w:fldChar')
+            fld_p3.set(qn('w:fldCharType'), 'end')
+            r_p3 = OxmlElement('w:r')
+            r_p3.append(fld_p3)
+            
+            hyperlink.append(r_p1)
+            hyperlink.append(r_pinstr)
+            hyperlink.append(r_p2)
+            hyperlink.append(r_pnum)
+            hyperlink.append(r_p3)
+            
+            p._p.append(hyperlink)
+            
+    p_end = doc.add_paragraph()
+    p_end.paragraph_format.space_before = Pt(0)
+    p_end.paragraph_format.space_after = Pt(4)
+    r_end = p_end.add_run()
+    fld_end = OxmlElement('w:fldChar')
+    fld_end.set(qn('w:fldCharType'), 'end')
+    r_end._r.append(fld_end)
+
+def docx_writer(blocks: list, styles: dict, output_file: str, config: dict = None):
+    """
+    Translates parsed markdown blocks into a Word document and applies CSS styling.
     """
     doc = Document()
     current_ordered_numId = None
@@ -736,13 +981,47 @@ def docx_writer(blocks: list, styles: dict, output_file: str, config: dict = Non
         _apply_css_to_run(normal_style, styles['body'])
         _apply_paragraph_formatting(normal_style, styles['body'])
 
+    # Pre-scan headings for Table of Contents
+    headings_for_toc = []
+    toc_seen_scan = False
+    for b in blocks:
+        if b[0] == 'toc':
+            toc_seen_scan = True
+            continue
+        if b[0] == 'heading' and toc_seen_scan:
+            headings_for_toc.append(b)
+            
+    if not headings_for_toc:
+        headings_for_toc = [b for b in blocks if b[0] == 'heading']
+
+    toc_seen = False
+    heading_counter = 0
+
     for block in blocks:
         btype = block[0]
         
         if btype == 'heading':
             level, text = block[1], block[2]
             p = doc.add_heading('', level=level)
-            _process_inline(p, text, styles, f'h{level}')
+            
+            if toc_seen:
+                bm_name = f"_Toc_{heading_counter}"
+                bm_id = str(2000 + heading_counter)
+                heading_counter += 1
+                
+                bm_start = OxmlElement('w:bookmarkStart')
+                bm_start.set(qn('w:id'), bm_id)
+                bm_start.set(qn('w:name'), bm_name)
+                p._p.append(bm_start)
+                
+                _process_inline(p, text, styles, f'h{level}')
+                
+                bm_end = OxmlElement('w:bookmarkEnd')
+                bm_end.set(qn('w:id'), bm_id)
+                p._p.append(bm_end)
+            else:
+                _process_inline(p, text, styles, f'h{level}')
+                
             if f'h{level}' in styles:
                 _apply_paragraph_formatting(p, styles[f'h{level}'])
                 
@@ -752,6 +1031,10 @@ def docx_writer(blocks: list, styles: dict, output_file: str, config: dict = Non
             if 'p' in styles:
                 _apply_paragraph_formatting(p, styles['p'])
             _process_inline(p, text, styles, 'p')
+            
+        elif btype == 'callout':
+            c_type, title, body_lines = block[1], block[2], block[3]
+            _add_callout_box(doc, c_type, title, body_lines, styles)
                 
         elif btype == 'list':
             text = block[1]
@@ -805,6 +1088,29 @@ def docx_writer(blocks: list, styles: dict, output_file: str, config: dict = Non
                 if 'table' in styles:
                     pass
 
+        elif btype == 'toc':
+            toc_seen = True
+            title = block[1]
+            _add_table_of_contents(doc, title, headings_for_toc, styles)
+            
+        elif btype == 'pagebreak':
+            doc.add_page_break()
+            
+        elif btype == 'sectionbreak':
+            doc.add_section(WD_SECTION.NEW_PAGE)
+            
+        elif btype == 'landscape_start':
+            new_sec = doc.add_section(WD_SECTION.NEW_PAGE)
+            new_sec.orientation = WD_ORIENT.LANDSCAPE
+            if new_sec.page_width < new_sec.page_height:
+                new_sec.page_width, new_sec.page_height = new_sec.page_height, new_sec.page_width
+                
+        elif btype == 'landscape_end':
+            new_sec = doc.add_section(WD_SECTION.NEW_PAGE)
+            new_sec.orientation = WD_ORIENT.PORTRAIT
+            if new_sec.page_width > new_sec.page_height:
+                new_sec.page_width, new_sec.page_height = new_sec.page_height, new_sec.page_width
+
     doc.save(output_file)
 
 

pyact_cli-0.9.0/pyact/scaffold.py

@@ -0,0 +1,259 @@
+import os
+import json
+
+def init_project(target_dir: str = ".", template: str = "default"):
+    """
+    Scaffolds a new PyAct project with boilerplate files.
+    
+    Why it is needed:
+    Enables users to instantly create a ready-to-run PyAct project with main.pamd, 
+    global.py, pamd.conf, style.css, and .gitignore without manual setup.
+    
+    Inputs:
+        target_dir (str): Destination folder path.
+        template (str): 'default', 'engineering', or 'academic'.
+    """
+    if target_dir != "." and not os.path.exists(target_dir):
+        os.makedirs(target_dir, exist_ok=True)
+        
+    project_name = os.path.basename(os.path.abspath(target_dir))
+    if project_name == "" or project_name == ".":
+        project_name = "My PyAct Project"
+        
+    # 1. global.py
+    global_py_content = f'''def global_context():
+    """
+    Global variables accessible across all templates using <glb>var_name</glb>.
+    """
+    return {{
+        "author": "Author Name",
+        "project_name": "{project_name}",
+        "company": "Company Name",
+        "version": "1.0.0"
+    }}
+'''
+
+    # 2. pamd.conf
+    pamd_conf_content = f'''[Header]
+left = {project_name}
+right = 2026
+font_size = 9pt
+color = #666666
+
+[Footer]
+left = Confidential
+center = Page {{page}} of {{pages}}
+font_size = 9pt
+
+[Metadata]
+author = Author Name
+title = {project_name}
+subject = Technical Report
+
+[Page]
+size = A4
+margin = 1in
+'''
+
+    # 3. style.css
+    style_css_content = '''body {
+    font-family: Calibri, sans-serif;
+    font-size: 11pt;
+    line-height: 1.25;
+    color: #222222;
+}
+
+h1 {
+    color: #1a365d;
+    font-size: 22pt;
+    font-weight: bold;
+    margin-bottom: 14pt;
+}
+
+h2 {
+    color: #2b6cb0;
+    font-size: 16pt;
+    font-weight: bold;
+    margin-top: 14pt;
+    margin-bottom: 8pt;
+}
+
+h3 {
+    color: #4a5568;
+    font-size: 13pt;
+    font-weight: bold;
+    margin-top: 10pt;
+    margin-bottom: 6pt;
+}
+
+p {
+    margin-bottom: 8pt;
+}
+'''
+
+    # 4. .gitignore
+    gitignore_content = '''.pamd-cache/
+__pycache__/
+*.pyc
+'''
+
+    # 5. main.pamd based on template
+    if template == "engineering":
+        cells = [
+            {
+                "cell_type": "code",
+                "source": [
+                    "import pamd_helpers\n",
+                    "\n",
+                    "def context():\n",
+                    "    # 1. Design formula with Greek symbols and subscripts\n",
+                    "    f_cd = lambda f_ck, gamma_c: f_ck / gamma_c\n",
+                    "    design_strength = pamd_helpers.equation(f_cd, [30, 1.5])\n",
+                    "    \n",
+                    "    # 2. Table of material properties\n",
+                    "    headers = [\"Property\", \"Symbol\", \"Value\", \"Unit\"]\n",
+                    "    rows = [\n",
+                    "        [\"Char. Compressive Strength\", \"f_ck\", \"30\", \"MPa\"],\n",
+                    "        [\"Partial Safety Factor\", \"gamma_c\", \"1.5\", \"-\"],\n",
+                    "        [\"Design Compressive Strength\", \"f_cd\", \"20\", \"MPa\"]\n",
+                    "    ]\n",
+                    "    mat_table = pamd_helpers.table(headers, rows, \"Concrete Material Properties\", add_no=True)\n",
+                    "    \n",
+                    "    return {\n",
+                    "        \"strength_calc\": design_strength,\n",
+                    "        \"material_table\": mat_table\n",
+                    "    }\n"
+                ]
+            },
+            {
+                "cell_type": "markdown",
+                "source": [
+                    "# <glb>project_name</glb>\n",
+                    "Author: **<glb>author</glb>** | Organization: **<glb>company</glb>**\n",
+                    "\n",
+                    "<toc/>\n",
+                    "\n",
+                    "<pagebreak/>\n",
+                    "\n",
+                    "## 1. Material Specifications\n",
+                    "Below are the design material parameters:\n",
+                    "<ctx>material_table</ctx>\n",
+                    "\n",
+                    "## 2. Design Strength Verification\n",
+                    "The design compressive strength is calculated in accordance with Eurocode 2:\n",
+                    "<ctx>strength_calc</ctx>\n"
+                ]
+            }
+        ]
+    elif template == "academic":
+        cells = [
+            {
+                "cell_type": "code",
+                "source": [
+                    "import pamd_helpers\n",
+                    "\n",
+                    "def context():\n",
+                    "    fn1 = pamd_helpers.Footnote(1, \"Comprehensive study published in Journal of Applied Sciences, 2026.\")\n",
+                    "    hyp = pamd_helpers.hyperlink(\"Research Data Repository\", \"https://example.org/dataset\")\n",
+                    "    \n",
+                    "    return {\n",
+                    "        \"fn_ref\": fn1.adnotation(),\n",
+                    "        \"fn_def\": fn1.define_string(),\n",
+                    "        \"data_link\": hyp\n",
+                    "    }\n"
+                ]
+            },
+            {
+                "cell_type": "markdown",
+                "source": [
+                    "# <glb>project_name</glb>\n",
+                    "**<glb>author</glb>** (<glb>company</glb>)\n",
+                    "\n",
+                    "### Abstract\n",
+                    "This document explores computational report generation with PyAct.\n",
+                    "\n",
+                    "<toc/>\n",
+                    "\n",
+                    "<pagebreak/>\n",
+                    "\n",
+                    "## 1. Introduction\n",
+                    "Recent advancements in dynamic markdown have bridged computational logic with formal report generation<ctx>fn_ref</ctx>.\n",
+                    "\n",
+                    "The primary datasets are hosted at <ctx>data_link</ctx>.\n",
+                    "\n",
+                    "---\n",
+                    "<ctx>fn_def</ctx>\n"
+                ]
+            }
+        ]
+    else:  # default template
+        cells = [
+            {
+                "cell_type": "code",
+                "source": [
+                    "import pamd_helpers\n",
+                    "\n",
+                    "def context():\n",
+                    "    eq = pamd_helpers.equation(lambda x, y: x**2 + y, [4, 5])\n",
+                    "    tasks = pamd_helpers.checklist([\"Setup project\", \"Write logic\", \"Export to Word\"])\n",
+                    "    \n",
+                    "    return {\n",
+                    "        \"math\": eq,\n",
+                    "        \"todo\": tasks\n",
+                    "    }\n"
+                ]
+            },
+            {
+                "cell_type": "markdown",
+                "source": [
+                    "# <glb>project_name</glb>\n",
+                    "Prepared by: **<glb>author</glb>**\n",
+                    "\n",
+                    "<toc/>\n",
+                    "\n",
+                    "<pagebreak/>\n",
+                    "\n",
+                    "## 1. Overview\n",
+                    "Welcome to PyAct! This project was initialized with `pyact init`.\n",
+                    "\n",
+                    "## 2. Dynamic Computation\n",
+                    "Here is a mathematical calculation:\n",
+                    "<ctx>math</ctx>\n",
+                    "\n",
+                    "## 3. Project Tasks\n",
+                    "<ctx>todo</ctx>\n"
+                ]
+            }
+        ]
+
+    pamd_content = json.dumps({"cells": cells}, indent=2)
+
+    files_to_create = {
+        "global.py": global_py_content,
+        "pamd.conf": pamd_conf_content,
+        "style.css": style_css_content,
+        ".gitignore": gitignore_content,
+        "main.pamd": pamd_content
+    }
+
+    created = []
+    skipped = []
+    for fname, content in files_to_create.items():
+        fpath = os.path.join(target_dir, fname)
+        if os.path.exists(fpath):
+            skipped.append(fname)
+        else:
+            with open(fpath, "w", encoding="utf-8") as f:
+                f.write(content)
+            created.append(fname)
+
+    target_display = target_dir if target_dir != "." else "current directory"
+    print(f"Initialized PyAct project in {target_display} (template: {template}):")
+    for f in created:
+        print(f"  + Created {f}")
+    for f in skipped:
+        print(f"  ~ Skipped {f} (already exists)")
+    print("\nNext steps:")
+    if target_dir != ".":
+        print(f"  cd {target_dir}")
+    print("  pyact main.pamd -o output.md --docx output.docx")

{pyact_cli-0.8.0 → pyact_cli-0.9.0}/pyact_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyact-cli
-Version: 0.8.0
+Version: 0.9.0
 Summary: A CLI tool to compile .pamd files to Markdown.
 Home-page: https://github.com/Abstergo2003/PyAct
 Author: Abstergo2003
@@ -112,4 +112,11 @@ title = Monthly Report
 
 PyAct will automatically detect `pamd.conf` in your directory, inject dynamic page numbers (`{page}` / `{pages}`), configure tab stops, and populate document metadata!
 
+### 7. Scaffolding New Projects with `pyact init`
+Quickly spin up a new project ready to compile:
+```bash
+pyact init my_project --template engineering
+```
+Templates: `default`, `engineering`, `academic`.
+
 That's it! You now have documents ready to be shared, published, or distributed.

{pyact_cli-0.8.0 → pyact_cli-0.9.0}/pyact_cli.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ pyact/css2json.py
 pyact/linter.py
 pyact/mdTOword.py
 pyact/py2tex.py
+pyact/scaffold.py
 pyact_cli.egg-info/PKG-INFO
 pyact_cli.egg-info/SOURCES.txt
 pyact_cli.egg-info/dependency_links.txt

{pyact_cli-0.8.0 → pyact_cli-0.9.0}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as fh:
 
 setup(
     name="pyact-cli",
-    version="0.8.0",
+    version="0.9.0",
     author="Abstergo2003",
     author_email="",
     description="A CLI tool to compile .pamd files to Markdown.",

pyact_cli-0.8.0/pyact/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.8.0"