Feature/doc quickstart (#34)

* update doc

* finish doc

blitz/cli/app.py

@@ -1,20 +1,21 @@
-# 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
 from .commands.release import release_blitz
 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)

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__)

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)

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

docs/api/index.md

@@ -1,2 +1,143 @@
-!!! warning
-    **WORK IN PROGRESS**
+# 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.

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
+```
+
+<!-- termynal -->
+
+<div class="termy">
+
+```console
+$ blitz clone https://demo.blitz.paperz.app/blitz-file
+
+<span style="color: #af87ff; font-weight: bold;">Demo Blitz App</span> created successfully !
+To start your app, you can use:
+    <span style="color: #af87ff; font-weight: bold;">blitz start demo-blitz-app</span>
+```
+
+</div>

docs/cli/index.md

@@ -1,6 +0,0 @@
-# Installation
-
-## Using [pipx](https://pipx.pypa.io/stable/installation/) (recommanded)
-```bash
-pipx install git+https://github.com/Paperz-org/[email protected]
-```

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.
 
 <!-- termynal -->
 
@@ -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/)

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/).
+

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

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).

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

docs/dashboard/index.md

@@ -0,0 +1,18 @@
+# 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**.
+
+
+
+
+
+

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.

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

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.