Provide NiceGUI documentation in a GPT-friendly format (e.g. PDF or HTML)

[cleesmith]

I know that NiceGUI documention is provided via NiceGUI itself, but is it possible to get that as a PDF or static HTML files?
The reason I ask is that it would be helpful for usage with both OpenAI, Anthropic, and other AI's when using AI chat to
assist with coding. At this point in time, Jul 28, 2024, none of the AI's seem well trained on the NiceGUI documentation (even the ones that can search the internet) ... unless specific parts of the doc's are copied/pasted directly into the AI chat. They get close and are helpful, but often they make assumptions when they don't know, and I think they would do a better job if they had the entire doc's.
Is this possible to provide a PDF or just static HTML files? (of course, that would lack the running example code)
By the way, I am enjoying using NiceGUI so far, much better than wxPython for me ... thanks for that.

[falkoschindler]

Regarding the documentation in PDF format, there are already discussions #3165 and #1571. And there is #1371 related to GPTs.

But let's keep this discussion open for the sake of generating a GPT-friendly documentation. There is a registry we could exploit to export the documentation in a different format:

nicegui/website/documentation/content/doc/api.py

Line 18 in f22690a

registry: Dict[str, DocumentationPage] = {}

[cleesmith]

Perhaps using Playwright in python with the Chromium option is a simple way to crawl
the pages and save them as one or more PDF files.

While testing this idea ...

I noticed a bad link on page:

https://nicegui.io/documentation/storage

Storing UI state
Storage can also be used in combination with bindings. Here we are storing the value of a textarea between visits. The note is also shared between all tabs of the same user.

the "with bindings" link is https://nicegui.io/documentation/bindings
HTTPException: 404: documentation for "bindings" could not be found
... but should be:
https://nicegui.io/documentation/section_binding_properties

Thanks and still enjoying NiceGUI while "teaching" AI's to help me code my app ... a repeat project formerly in wxPython, but NiceGUI looks way cooler/modern.

[falkoschindler]

Thanks for spotting the bad link! I quickly fixed it in b1ba313. Will be online with the next release.

[cleesmith]

I created a free open source repo of scripts to allow the creation of text/pdf files based on NiceGUI's locally run website server, see:

NiceGUI-primer

I used it to create the "knowledge base" text file for a GPT on ChatGPT, which has been helpful for learning and coding.

All credits and kudos to the NiceGUI project, thanks.

[ruiheng]

Hi everyone,

I've created a Python project to scrape the NiceGUI documentation (https://nicegui.io/documentation) and consolidate it into a single Markdown file, making it easier for offline reference or AI processing. The project was generated with assistance from Grok 3 and is designed to be simple, open-source, and easy to use.

Source code: https://github.com/ruiheng/nicegui_doc_scraper

Key features:

• Uses Playwright to handle dynamically rendered pages.
• Saves individual HTML files for debugging.
• Merges content into a single, AI-friendly Markdown file (nicegui_documentation.md).
• Modular and customizable for further tweaks.

I've attached the resulting nicegui_documentation.md file for reference.

Feel free to check out the project, contribute, or let me know if you have suggestions for improvements. Hope this is helpful!
nicegui_documentation.md.zip

[evnchn]

Burning question: can this fit in the context window?

I don't think it can, because it's very long, so I'm thinking we can segment the markdown by pages, and offer, in MCP or function calling, a tool for the LLM to do a vector search, returning the top N pages which are relevant.

[ruiheng]

The md file is too large for context window, but you can use it as a knowledge base for AI to reference. For example, in POE, you can create a bot, and upload this md file to its knowledge base. In Grok, you can create a workspace, and attach this md file in it. Other AI platforms probably have this similar feature.

[evnchn]

Hey all.

Here comes a bomb shell: Did you know about https://nicegui.io/static/search_index.json?

It is used for when the browser searches stuff through the search bar, but as it turns out, it's a pretty complete tapestry of what's in the NiceGUI website.

How it is generated:

nicegui/website/documentation/search.py

Lines 15 to 41 in 23292d4

	@app.get('/static/search_index.json')
	def _get_search_index() -> JSONResponse:
	return JSONResponse(search_index)
	def build_search_index() -> None:
	"""Build search index."""
	search_index.clear()
	search_index.extend([
	{
	'title': f'{documentation.heading.replace("*", "")}: {part.title}',
	'content': part.description or part.search_text or '',
	'format': part.description_format,
	'url': f'/documentation/{documentation.name}#{part.link_target}',
	}
	for documentation in registry.values()
	for part in documentation.parts
	])
	search_index.extend([
	{
	'title': f'Example: {example.title}',
	'content': example.description,
	'format': 'md',
	'url': example.url,
	}
	for example in examples
	])

A shortcoming though: the code is not included in the search_index.json, so after feeding the search index, ChatGPT may be very good at making stuff up as a result.

[evnchn]

https://tinydata.dev/data/E0Hcrejx.json

[falkoschindler]

Reminds my of a colleague of mine, who recently wanted to test Gemini 2.5 with its huge context window. He dumped all Python files from the repo into a single txt and asked the LLM to "generate a python app in a single .py file. The app should implement tetris using only nicegui as external library." After passing error messages back to the AI about 6 times, he got a working Tetris implementation.

find . -name "*.py" | while read file; do
  echo "# ---- $file ----" >> combined_python_files.txt
  cat "$file" >> combined_python_files.txt
  echo -e "\n" >> combined_python_files.txt
done

tetris.py

import asyncio
import random

# Import Callable
from typing import Callable, Dict, List, Optional, Tuple, Union, cast

from nicegui import Client, events, ui

# --- Constants --- (Unchanged)
BOARD_WIDTH = 10
BOARD_HEIGHT = 20
BLOCK_SIZE = 25

TETROMINOES: Dict[str, Dict[str, Union[List[Tuple[int, int]], str]]] = {
    'I': {'shape': [(0, -1), (0, 0), (0, 1), (0, 2)], 'color': '#00FFFF'},
    'O': {'shape': [(0, 0), (0, 1), (1, 0), (1, 1)], 'color': '#FFFF00'},
    'T': {'shape': [(0, -1), (0, 0), (0, 1), (1, 0)], 'color': '#800080'},
    'S': {'shape': [(0, 0), (0, 1), (1, -1), (1, 0)], 'color': '#00FF00'},
    'Z': {'shape': [(0, -1), (0, 0), (1, 0), (1, 1)], 'color': '#FF0000'},
    'J': {'shape': [(0, -1), (1, -1), (1, 0), (1, 1)], 'color': '#0000FF'},
    'L': {'shape': [(0, 1), (1, -1), (1, 0), (1, 1)], 'color': '#FFA500'},
}
TETROMINO_TYPES = list(TETROMINOES.keys())

# --- GameState Class ---


class GameState:
    # ... (GameState class remains unchanged from the previous correct version) ...
    def __init__(self, client: Client, update_ui_callback: Callable[[], None]):  # Added return type hint
        self.client = client
        self.update_ui = update_ui_callback
        self.board: List[List[Optional[str]]] = []
        self.current_piece_type: Optional[str] = None
        self.current_piece_blocks: List[Tuple[int, int]] = []
        self.current_pivot: Tuple[int, int] = (0, 0)
        self.current_rotation: int = 0
        self.next_piece_type: Optional[str] = None
        self.score: int = 0
        self.level: int = 1
        self.lines_cleared_total: int = 0
        self.game_over: bool = False
        self.paused: bool = False
        self.timer: Optional[ui.timer] = None
        self._reset_internals()  # Call reset during init

    def _reset_internals(self):
        """Initializes or resets the internal game state."""
        self.board = [[None for _ in range(BOARD_WIDTH)] for _ in range(BOARD_HEIGHT)]
        self.current_piece_type = None
        self.current_piece_blocks = []
        self.current_pivot = (-1, BOARD_WIDTH // 2 - 1)
        self.current_rotation = 0
        self.next_piece_type = random.choice(TETROMINO_TYPES)
        self.score = 0
        self.level = 1
        self.lines_cleared_total = 0
        self.game_over = False
        self.paused = False
        self.spawn_new_piece()

    def start_game(self):
        """Starts or restarts the game timer and resets state."""
        self._reset_internals()
        self.paused = False
        if self.timer:
            self.timer.interval = self.get_timer_interval()
            self.timer.activate()
        else:
            self.timer = ui.timer(self.get_timer_interval(), self.game_step, active=True)
        self.update_ui()

    def toggle_pause(self):
        """Pauses or resumes the game."""
        if self.game_over:
            return
        self.paused = not self.paused
        if self.timer:
            if self.paused:
                self.timer.deactivate()
            else:
                self.timer.activate()
        self.update_ui()

    def get_timer_interval(self) -> float: return max(0.1, (0.8-(self.level-1)*0.05))

    def update_timer_interval(self):
        if self.timer:
            self.timer.interval = self.get_timer_interval()

    def get_rotated_shape(self, piece_type: str, rotation: int) -> List[Tuple[int, int]]:
        shape = cast(List[Tuple[int, int]], TETROMINOES[piece_type]['shape'])
        if piece_type == 'O':
            return shape
        rotated_shape: List[Tuple[int, int]] = []
        for r_off, c_off in shape:
            cr, cc = int(r_off), int(c_off)
            for _ in range(rotation % 4):
                cr, cc = -cc, cr
            rotated_shape.append((cr, cc))
        return rotated_shape

    def get_absolute_coords(self, pivot: Tuple[int, int], shape_offsets: List[Tuple[int, int]]) -> List[Tuple[int, int]]:
        pr, pc = pivot
        return [(pr + r, pc + c) for r, c in shape_offsets]

    def is_valid_position(self, blocks: List[Tuple[int, int]]) -> bool:
        for r, c in blocks:
            if not (0 <= c < BOARD_WIDTH and r < BOARD_HEIGHT):
                return False
            if r >= 0:
                try:
                    if self.board[r][c] is not None:
                        return False
                except IndexError:
                    return False
        return True

    def spawn_new_piece(self):
        self.current_piece_type = self.next_piece_type
        self.next_piece_type = random.choice(TETROMINO_TYPES)
        self.current_pivot = (-1, BOARD_WIDTH//2-1)
        self.current_rotation = 0
        if self.current_piece_type is None:
            self.game_over = True
            return
        shape = self.get_rotated_shape(self.current_piece_type, self.current_rotation)
        self.current_piece_blocks = self.get_absolute_coords(self.current_pivot, shape)
        if not self.is_valid_position(self.current_piece_blocks):
            self.game_over = True
            if self.timer:
                self.timer.deactivate()
            print(f"Client {self.client.id}: Game Over! (Spawn collision)")

    def move_piece(self, dr: int, dc: int) -> bool:
        if self.game_over or self.paused or self.current_piece_type is None:
            return False
        npiv = (self.current_pivot[0]+dr, self.current_pivot[1]+dc)
        sh = self.get_rotated_shape(self.current_piece_type, self.current_rotation)
        nb = self.get_absolute_coords(npiv, sh)
        if self.is_valid_position(nb):
            self.current_pivot = npiv
            self.current_piece_blocks = nb
            return True
        return False

    def rotate_piece(self) -> bool:
        if self.game_over or self.paused or self.current_piece_type is None or self.current_piece_type == 'O':
            return False
        nr = (self.current_rotation+1) % 4
        sh = self.get_rotated_shape(self.current_piece_type, nr)
        offs = [(0, 0), (0, -1), (0, 1), (0, -2), (0, 2), (-1, 0), (1, 0)]
        for dr, dc in offs:
            kp = (self.current_pivot[0]+dr, self.current_pivot[1]+dc)
            kb = self.get_absolute_coords(kp, sh)
            if self.is_valid_position(kb):
                self.current_rotation = nr
                self.current_pivot = kp
                self.current_piece_blocks = kb
                return True
        return False

    def lock_piece(self):
        if self.game_over or self.current_piece_type is None:
            return
        clr = cast(str, TETROMINOES[self.current_piece_type]['color'])
        pab = any(r < 0 for r, c in self.current_piece_blocks)
        if pab:
            self.game_over = True
            if self.timer:
                self.timer.deactivate()
            print(f"Client {self.client.id}: Game Over! (Locked partially off-screen)")
            for r, c in self.current_piece_blocks:
                if 0 <= r < BOARD_HEIGHT and 0 <= c < BOARD_WIDTH:
                    try:
                        self.board[r][c] = clr
                    except IndexError:
                        pass
            self.update_ui()
            return
        for r, c in self.current_piece_blocks:
            if 0 <= r < BOARD_HEIGHT and 0 <= c < BOARD_WIDTH:
                try:
                    self.board[r][c] = clr
                except IndexError:
                    self.game_over = True
                    break
        if self.game_over:
            if self.timer:
                self.timer.deactivate()
            self.update_ui()
            return
        lines = self.clear_lines()
        if lines > 0:
            self.score += [0, 40, 100, 300, 1200][min(lines, 4)]*self.level
            self.lines_cleared_total += lines
            nl = (self.lines_cleared_total//10)+1
            if nl > self.level:
                self.level = nl
                self.update_timer_interval()
        if not self.game_over:
            self.spawn_new_piece()
        self.update_ui()

    def clear_lines(self) -> int:
        ltc = [r for r, row in enumerate(self.board) if all(row)]
        if not ltc:
            return 0
        lcn = len(ltc)
        nb: List[List[Optional[str]]] = [[None]*BOARD_WIDTH for _ in range(lcn)]
        rem = [row for r, row in enumerate(self.board) if r not in ltc]
        nb.extend(rem)
        self.board = nb
        return lcn

    def game_step(self):
        if self.game_over or self.paused:
            if self.game_over and self.timer and self.timer.active:
                self.timer.deactivate()
            return
        if not self.move_piece(1, 0):
            self.lock_piece()
        self.update_ui()


# --- NiceGUI UI and Event Handlers ---

# FIX: Added Type Hint for gs parameter
def generate_svg_content(gs: GameState) -> str:
    if not gs.board:
        return f'<svg width="{BOARD_WIDTH*BLOCK_SIZE}" height="{BOARD_HEIGHT*BLOCK_SIZE}"></svg>'
    svg_elements = []
    for r in range(BOARD_HEIGHT):
        for c in range(BOARD_WIDTH):
            if gs.board[r][c]:
                svg_elements.append(
                    f'<rect x="{c*BLOCK_SIZE}" y="{r*BLOCK_SIZE}" width="{BLOCK_SIZE}" height="{BLOCK_SIZE}" fill="{gs.board[r][c]}" stroke="black" stroke-width="1"/>')
    if gs.current_piece_type and not gs.game_over:
        clr = cast(str, TETROMINOES[gs.current_piece_type]['color'])
        for r, c in gs.current_piece_blocks:
            if 0 <= r < BOARD_HEIGHT and 0 <= c < BOARD_WIDTH:
                svg_elements.append(
                    f'<rect x="{c*BLOCK_SIZE}" y="{r*BLOCK_SIZE}" width="{BLOCK_SIZE}" height="{BLOCK_SIZE}" fill="{clr}" stroke="grey" stroke-width="1"/>')
    svg_elements.append(
        f'<rect x="0" y="0" width="{BOARD_WIDTH*BLOCK_SIZE}" height="{BOARD_HEIGHT*BLOCK_SIZE}" fill="none" stroke="black" stroke-width="2"/>')
    return f'<svg width="{BOARD_WIDTH*BLOCK_SIZE}" height="{BOARD_HEIGHT*BLOCK_SIZE}">{"".join(svg_elements)}</svg>'

# FIX: Added Type Hint for gs parameter


def generate_next_piece_svg(gs: GameState) -> str:
    if not gs.next_piece_type:
        return f'<svg width="{4*BLOCK_SIZE}" height="{4*BLOCK_SIZE}"></svg>'
    piece = TETROMINOES[gs.next_piece_type]
    shape = cast(List[Tuple[int, int]], piece['shape'])
    clr = cast(str, piece['color'])
    min_r: int = min(r for r, c in shape)if shape else 0
    max_r: int = max(r for r, c in shape)if shape else 0
    min_c: int = min(c for r, c in shape)if shape else 0
    max_c: int = max(c for r, c in shape)if shape else 0
    pw: int = (max_c-min_c+1)*BLOCK_SIZE
    ph: int = (max_r-min_r+1)*BLOCK_SIZE
    ox: float = (4*BLOCK_SIZE-pw)/2-min_c*BLOCK_SIZE
    oy: float = (4*BLOCK_SIZE-ph)/2-min_r*BLOCK_SIZE
    svg_elements: List[str] = [
        f'<rect x="{c*BLOCK_SIZE+ox}" y="{r*BLOCK_SIZE+oy}" width="{BLOCK_SIZE}" height="{BLOCK_SIZE}" fill="{clr}" stroke="grey" stroke-width="1"/>' for r, c in shape]
    return f'<svg width="{4*BLOCK_SIZE}" height="{4*BLOCK_SIZE}">{"".join(svg_elements)}</svg>'


@ui.page('/')
def main_page(client: Client):
    # UI Elements local to this function instance
    board_svg_local: Optional[ui.html] = None
    score_label_local: Optional[ui.label] = None
    level_label_local: Optional[ui.label] = None
    lines_label_local: Optional[ui.label] = None
    game_over_label_local: Optional[ui.label] = None
    pause_button_local: Optional[ui.button] = None
    next_piece_svg_local: Optional[ui.html] = None

    def update_all_ui_elements() -> None:  # FIX: Added return type hint
        """Callback to update all UI elements for the current client."""
        gs: Optional[GameState] = client.storage.get('game_state')
        if not gs:
            return

        # Use the local references captured by this function
        if score_label_local:
            score_label_local.set_text(f"Score: {gs.score}")
        if level_label_local:
            level_label_local.set_text(f"Level: {gs.level}")
        if lines_label_local:
            lines_label_local.set_text(f"Lines: {gs.lines_cleared_total}")
        if game_over_label_local:
            game_over_label_local.set_visibility(gs.game_over)
        if pause_button_local:
            pause_button_local.set_text('Resume' if gs.paused else 'Pause')
        if board_svg_local:
            board_svg_local.set_content(generate_svg_content(gs))
        if next_piece_svg_local:
            next_piece_svg_local.set_content(generate_next_piece_svg(gs))

    # --- Button Click Handlers (defined within page scope) ---
    def handle_start_game() -> None:
        gs: Optional[GameState] = client.storage.get('game_state')
        if gs:
            gs.start_game()

    def handle_toggle_pause() -> None:
        gs: Optional[GameState] = client.storage.get('game_state')
        if gs:
            gs.toggle_pause()

    # UI Layout
    ui.add_css(f''' /* ... CSS remains the same ... */ ''')
    with ui.column().classes('items-center'):
        ui.label('NiceGUI Tetris').classes('text-h4')
        with ui.row().classes('game-container'):
            with ui.column().classes('board-container'):
                board_svg_local = ui.html()  # Assign to local var
            with ui.column().classes('info-container'):
                score_label_local = ui.label().classes('text-lg')
                level_label_local = ui.label().classes('text-lg')
                lines_label_local = ui.label().classes('text-lg')
                ui.label("Next:").classes('text-lg')
                with ui.element('div').classes('next-piece-container'):
                    next_piece_svg_local = ui.html()  # Assign to local var
                game_over_label_local = ui.label("GAME OVER").classes('text-red-500 text-xl font-bold')
                game_over_label_local.set_visibility(False)

                # FIX: Call the helper functions defined above
                ui.button("New Game", on_click=handle_start_game)
                pause_button_local = ui.button("Pause", on_click=handle_toggle_pause)  # Assign to local var

    # Keyboard handler
    def handle_keypress(e: events.KeyEventArguments):
        gs: Optional[GameState] = e.client.storage.get('game_state')
        if not gs or gs.game_over or gs.paused:
            return
        moved = False
        rotated = False
        timer = gs.timer
        if e.key.arrow_left and e.action.keydown:
            moved = gs.move_piece(0, -1)
        elif e.key.arrow_right and e.action.keydown:
            moved = gs.move_piece(0, 1)
        elif e.key.arrow_down and e.action.keydown:
            moved = gs.move_piece(1, 0)
            if moved and timer:
                timer.interval = min(timer.interval, 0.05)
        elif e.key.arrow_up and e.action.keydown:
            rotated = gs.rotate_piece()
        elif e.key.arrow_down and e.action.keyup:
            if timer:
                gs.update_timer_interval()
        if moved or rotated:
            update_all_ui_elements()

    keyboard = ui.keyboard(on_key=handle_keypress)

    # Client-specific setup
    async def client_setup() -> None:  # FIX: Added return type hint
        await client.connected()
        gs = GameState(client, update_all_ui_elements)
        client.storage['game_state'] = gs
        gs.start_game()

    # Cleanup for this specific client
    def cleanup() -> None:  # FIX: Added return type hint
        gs: Optional[GameState] = client.storage.get('game_state')
        if gs and gs.timer:
            gs.timer.cancel()
        client.storage.pop('game_state', None)

    client.on_connect(client_setup)
    client.on_disconnect(cleanup)


if __name__ in {"__main__", "__mp_main__"}:
    ui.run(title="NiceGUI Tetris", reload=False, storage_secret="a_secret_key_is_needed_for_client_storage")

[evnchn]

dumped all Python files from the repo into a single txt

Just to clarify, I guess this means you dumped both the website and the source code, then?

[evnchn]

Also I must bring this to your attention, if it isn't already: #4688 Sitewide index for AI

[falkoschindler]

Just to clarify, I guess this means you dumped both the website and the source code, then?

I'm not sure. I'd have to ask him. (It have been 466K tokens - if this helps.)

Also I must bring this to your attention, if it isn't already: #4688 Sitewide index for AI

I've seen it, but haven't looked into the code yet.