docs: Add HTML documentation generator and improve documentation structure

- Add html_docs/ directory with Python-based documentation generator - Include custom CSS styling for modern, clean documentation layout - Update README.md with improved formatting and documentation links - Enhance markdown documentation across all docs/ files: - Improve API documentation with better code examples - Refactor DOCUMENTATION_INDEX.md for clearer navigation - Update EMBEDDING.md, CUSTOMIZATION.md, and other guides - Standardize formatting and improve readability throughout - Fix inconsistent line endings and formatting issues The HTML documentation generator creates a styled, browsable version of the project documentation for easier reading and navigation.
2025-11-07 04:44:30 +05:30
parent 8c4b587a23
commit f3373d08c7
16 changed files with 8831 additions and 279 deletions
--- a/html_docs/README.md
+++ b/html_docs/README.md
@@ -0,0 +1,34 @@
+# ReiLua Documentation
+
+Simple HTML documentation for ReiLua, inspired by the Lua manual style.
+
+## Contents
+
+- index.html - Homepage
+- manual.html - Complete user guide
+- reference.html - API reference (1924 functions and structures)
+- style.css - Stylesheet
+- generate.py - Documentation generator
+
+## Viewing
+
+Open index.html in any web browser.
+
+## Hosting
+
+Upload the entire html_docs folder to your web server.
+
+## Regenerating
+
+If you update the markdown source files, regenerate with:
+
+    cd html_docs
+    python generate.py
+
+Requires Python 3.
+
+## Style
+
+Clean white background with navy blue headers, inspired by the official Lua manual.
+
+Simple, practical, and easy to read.
--- a/html_docs/generate.py
+++ b/html_docs/generate.py
@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""ReiLua Documentation Generator"""
+import os, re
+from pathlib import Path
+
+HTML_TEMPLATE = '''<!DOCTYPE HTML><html><head><title>{title}</title>
+<link rel="stylesheet" href="style.css"><meta charset="utf-8"></head><body>
+<div class="container"><div class="navigation">
+<a href="index.html">home</a> &middot; <a href="manual.html">manual</a> &middot; <a href="reference.html">reference</a>
+</div>{content}<div class="footer"><p>ReiLua Enhanced &middot; <a href="https://indrajith.dev">indrajith.dev</a></p></div></div></body></html>'''
+
+def fix_links(t):
+    t=re.sub(r'\(([^)]+)\.md\)',r'(manual.html)',t)
+    t=re.sub(r'\(docs/[^)]+\.md\)',r'(manual.html)',t)
+    t=re.sub(r'\(\.\.\/docs\/[^)]+\.md\)',r'(manual.html)',t)
+    return t
+
+def md2html(md):
+    h=fix_links(md)
+    
+    # Protect code blocks by replacing them with placeholders
+    code_blocks = []
+    def save_code(m):
+        code_blocks.append(m.group(0))
+        return f'___CODE_BLOCK_{len(code_blocks)-1}___'
+    h=re.sub(r'```[^\n]*\n.*?```',save_code,h,flags=re.DOTALL)
+    
+    # Now process markdown (code is protected)
+    # Headers - MUST be before bold/italic to avoid conflicts
+    h=re.sub(r'^#### (.+)$',r'<h4>\1</h4>',h,flags=re.MULTILINE)
+    h=re.sub(r'^### (.+)$',r'<h3>\1</h3>',h,flags=re.MULTILINE)
+    h=re.sub(r'^## (.+)$',r'<h2>\1</h2>',h,flags=re.MULTILINE)
+    h=re.sub(r'^# (.+)$',r'<h1>\1</h1>',h,flags=re.MULTILINE)
+    
+    # Links
+    h=re.sub(r'\[([^\]]+)\]\(([^\)]+)\)',r'<a href="\2">\1</a>',h)
+    
+    # Bold/italic (after headers to avoid **text:** becoming headings)
+    h=re.sub(r'\*\*([^\*]+)\*\*',r'<strong>\1</strong>',h)
+    h=re.sub(r'\*([^\*\n]+)\*',r'<em>\1</em>',h)
+    
+    # Inline code
+    h=re.sub(r'`([^`]+)`',r'<code>\1</code>',h)
+    
+    # Restore code blocks
+    for i, block in enumerate(code_blocks):
+        content = re.search(r'```[^\n]*\n(.*?)```', block, re.DOTALL).group(1)
+        h = h.replace(f'___CODE_BLOCK_{i}___', f'<pre><code>{content}</code></pre>')
+    
+    # Process line by line for paragraphs and lists
+    lines=h.split('\n')
+    result=[]
+    in_ul=False
+    in_pre=False
+    para_buffer=[]
+    
+    def flush_para():
+        if para_buffer:
+            result.append('<p>' + ' '.join(para_buffer) + '</p>')
+            para_buffer.clear()
+    
+    for line in lines:
+        s=line.strip()
+        
+        # Track pre blocks
+        if '<pre>' in line:
+            flush_para()
+            in_pre=True
+            result.append(line)
+            continue
+        if '</pre>' in line:
+            in_pre=False
+            result.append(line)
+            continue
+        if in_pre:
+            result.append(line)
+            continue
+        
+        # Handle list items
+        if s.startswith(('- ','* ')):
+            flush_para()
+            if not in_ul:
+                result.append('<ul>')
+                in_ul=True
+            item=re.sub(r'^[\-\*]\s+','',s)
+            result.append(f'<li>{item}</li>')
+            continue
+        
+        # End list if needed
+        if in_ul and not s.startswith(('- ','* ')):
+            result.append('</ul>')
+            in_ul=False
+        
+        # Handle block elements
+        if s.startswith('<h') or s.startswith('<div') or s.startswith('<hr'):
+            flush_para()
+            result.append(line)
+            continue
+        
+        # Empty line = paragraph break
+        if not s:
+            flush_para()
+            continue
+        
+        # Accumulate paragraph text
+        if s and not s.startswith('<'):
+            para_buffer.append(s)
+        else:
+            flush_para()
+            result.append(line)
+    
+    # Flush remaining
+    flush_para()
+    if in_ul:
+        result.append('</ul>')
+    
+    return '\n'.join(result)
+
+def parse_api(f):
+    with open(f,'r',encoding='utf-8') as fp: c=fp.read()
+    secs=[]; cur=None; lines=c.split('\n'); i=0
+    while i<len(lines):
+        l=lines[i]; s=l.strip()
+        if s.startswith('## ') and not s.startswith('###'):
+            if cur and cur.get('items'): secs.append(cur)
+            cur={'title':s.replace('##','').strip(),'items':[]}; i+=1; continue
+        if s.startswith('>'):
+            if not cur: cur={'title':'Definitions','items':[]}
+            d=s.replace('>','').strip(); desc=[]; i+=1
+            while i<len(lines):
+                n=lines[i]; ns=n.strip()
+                if ns.startswith('>') or (ns.startswith('##') and not ns.startswith('###')): break
+                if ns=='---': i+=1; break
+                desc.append(n); i+=1
+            cur['items'].append({'definition':d,'description':'\n'.join(desc).strip()}); continue
+        i+=1
+    if cur and cur.get('items'): secs.append(cur)
+    return secs
+
+out=Path(__file__).parent
+(out/'index.html').write_text(HTML_TEMPLATE.format(title='ReiLua',content='<h1>ReiLua Enhanced</h1><p>Lua binding for Raylib.</p><h2>Documentation</h2><ul><li><a href="manual.html">Manual</a></li><li><a href="reference.html">API Reference</a></li></ul><h2>Quick Start</h2><p>Create <code>main.lua</code>:</p><pre><code>function RL.init()\n  RL.SetWindowTitle("Hello")\nend\n\nfunction RL.update(dt)\nend\n\nfunction RL.draw()\n  RL.ClearBackground(RL.RAYWHITE)\n  RL.DrawText("Hello!",190,200,20,RL.BLACK)\nend</code></pre><p>Run: <code>ReiLua.exe</code></p>'),encoding='utf-8')
+print('✓ index.html')
+
+parts=['<h1>ReiLua Manual</h1>']
+readme=Path('../README.md')
+if readme.exists():
+    parts.append(md2html(re.sub(r'!\[.*?\]\(.*?\)','',readme.read_text(encoding='utf-8'))))
+    parts.append('<hr>')
+for fp,t in [('../docs/EMBEDDING.md','Embedding'),('../docs/ASSET_LOADING.md','Asset Loading'),('../docs/SPLASH_SCREENS.md','Splash Screens'),('../docs/BUILD_SCRIPTS.md','Build Scripts'),('../docs/CUSTOMIZATION.md','Customization'),('../docs/ZED_EDITOR_SETUP.md','Editor Setup')]:
+    p=Path(fp)
+    if p.exists():
+        a=t.lower().replace(' ','-')
+        parts.append(f'<h2 id="{a}">{t}</h2>')
+        parts.append(md2html(p.read_text(encoding='utf-8')))
+        parts.append('<hr>')
+(out/'manual.html').write_text(HTML_TEMPLATE.format(title='Manual',content='\n'.join(parts)),encoding='utf-8')
+print('✓ manual.html')
+
+secs=parse_api(Path('../docs/API.md'))
+parts=['<h1>ReiLua API Reference</h1><p>Complete function reference.</p><h2>Contents</h2><ul>']
+for s in secs:
+    a=s['title'].lower().replace(' ','-').replace('/','').replace('.','')
+    parts.append(f'<li><a href="#{a}">{s["title"]}</a> ({len(s["items"])} items)</li>')
+parts.append('</ul>')
+for s in secs:
+    a=s['title'].lower().replace(' ','-').replace('/','').replace('.','')
+    parts.append(f'<h2 id="{a}">{s["title"]}</h2>')
+    for i in s['items']:
+        parts.append(f'<div class="apii"><code>{i["definition"]}</code></div>')
+        if i['description']:
+            parts.append(f'<div class="apidesc">{md2html(i["description"])}</div>')
+(out/'reference.html').write_text(HTML_TEMPLATE.format(title='API Reference',content='\n'.join(parts)),encoding='utf-8')
+print(f'✓ reference.html ({sum(len(s["items"]) for s in secs)} items)')
+print('Complete!')
--- a/html_docs/index.html
+++ b/html_docs/index.html
@@ -0,0 +1,15 @@
+<!DOCTYPE HTML><html><head><title>ReiLua</title>
+<link rel="stylesheet" href="style.css"><meta charset="utf-8"></head><body>
+<div class="container"><div class="navigation">
+<a href="index.html">home</a> &middot; <a href="manual.html">manual</a> &middot; <a href="reference.html">reference</a>
+</div><h1>ReiLua Enhanced</h1><p>Lua binding for Raylib.</p><h2>Documentation</h2><ul><li><a href="manual.html">Manual</a></li><li><a href="reference.html">API Reference</a></li></ul><h2>Quick Start</h2><p>Create <code>main.lua</code>:</p><pre><code>function RL.init()
+  RL.SetWindowTitle("Hello")
+end
+
+function RL.update(dt)
+end
+
+function RL.draw()
+  RL.ClearBackground(RL.RAYWHITE)
+  RL.DrawText("Hello!",190,200,20,RL.BLACK)
+end</code></pre><p>Run: <code>ReiLua.exe</code></p><div class="footer"><p>ReiLua Enhanced &middot; <a href="https://indrajith.dev">indrajith.dev</a></p></div></div></body></html>
--- a/html_docs/manual.html
+++ b/html_docs/manual.html
--- a/html_docs/reference.html
+++ b/html_docs/reference.html
--- a/html_docs/style.css
+++ b/html_docs/style.css
@@ -0,0 +1,136 @@
+/* ReiLua Documentation - Lua Manual Style */
+
+body {
+    font-family: Helvetica, Arial, sans-serif;
+    line-height: 1.6;
+    color: #000000;
+    background-color: #FFFFFF;
+    margin: 0;
+    padding: 0;
+}
+
+.container {
+    max-width: 800px;
+    margin: 0 auto;
+    padding: 20px;
+}
+
+h1 {
+    font-size: 24px;
+    font-weight: normal;
+    margin: 20px 0 10px 0;
+    color: #000080;
+    border-bottom: 1px solid #000080;
+    padding-bottom: 5px;
+}
+
+h2 {
+    font-size: 20px;
+    font-weight: normal;
+    margin: 20px 0 10px 0;
+    color: #000080;
+}
+
+h3 {
+    font-size: 16px;
+    font-weight: bold;
+    margin: 15px 0 10px 0;
+}
+
+.navigation {
+    font-size: 12px;
+    margin: 10px 0;
+    padding: 10px;
+    background-color: #F0F0F0;
+    border: 1px solid #D0D0D0;
+}
+
+.navigation a {
+    color: #000080;
+    text-decoration: none;
+    margin: 0 5px;
+}
+
+.navigation a:hover {
+    text-decoration: underline;
+}
+
+a {
+    color: #000080;
+    text-decoration: none;
+}
+
+a:hover {
+    text-decoration: underline;
+}
+
+p {
+    margin: 10px 0;
+    text-align: justify;
+}
+
+code, tt {
+    font-family: "Courier New", Courier, monospace;
+    font-size: 13px;
+    background-color: #F5F5F5;
+    padding: 1px 4px;
+}
+
+pre {
+    font-family: "Courier New", Courier, monospace;
+    font-size: 13px;
+    background-color: #F5F5F5;
+    border: 1px solid #D0D0D0;
+    padding: 10px;
+    overflow-x: auto;
+    margin: 10px 0;
+}
+
+.apii {
+    font-family: "Courier New", Courier, monospace;
+    margin: 15px 0 5px 0;
+    padding: 8px;
+    background-color: #F0F0F0;
+    border-left: 3px solid #000080;
+}
+
+.apii code {
+    background-color: transparent;
+    font-weight: bold;
+}
+
+.apidesc {
+    margin: 5px 0 15px 20px;
+}
+
+ul, ol {
+    margin: 10px 0;
+    padding-left: 30px;
+}
+
+table {
+    border-collapse: collapse;
+    margin: 10px 0;
+    width: 100%;
+}
+
+th {
+    background-color: #F0F0F0;
+    border: 1px solid #D0D0D0;
+    padding: 8px;
+    text-align: left;
+}
+
+td {
+    border: 1px solid #D0D0D0;
+    padding: 8px;
+}
+
+.footer {
+    margin-top: 40px;
+    padding-top: 10px;
+    border-top: 1px solid #D0D0D0;
+    font-size: 11px;
+    color: #666;
+    text-align: center;
+}