From 145aa2bc5c804359b1573c7a4cb8c6b5830f5df0 Mon Sep 17 00:00:00 2001 From: pbrochar Date: Sun, 17 Mar 2024 00:47:19 +0100 Subject: [PATCH] finish doc --- blitz/cli/app.py | 5 +- blitz/cli/commands/callback.py | 11 +++ blitz/cli/commands/clone.py | 5 +- blitz/models/blitz/file.py | 12 ++- docs/api/index.md | 145 ++++++++++++++++++++++++++++++++- docs/cli/clone.md | 27 ++++++ docs/cli/start.md | 14 +++- docs/dashboard/admin.md | 5 ++ docs/dashboard/blitz_file.md | 6 ++ docs/dashboard/diagram.md | 3 + docs/dashboard/gpt_builder.md | 17 ++++ docs/dashboard/index.md | 19 ++++- docs/dashboard/logs.md | 7 ++ docs/dashboard/swagger.md | 6 ++ docs/features.md | 2 +- docs/index.md | 4 + mkdocs.yml | 4 +- 17 files changed, 282 insertions(+), 10 deletions(-) create mode 100644 blitz/cli/commands/callback.py create mode 100644 docs/cli/clone.md diff --git a/blitz/cli/app.py b/blitz/cli/app.py index d45465b..91be0ab 100644 --- a/blitz/cli/app.py +++ b/blitz/cli/app.py @@ -1,7 +1,7 @@ -# from .commands.swagger import list_routes import typer from blitz.cli.commands.clone import clone_project +from blitz.cli.commands.callback import callback from .commands.create import create_blitz_app from .commands.list import list_blitz_app @@ -9,12 +9,13 @@ from .commands.start import start_blitz from .commands.swagger import list_routes -app = typer.Typer() +app = typer.Typer(no_args_is_help=True) app.command(name="create")(create_blitz_app) app.command(name="list")(list_blitz_app) app.command(name="start")(start_blitz) app.command(name="release")(release_blitz) app.command(name="swagger")(list_routes) app.command(name="clone")(clone_project) +app.callback(invoke_without_command=True)(callback) # dev only # app.command(name="clean")(clean_blitz) diff --git a/blitz/cli/commands/callback.py b/blitz/cli/commands/callback.py new file mode 100644 index 0000000..5804c18 --- /dev/null +++ b/blitz/cli/commands/callback.py @@ -0,0 +1,11 @@ +from typing import Annotated, Optional +import typer +from blitz import __version__ + +def version_callback(show_version: bool) -> None: + if show_version: + print(__version__) + +def callback(version: Annotated[Optional[bool], typer.Option("--version", help="Show the Blitz version.", callback=version_callback)] = None) -> None: + if version: + print(__version__) diff --git a/blitz/cli/commands/clone.py b/blitz/cli/commands/clone.py index 1da92e4..d0e6951 100644 --- a/blitz/cli/commands/clone.py +++ b/blitz/cli/commands/clone.py @@ -5,7 +5,7 @@ import typer from blitz.cli.commands.create import BlitzProjectCreator from blitz.cli.utils import progress -from blitz.models.blitz.file import BlitzFile +from blitz.models.blitz.file import BlitzFile, InvalidFileTypeError def clone_project( @@ -26,6 +26,9 @@ def clone_project( except (requests.HTTPError, JSONDecodeError): print(f"Failed to clone the project from {url}") raise typer.Exit(1) + except InvalidFileTypeError as err: + print(err) + raise typer.Exit(1) name = name or blitz_file.config.name blitz_creator = BlitzProjectCreator(name, blitz_file.config.description, format, blitz_file, demo=False) diff --git a/blitz/models/blitz/file.py b/blitz/models/blitz/file.py index 50825cd..db59e43 100644 --- a/blitz/models/blitz/file.py +++ b/blitz/models/blitz/file.py @@ -22,6 +22,11 @@ def _get_data_from_yaml(file: Path) -> dict[str, dict[str, Any]]: def _no_parser_for_suffix(file: Path) -> NoReturn: raise ValueError(f"No parser for {file}") +class InvalidFileTypeError(Exception): + def __init__(self, file_type: str) -> None: + self.file_type = file_type + super().__init__(f"Invalid file type: {file_type}") + class BlitzFile(BaseModel): """ @@ -97,11 +102,16 @@ def from_dict( @classmethod def from_url(cls, url: str, name: str | None = None, format: str = "yaml") -> "BlitzFile": + try: + file_type = cls.FileType(format) + except ValueError: + raise InvalidFileTypeError(format) response = requests.get(url) try: response.raise_for_status() project_data = response.json() - blitz_file = cls.from_dict(project_data, file_type=cls.FileType(format)) + + blitz_file = cls.from_dict(project_data, file_type=file_type) except Exception as err: raise err name = name or blitz_file.config.name diff --git a/docs/api/index.md b/docs/api/index.md index a1e865a..0bf3b51 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -1,2 +1,143 @@ -!!! warning - **WORK IN PROGRESS** \ No newline at end of file +# API + +The Blitz API contains all the exposed CRUD operations defined on the [Blitz File](/blitz/blitzfile/), but also the `/blitz-file` which is, as its name suggests, the Json representation of the running Blitz File. + +This feature is used for the [clone command](/blitz/cli/clone/) and the [--url option of the start command](/blitz/cli/start). + +This feature can be disabled with the `--no-config-route` option of the start command. + +For exemple, this is the return of the demo `/blitz-file`: + +```json +{ + "config":{ + "name":"Demo Blitz App", + "description":"This is a demo blitz app", + "version":"0.1.0" + }, + "resources":{ + "Food":{ + "name":{ + "type":"str", + "nullable":false, + "unique":true + }, + "expiration_date":{ + "type":"datetime", + "nullable":false, + "unique":false + } + }, + "Ingredient":{ + "food_id":{ + "type":"uuid", + "foreign_key":"Food.id", + "nullable":true, + "unique":false + }, + "food":{ + "type":"relationship", + "relationship":"Food", + "relationship_list":false, + "nullable":false, + "unique":false + }, + "recipe_id":{ + "type":"uuid", + "foreign_key":"Recipe.id", + "nullable":true, + "unique":false + }, + "recipe":{ + "type":"relationship", + "relationship":"Recipe", + "relationship_list":false, + "nullable":false, + "unique":false + } + }, + "Recipe":{ + "name":{ + "type":"str", + "nullable":false, + "unique":true + }, + "ingredients":{ + "type":"relationship", + "relationship":"Ingredient", + "relationship_list":true, + "nullable":false, + "unique":false + }, + "cook_id":{ + "type":"uuid", + "foreign_key":"Cook.id", + "nullable":true, + "unique":false + }, + "cook":{ + "type":"relationship", + "relationship":"Cook", + "relationship_list":false, + "nullable":false, + "unique":false + } + }, + "Cook":{ + "name":{ + "type":"str", + "nullable":false, + "unique":true + }, + "age":{ + "type":"int", + "nullable":false, + "unique":false + }, + "recipes":{ + "type":"relationship", + "relationship":"Recipe", + "relationship_list":true, + "nullable":false, + "unique":false + }, + "rat":{ + "type":"relationship", + "relationship":"Rat", + "relationship_list":false, + "nullable":false, + "unique":false + } + }, + "Rat":{ + "name":{ + "type":"str", + "nullable":false, + "unique":true + }, + "age":{ + "type":"int", + "nullable":false, + "unique":false + }, + "cook_id":{ + "type":"uuid", + "foreign_key":"Cook.id", + "nullable":true, + "unique":true + }, + "cook":{ + "type":"relationship", + "relationship":"Cook", + "relationship_list":false, + "nullable":false, + "unique":false + } + } + } +} +``` + +!!! tip "Want to master the syntax of Blitz?" + + You can **[learn here](/blitz/blitzfile/)** how the Blitz File work. \ No newline at end of file diff --git a/docs/cli/clone.md b/docs/cli/clone.md new file mode 100644 index 0000000..074e7c4 --- /dev/null +++ b/docs/cli/clone.md @@ -0,0 +1,27 @@ +# Clone + +With clone you can create a new Blitz project from a Blitz App running on a remote server. + +A Blitz App can expose the `/blitz-file` endpoint which is the Blitz file of the current running Blitz App. + +!!! tip + You can desactivate this feature with `blitz start --no-config-route` option. + +You can try it with the demo: +```console +blitz clone https://demo.blitz.paperz.app/blitz-file +``` + + + +
+ +```console +$ blitz clone https://demo.blitz.paperz.app/blitz-file + +Demo Blitz App created successfully ! +To start your app, you can use: + blitz start demo-blitz-app +``` + +
\ No newline at end of file diff --git a/docs/cli/start.md b/docs/cli/start.md index 738c24a..d132085 100644 --- a/docs/cli/start.md +++ b/docs/cli/start.md @@ -1,4 +1,4 @@ -The `blitz start` command is used to start an existing blitz app. It will start the blitz API, the blitz admin and the blitz UI. +The `blitz start` command is used to start an existing Blitz App. It will start the Blitz API, the blitz admin and the blitz UI. @@ -24,3 +24,15 @@ $ blitz start your-blitz-app !!! note Use `blitz create --help` to see all available options. + +## --url + +With the `--url` option, you can start a Blitz App directly from a remote server Blitz File exposed on the `/blitz-file` route. + +You can try it with the demo: +```console +blitz start --url https://demo.blitz.paperz.app/blitz-file +``` + +!!! tips + You can clone the project locally with the [clone command](/blitz/cli/clone/) \ No newline at end of file diff --git a/docs/dashboard/admin.md b/docs/dashboard/admin.md index e69de29..92c5e76 100644 --- a/docs/dashboard/admin.md +++ b/docs/dashboard/admin.md @@ -0,0 +1,5 @@ +# Admin +The admin is provided by [Starlette Admin](https://github.com/jowilf/starlette-admin) + +Check the [admin from the Live Demo](https://demo.blitz.paperz.app/admin/). + diff --git a/docs/dashboard/blitz_file.md b/docs/dashboard/blitz_file.md index e69de29..de71188 100644 --- a/docs/dashboard/blitz_file.md +++ b/docs/dashboard/blitz_file.md @@ -0,0 +1,6 @@ +# Blitz File Editor + +The Dashboard has a Blitz file editor (only JSON for now) to directly create or update your resources. + +You can test our [Blitz file editor in the Live Demo](https://demo.blitz.paperz.app/dashboard/projects/demo-blitz-app/blitz-file). + diff --git a/docs/dashboard/diagram.md b/docs/dashboard/diagram.md index e69de29..2caf390 100644 --- a/docs/dashboard/diagram.md +++ b/docs/dashboard/diagram.md @@ -0,0 +1,3 @@ +# Diagram + +The demo diagram is [available here](https://demo.blitz.paperz.app/dashboard/projects/demo-blitz-app/diagram). \ No newline at end of file diff --git a/docs/dashboard/gpt_builder.md b/docs/dashboard/gpt_builder.md index e69de29..8bc925c 100644 --- a/docs/dashboard/gpt_builder.md +++ b/docs/dashboard/gpt_builder.md @@ -0,0 +1,17 @@ +# GPT Builder + +You can chat with GPT to create or improve Blitz file. + +You have to set an OpenAI API Key in the settings (or as environment variable for local projects). + +We will automaticly detect valid Blitz File and you will be able to copy to clipboard or download in yaml or Json. + +You can [chat with our builder in the Live Demo](https://demo.blitz.paperz.app/dashboard/gpt). + +Features: + +- Detect valid and invalid Blitz files. +- Change or update the pre-prompt, to provide your context and your needs to GPT. +- Choose between GPT 3.5 turbo and GPT 4. + + diff --git a/docs/dashboard/index.md b/docs/dashboard/index.md index 3f88219..5b08875 100644 --- a/docs/dashboard/index.md +++ b/docs/dashboard/index.md @@ -1 +1,18 @@ -Blitz has a dashboard and an admin. +# Overview +Blitz has a native dashboard and an admin. + +You can test it in our [Live Demo](https://demo.blitz.paperz.app) + +# Main features +- **Swagger UI**: You can interect with the swagger ui directly in the Blitz Dashboard. +- **Blitz File Editor**: The dashboard provides users with direct access to the Blitz file, allowing them to make instantaneous modifications as needed. +- **Panel Admin Data Management**: Interface for managing database resources, ensuring efficient organization, manipulation, and retrieval of data +- **Dynamic Blitz File Generation**: Utilizing GPT capabilities, users can prompt the system to generate new Blitz files on demand, streamlining the process of creating and updating Blitz files. +- **Mermaid Diagram Visualization** +- **Log Visualization**. + + + + + + \ No newline at end of file diff --git a/docs/dashboard/logs.md b/docs/dashboard/logs.md index e69de29..5fb63bf 100644 --- a/docs/dashboard/logs.md +++ b/docs/dashboard/logs.md @@ -0,0 +1,7 @@ +# Logs + +The log page of the dashboard is always in WIP. + +The [demo version](https://demo.blitz.paperz.app/dashboard/projects/demo-blitz-app/logs) is anonymised. + +Run the [blitz demo locally](/blitz/) to see more. diff --git a/docs/dashboard/swagger.md b/docs/dashboard/swagger.md index e69de29..d4b02f9 100644 --- a/docs/dashboard/swagger.md +++ b/docs/dashboard/swagger.md @@ -0,0 +1,6 @@ +# Swagger + +You can interact with the swagger directly inside the Blitz Dashboard. + +You can play with the [Swagger from the Live Demo](https://demo.blitz.paperz.app/dashboard/projects/demo-blitz-app/swagger). + diff --git a/docs/features.md b/docs/features.md index 4cf0f59..f78e847 100644 --- a/docs/features.md +++ b/docs/features.md @@ -14,6 +14,6 @@ Get a swagger UI for all you routes with automatic documentation. Internally manages database schema and generates data migration to keep your database up to date with your Blitz file. -## Dashboard +## Dashboard & Admin Use the intuitive dashboard to build your Blitz app, manage your data and test your API. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index de21310..c9912ce 100644 --- a/docs/index.md +++ b/docs/index.md @@ -131,6 +131,10 @@ To start your app, you can use: *And yeah, that's it.* +!!! tip "Want to master Blitz?" + + You can **[learn here](/blitz/blitzfile/)** how to create resources. + Just add some resources in the blitz file, and you now have a fully functional API and the corresponding database schema, along with all the modern features you can expect from a modern app like: - **Automatic Swagger UI** for the API diff --git a/mkdocs.yml b/mkdocs.yml index 740540f..2a8e355 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -97,6 +97,7 @@ nav: - Start: cli/start.md - List: cli/list.md - Release: cli/release.md + - Clone: cli/clone.md - References: cli/references.md - API: - Blitz API: api/index.md @@ -105,6 +106,7 @@ nav: - Admin: dashboard/admin.md - Swagger: dashboard/swagger.md - Blitz File Editor: dashboard/blitz_file.md + - GPT Builder: dashboard/gpt_builder.md - Diagram: dashboard/diagram.md - Logs: dashboard/logs.md - - GPT Builder: dashboard/gpt_builder.md +