Improve code quality, fix all errors (finally)

Author: Omena0

.vscode/settings.json

@@ -3,7 +3,7 @@
         "https://www.schemastore.org/bukkit-plugin.json": "file:///home/omena0/Github/PyJavaBridge/src/main/resources/plugin.yml"
     },
     "java.compile.nullAnalysis.mode": "automatic",
-    "python-envs.defaultEnvManager": "ms-python.python:venv",
+    "python-envs.defaultEnvManager": "ms-python.python:system",
     "java.configuration.updateBuildConfiguration": "interactive",
     "python.defaultInterpreterPath": "/home/omena0/Github/PyJavaBridge/.venv/bin/python"
 }

docs/build.py

@@ -37,13 +37,11 @@
     import zstandard
 
 # ── Paths ────────────────────────────────────────────────────────────────────
-
 DOCS_DIR = os.path.dirname(os.path.abspath(__file__))
 SRC_DIR = os.path.join(DOCS_DIR, "src")
 OUT_DIR = os.path.join(DOCS_DIR, "site")
 
 # ── Sidebar definition (order matters) ──────────────────────────────────────
-
 SIDEBAR = [
     ("Getting Started", [
         ("getting_started/index", "Home"),
@@ -147,31 +145,31 @@
     ]),
 ]
 
-
 def slug_basename(slug):
     """Extract the filename part from a possibly prefixed slug (e.g. 'core/entity' → 'entity')."""
     return slug.rsplit("/", 1)[-1]
 
 # ── Frontmatter parser ──────────────────────────────────────────────────────
-
 def parse_frontmatter(text):
     """Extract YAML-like frontmatter and return (metadata_dict, remaining_text)."""
     if not text.startswith("---"):
         return {}, text
+
     end = text.find("---", 3)
     if end == -1:
         return {}, text
+
     fm_block = text[3:end].strip()
     body = text[end + 3:].strip()
     meta = {}
     for line in fm_block.splitlines():
         if ":" in line:
             key, val = line.split(":", 1)
             meta[key.strip()] = val.strip()
+
     return meta, body
 
 # ── Syntax highlighter (simple Python-aware) ────────────────────────────────
-
 PYTHON_KEYWORDS = {
     'False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await',
     'break', 'class', 'continue', 'def', 'del', 'elif', 'else', 'except',
@@ -203,21 +201,24 @@ def highlight_python(code):
     classes = [cls for cls, _ in token_specs]
 
     def _replacer(m):
+        """Return the highlighted span for the first matching token group."""
         for i, cls in enumerate(classes):
             if m.group(f'g{i}') is not None:
                 return f'<span class="{cls}">{m.group(f"g{i}")}</span>'
+
         return m.group(0)
 
     return re.sub(combined, _replacer, code, flags=re.DOTALL)
 
-
 def highlight_code_blocks(html_text):
     """Find <pre><code class="language-python"> blocks and apply highlighting."""
     def replace_block(m):
+        """Replace a fenced code block with syntax-highlighted HTML."""
         lang = m.group(1) or ""
         inner = m.group(2)
         if "python" in lang or "py" in lang:
             inner = highlight_python(inner)
+
         return f'<pre><code class="language-{lang}">{inner}</code></pre>'
 
     html_text = re.sub(
@@ -228,7 +229,6 @@ def replace_block(m):
     return html_text
 
 # ── Markdown → HTML conversion ──────────────────────────────────────────────
-
 def convert_markdown(text):
     """Convert markdown text to HTML with extensions."""
     md = markdown.Markdown(extensions=[
@@ -241,15 +241,14 @@ def convert_markdown(text):
     md.reset()
     return html, toc_tokens
 
-
 def rewrite_md_links(html_text):
     """Rewrite .md links to .html links."""
     return re.sub(r'href="([^"#]+)\.md(#[^"]*)?"', lambda m: f'href="{m.group(1)}.html{m.group(2) or ""}"', html_text)
 
-
 def process_blockquotes(html_text):
     """Convert blockquotes starting with bold markers into styled callouts."""
     def classify(m):
+        """Classify a blockquote as a callout based on its leading marker."""
         content = m.group(1)
         if content.strip().startswith("<strong>Warning"):
             cls = "callout callout-warn"
@@ -261,23 +260,21 @@ def classify(m):
             cls = "callout callout-info"
         else:
             cls = "callout callout-info"
+
         return f'<div class="{cls}">{content}</div>'
-    return re.sub(r'<blockquote>\s*(.*?)\s*</blockquote>', classify, html_text, flags=re.DOTALL)
 
+    return re.sub(r'<blockquote>\s*(.*?)\s*</blockquote>', classify, html_text, flags=re.DOTALL)
 
 # ── Tag formatting ───────────────────────────────────────────────────────────
-
 def format_ext_tags(html_text):
     """Replace [ext] with a styled badge span."""
     return html_text.replace('[ext]', '<span class="ext-tag">ext</span>')
 
 # ── HTML template ────────────────────────────────────────────────────────────
-
 def _section_key(name):
     """Turn a section name into a compact localStorage key."""
     return re.sub(r'[^a-z0-9]+', '-', name.lower()).strip('-')
 
-
 def build_sidebar_html(current_slug):
     """Generate the sidebar HTML."""
     parts = [
@@ -306,8 +303,8 @@ def build_sidebar_html(current_slug):
             parts.append(f'    <li><a href="{href}"{active}>{display}</a></li>')
 
         parts.extend(('  </ul>', '</div>'))
-    return "\n".join(parts)
 
+    return "\n".join(parts)
 
 def build_toc_sidebar(toc_tokens, current_slug):
     """Build the sidebar with 'On This Page' TOC at the top, then nav sections."""
@@ -328,14 +325,15 @@ def build_toc_sidebar(toc_tokens, current_slug):
             toc_parts.append(f'    <li><ul class="toc-sub" data-parent="{token["id"]}">')
             for child in children:
                 toc_parts.append(f'      <li><a href="#{child["id"]}">{child["name"]}</a></li>')
+
             toc_parts.append('    </ul></li>')
+
     toc_parts.extend(('  </ul>', '</div>'))
 
     # Insert TOC right after the search box (first </div>)
     search_end = nav.find('</div>') + len('</div>')
     return nav[:search_end] + '\n' + '\n'.join(toc_parts) + '\n' + nav[search_end:]
 
-
 TEMPLATE = """\
 <!DOCTYPE html>
 <html lang="en">
@@ -354,33 +352,41 @@ def build_toc_sidebar(toc_tokens, current_slug):
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
   <link href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,400..800&family=JetBrains+Mono:wght@400..700&display=swap" rel="stylesheet">
   <link rel="stylesheet" href="style.css">
+
 </head>
 <body>
   <!-- Header -->
   <header class="site-header">
     <button class="menu-toggle" aria-label="Toggle menu">
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
         <path d="M3 12h18M3 6h18M3 18h18"/>
+
       </svg>
+
     </button>
     <a href="index.html" class="header-brand">
       <span class="logo">Py</span>
       PyJavaBridge
+
     </a>
     <div class="header-search">
       <svg class="header-search-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
       <input type="text" id="header-search" placeholder="Search docs… (Ctrl+K)" autocomplete="off">
       <div id="search-results" class="search-results"></div>
+
     </div>
     <nav class="header-nav">
       <a href="index.html">Docs</a>
       <a href="examples.html">Examples</a>
       <a href="https://github.com/Omena0/PyJavaBridge">GitHub</a>
+
     </nav>
+
   </header>
 
   <!-- Sidebar -->
   <aside class="sidebar">
+
 {sidebar}
   </aside>
   <div class="sidebar-overlay"></div>
@@ -390,28 +396,33 @@ def build_toc_sidebar(toc_tokens, current_slug):
     <div class="content">
       {subtitle_html}
       {body}
+
     </div>
     <footer class="site-footer">
       &copy; Omena0 2026 &middot; PyJavaBridge Documentation
+
     </footer>
+
   </main>
 
   <!-- Back to top -->
   <button class="back-to-top" aria-label="Back to top">
     <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5">
       <path d="M18 15l-6-6-6 6"/>
+
     </svg>
+
   </button>
 
   <script id="zstd-data" type="text/plain">{search_index_zstd_b64}</script>
   <script src="https://cdn.jsdelivr.net/npm/fzstd@0.1.1/umd/index.js" async></script>
   <script src="script.js"></script>
+
 </body>
 </html>
 """
 
 # ── Builder ──────────────────────────────────────────────────────────────────
-
 def build_page(slug):
     """Build a single page from its markdown source."""
     src_path = os.path.join(SRC_DIR, f"{slug}.md")
@@ -463,18 +474,18 @@ def build_page(slug):
     with open(out_path, "w", encoding="utf-8") as f:
         f.write(out_html)
 
-
 def get_all_slugs():
     """Get all markdown file slugs from the sidebar definition."""
     slugs = []
     for _, pages in SIDEBAR:
         slugs.extend(slug for slug, _ in pages)
-    return slugs
 
+    return slugs
 
 _search_index_zstd_b64 = ""
 
 def main():
+    """Build the static documentation site from markdown sources."""
     global _search_index_zstd_b64
     print("📖 Building PyJavaBridge docs...")
     print(f"   Source: {SRC_DIR}")
@@ -499,63 +510,86 @@ def main():
     # Build search index first (needed for inlining into pages)
     for slug in slugs:
         src = os.path.join(SRC_DIR, f"{slug}.md")
+
         if os.path.exists(src):
             with open(src, "r", encoding="utf-8") as f:
                 raw = f.read()
+
             meta, body_md = parse_frontmatter(raw)
+
             title = meta.get("title", slug.capitalize())
             current_heading = title
+
             sections = []
             in_table = False
+
             table_first_cols = []
             table_header_seen = False
+
             for line in body_md.split("\n"):
                 stripped = line.strip()
+
                 if stripped.startswith("|") and "|" in stripped[1:]:
                     # Table row
                     if re.match(r'^\|[\s\-:|]+\|$', stripped):
                         table_header_seen = True  # separator marks end of header
                         continue
+
                     if not in_table:
                         # First row is the header — skip it
                         in_table = True
                         table_header_seen = False
                         continue
+
                     if not table_header_seen:
                         continue  # still in header somehow
+
                     cols = [c.strip() for c in stripped.strip("|").split("|")]
+
                     if cols:
                         col = re.sub(r'[`*\[\]()]', '', cols[0]).strip()
+
                         if col:
                             table_first_cols.append(col)
+
                     continue
+
                 else:
                     if in_table and table_first_cols:
                         sections.append({"heading": current_heading, "text": ", ".join(table_first_cols)})
                         table_first_cols = []
+
                     in_table = False
                     table_header_seen = False
 
                 if stripped.startswith("#"):
                     current_heading = stripped.lstrip("#").strip()
+
                 elif stripped and not stripped.startswith("```") and not stripped.startswith("---"):
                     clean = re.sub(r'[`*\[\]()]', '', stripped)
+
                     if clean:
                         sections.append({"heading": current_heading, "text": clean})
+
             # Flush any remaining table
             if table_first_cols:
                 sections.append({"heading": current_heading, "text": ", ".join(table_first_cols)})
+
             url = "index.html" if slug_basename(slug) == "index" else f"{slug_basename(slug)}.html"
             search_index.append({"slug": slug_basename(slug), "title": title, "url": url, "sections": sections})
 
     import json
+
     search_json = json.dumps(search_index, separators=(',', ':'))
     cctx = zstandard.ZstdCompressor(level=22)
+
     compressed = cctx.compress(search_json.encode('utf-8'))
     _search_index_zstd_b64 = base64.b64encode(compressed).decode('ascii')
+
     raw_size = len(search_json.encode('utf-8'))
     compressed_size = len(compressed)
     b64_size = len(_search_index_zstd_b64)
+
     print(f"   Search index: {raw_size:,} bytes → {compressed_size:,} zstd → {b64_size:,} base64 ({100*b64_size/raw_size:.1f}%)")
 
     # Build pages (with search index inlined)
@@ -568,6 +602,5 @@ def main():
 
     print(f"\n✅ Built {built} pages")
 
-
 if __name__ == "__main__":
     main()