From f3373d08c74e36b2161e1f4e4eef6aa7197352e0 Mon Sep 17 00:00:00 2001 From: Indrajith K L Date: Fri, 7 Nov 2025 04:44:30 +0530 Subject: 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. --- html_docs/generate.py | 174 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 html_docs/generate.py (limited to 'html_docs/generate.py') diff --git a/html_docs/generate.py b/html_docs/generate.py new file mode 100644 index 0000000..4320bcc --- /dev/null +++ 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 = '''{title} + +

{content}

''' + +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'

\1

',h,flags=re.MULTILINE) + h=re.sub(r'^### (.+)$',r'

\1

',h,flags=re.MULTILINE) + h=re.sub(r'^## (.+)$',r'

\1

',h,flags=re.MULTILINE) + h=re.sub(r'^# (.+)$',r'

\1

',h,flags=re.MULTILINE) + + # Links + h=re.sub(r'\[([^\]]+)\]$([^$]+)\)',r'\1',h) + + # Bold/italic (after headers to avoid **text:** becoming headings) + h=re.sub(r'\*\*([^\*]+)\*\*',r'\1',h) + h=re.sub(r'\*([^\*\n]+)\*',r'\1',h) + + # Inline code + h=re.sub(r'`([^`]+)`',r'\1',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'

{content}

') + + # 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('

' + ' '.join(para_buffer) + '

') + para_buffer.clear() + + for line in lines: + s=line.strip() + + # Track pre blocks + if '

' in line:
+            flush_para()
+            in_pre=True
+            result.append(line)
+            continue
+        if '

' 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('

{item}

') + in_ul=False + + # Handle block elements + if s.startswith('') + + 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'): + if not cur: cur={'title':'Definitions','items':[]} + d=s.replace('>','').strip(); desc=[]; i+=1 + while i') 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='

ReiLua Enhanced

Lua binding for Raylib.

Documentation

Quick Start

Create main.lua:

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

Run: ReiLua.exe

'),encoding='utf-8') +print('✓ index.html') + +parts=['

ReiLua Manual

'] +readme=Path('../README.md') +if readme.exists(): + parts.append(md2html(re.sub(r'!\[.*?\]$.*?$','',readme.read_text(encoding='utf-8')))) + parts.append('

') +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'

{t}

') + parts.append(md2html(p.read_text(encoding='utf-8'))) + parts.append('

') +(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=['

ReiLua API Reference

Complete function reference.

{s["title"]} ({len(s["items"])} items)

') +for s in secs: + a=s['title'].lower().replace(' ','-').replace('/','').replace('.','') + parts.append(f'

{s["title"]}

') + for i in s['items']: + parts.append(f'

{i["definition"]}

') + if i['description']: + parts.append(f'

{md2html(i["description"])}

') +(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!') -- cgit v1.2.3

\1

\1

\1

\1