From bf27a344e1aca0bdcb8f52e7d879a89f20cc1bfb Mon Sep 17 00:00:00 2001 From: mdnapo Date: Fri, 19 Jul 2024 13:08:59 +0200 Subject: [PATCH] Improved docs --- docs/.k8s/local.yml | 2 +- docs/docs/Commands/index.md | 2 +- docs/docs/command_plugins.md | 2 +- docs/docs/getting_started.md | 31 ++-- docs/docs/intro.md | 145 ++---------------- docs/docs/project_layout.md | 111 ++++++++++++++ docs/docs/tutorial.md | 15 +- .../src/components/HomepageFeatures/index.tsx | 18 +-- docs/src/pages/index.tsx | 2 +- 9 files changed, 162 insertions(+), 166 deletions(-) create mode 100644 docs/docs/project_layout.md diff --git a/docs/.k8s/local.yml b/docs/.k8s/local.yml index de0e08f..951d084 100644 --- a/docs/.k8s/local.yml +++ b/docs/.k8s/local.yml @@ -20,7 +20,7 @@ spec: spec: containers: - name: m4g-docs - image: m4g_docs:latest + image: m4gdocs:latest imagePullPolicy: Never ports: - containerPort: 80 diff --git a/docs/docs/Commands/index.md b/docs/docs/Commands/index.md index 830f089..71f15e8 100644 --- a/docs/docs/Commands/index.md +++ b/docs/docs/Commands/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 --- # Commands diff --git a/docs/docs/command_plugins.md b/docs/docs/command_plugins.md index b3b71b8..f95d460 100644 --- a/docs/docs/command_plugins.md +++ b/docs/docs/command_plugins.md @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 --- # Command plugins \ No newline at end of file diff --git a/docs/docs/getting_started.md b/docs/docs/getting_started.md index d2583cd..86878e5 100644 --- a/docs/docs/getting_started.md +++ b/docs/docs/getting_started.md @@ -2,27 +2,38 @@ sidebar_position: 2 --- -# Getting started +# Getting Started ## Requirements -MycroForge has the following dependencies. +To use MycroForge, ensure you have the following dependencies installed: -- bash -- git -- Python3 (3.10) -- Docker -- .NET 8 +- **bash** +- **git** +- **Python 3.10** +- **Docker** +- **.NET 8** ### Windows -To simplify the implementation of this tool, it assumes that it's running in a POSIX compliant environment. -MycroForge has been developed and tested on Windows in WSL2 Ubuntu 22.04.03. -So when running on Windows, it's recommended to run MycroForge in the same environment or atleast in a similar WSL2 distro. +For Windows users, MycroForge is designed to run in a POSIX compliant environment. It has been tested on Windows using WSL2 with Ubuntu 22.04.03. Therefore, it is recommended to run MycroForge within the same or a similar WSL2 distribution for optimal performance. +### Adding the Package Registry + +Before installing MycroForge, add the package registry by running the following command: + +```sh +dotnet nuget add source --name devdisciples https://git.devdisciples.com/api/packages/devdisciples/nuget/index.json +``` ### Install ``` dotnet tool install -g MycroForge.CLI ``` + +### Uninstall + +``` +dotnet tool install -g MycroForge.CLI +``` diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 68cc72d..e886c30 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -2,144 +2,21 @@ sidebar_position: 1 --- + # Intro -## What is MycroForge? +Welcome to **MycroForge** – an opinionated CLI tool designed to streamline the development of FastAPI and SQLAlchemy-based backends. With MycroForge, you can effortlessly create and manage your backend projects through a powerful command line interface. -MycroForge is an opinionated CLI tool that is meant to facilitate the development of FastAPI & SQLAlchemy based backends. -It provides a command line interface that allows users to generate a skeleton project and other common items like -database entities, migrations, routers and even basic CRUD functionality. The main purpose of this tool is to generate -boilerplate code and to provide a unified interface for performing recurrent development activities. +## Key Features +- **Project Skeleton Generation:** Quickly generate a well-structured project skeleton tailored for FastAPI and SQLAlchemy, ensuring you start with best practices. +- **Database Entities:** Easily create and manage database entities, simplifying your database interactions. +- **Migrations:** Handle database migrations seamlessly, allowing for smooth transitions and updates. +- **Routers:** Generate and manage routers to keep your application modular and organized. +- **CRUD Functionality:** Automatically generate basic CRUD (Create, Read, Update, Delete) operations to accelerate your development process. -## Generating a project +## Purpose -To generate a project you can run the following command. +The primary goal of MycroForge is to reduce the boilerplate code and provide a unified interface for common development tasks. By leveraging this tool, developers can focus more on writing business logic rather than repetitive setup and configuration. -`m4g init ` - -``` -Description: - Initialize a new project - -Usage: - m4g init [options] - -Arguments: - The name of your project - -Options: - --without Features to exclude - -?, -h, --help Show help and usage information - -``` - -Running this command will generate the following project structure. - -``` -📦 - ┣ 📂.git - ┣ 📂.venv - ┣ 📂api - ┃ ┗ 📂routers - ┃ ┃ ┗ 📜hello.py - ┣ 📂db - ┃ ┣ 📂engine - ┃ ┃ ┗ 📜async_session.py - ┃ ┣ 📂entities - ┃ ┃ ┗ 📜entity_base.py - ┃ ┣ 📂versions - ┃ ┣ 📜README - ┃ ┣ 📜env.py - ┃ ┣ 📜script.py.mako - ┃ ┗ 📜settings.py - ┣ 📜.gitignore - ┣ 📜alembic.ini - ┣ 📜db.docker-compose.yml - ┣ 📜m4g.json - ┣ 📜main.py - ┗ 📜requirements.txt -``` - -Let's go through these one by one. - -### .git - -The `m4g init` command will initialize new projects with git by default. -If you don't want to use git you can pass the option `--without git` to `m4g init`. - -### .venv - -To promote isolation of Python dependencies, new projects are initialized with a virtual environment by default. -TODO: This is a good section to introduce the `m4g hydrate` command. - -### api/routers/hello.py - -This file defines a basic example router, which is imported and mapped in `main.py`. This router is just an example and -can be removed or modified at you discretion. - -### db/engine/async_session.py - -This file defines the `async_session` function, which can be used to open an asynchronous session to a database. - -### db/entities/entity_base.py - -This file contains an automatically generated entity base class that derives from the DeclarativeBase. -All entities must inherit from this class, so that SQLAlchemy & alembic can track them. The entities directory is also -where all newly generated entities will be stored. - -### db/versions - -This is where the generated database migrations will be stored. - -### db/README - -This README file is automatically generated by the alembic init command. - -### db/env.py - -This is the database environment file that is used by alembic to interact with the database. -If you take a closer look at the imports, you'll see that the file has been modified to assign `EntityBase.metadata` to -a variable called `target_metadata`, this will allow alembic to track changes in your entities. You'll also find that -the `DbSettings` class is used to get the connectionstring. Any time you generate a new database entity, or create a -many-to-many relation between two entities, this file will also be modified to include the generated classes. - -### db/script.py.mako - -This file is automatically generated by the alembic init command. - -### db/settings.py - -This file defines the `DbSettings` class, that is responsible for retrieving the database connectionstring. -You will probably want to modify this class to retrieve the connectionstring from a secret manager at some point. - -### .gitignore - -The default .gitignore file that is generated by the `m4g init` command. Modify this file at your discretion. - -### alembic.ini - -This file is automatically generated by the alembic init command. - -### db.docker-compose.yml - -A docker compose file for running a database locally. - -### m4g.json - -This file contains some configs that are used by the CLI, for example the ports to map to the API and database. - -### main.py - -The entrypoint for the application. When generating entities, many-to-many relations or routers, this file will be -modified to include the generated files. - -### requirements.txt - -The requirements file containing the Python dependencies. -TODO: introduce the `m4g install` & `m4g uninstall` commands. - - -## Plugin system - -TODO: Dedicate a section to the Plugin system \ No newline at end of file +Get started with MycroForge and enhance your backend development efficiency today! diff --git a/docs/docs/project_layout.md b/docs/docs/project_layout.md new file mode 100644 index 0000000..977bacb --- /dev/null +++ b/docs/docs/project_layout.md @@ -0,0 +1,111 @@ +--- +sidebar_position: 4 +--- + +# Project layout + +When you generate a new project with `m4g init `, it will create a folder like the example below. + +``` +📦 + ┣ 📂.git + ┣ 📂.venv + ┣ 📂api + ┃ ┗ 📂routers + ┃ ┃ ┗ 📜hello.py + ┣ 📂db + ┃ ┣ 📂engine + ┃ ┃ ┗ 📜async_session.py + ┃ ┣ 📂entities + ┃ ┃ ┗ 📜entity_base.py + ┃ ┣ 📂versions + ┃ ┣ 📜README + ┃ ┣ 📜env.py + ┃ ┣ 📜script.py.mako + ┃ ┗ 📜settings.py + ┣ 📜.gitignore + ┣ 📜alembic.ini + ┣ 📜db.docker-compose.yml + ┣ 📜m4g.json + ┣ 📜main.py + ┗ 📜requirements.txt +``` + +Let's go through these one by one. + +### .git + +The `m4g init` command will initialize new projects with git by default. +If you don't want to use git you can pass the option `--without git` to `m4g init`. + +### .venv + +To promote isolation of Python dependencies, new projects are initialized with a virtual environment by default. +When you clone a MycroForge repository from git, it won't have a `.venv` folder yet. +You can run `m4g hydrate` in the root folder of the project to restore the dependencies. + +### api/routers/hello.py + +This file defines a basic example router, which is imported and mapped in `main.py`. This router is just an example and +can be removed or modified at you discretion. + +### db/engine/async_session.py + +This file defines the `async_session` function, which can be used to open an asynchronous session to a database. + +### db/entities/entity_base.py + +This file contains an automatically generated entity base class that derives from the DeclarativeBase. +All entities must inherit from this class, so that SQLAlchemy & alembic can track them. The entities directory is also +where all newly generated entities will be stored. + +### db/versions + +This is where the generated database migrations will be stored. + +### db/README + +This README file is automatically generated by the alembic init command. + +### db/env.py + +This is the database environment file that is used by alembic to interact with the database. +If you take a closer look at the imports, you'll see that the file has been modified to assign `EntityBase.metadata` to +a variable called `target_metadata`, this will allow alembic to track changes in your entities. You'll also find that +the `DbSettings` class is used to get the connectionstring. Any time you generate a new database entity, or create a +many-to-many relation between two entities, this file will also be modified to include the generated classes. + +### db/script.py.mako + +This file is automatically generated by the alembic init command. + +### db/settings.py + +This file defines the `DbSettings` class, that is responsible for retrieving the database connectionstring. +You will probably want to modify this class to retrieve the connectionstring from a secret manager at some point. + +### .gitignore + +The default .gitignore file that is generated by the `m4g init` command. Modify this file at your discretion. + +### alembic.ini + +This file is automatically generated by the alembic init command. + +### db.docker-compose.yml + +A docker compose file for running a database locally. + +### m4g.json + +This file contains some configs that are used by the CLI, for example the ports to map to the API and database. + +### main.py + +The entrypoint for the application. When generating entities, many-to-many relations or routers, this file will be +modified to include the generated files. + +### requirements.txt + +The requirements file containing the Python dependencies. +Whenever you run `m4g install` or `m4g uninstall` this file will be updated too. diff --git a/docs/docs/tutorial.md b/docs/docs/tutorial.md index d434ca4..7d6b1b2 100644 --- a/docs/docs/tutorial.md +++ b/docs/docs/tutorial.md @@ -4,20 +4,17 @@ sidebar_position: 3 # Tutorial -We're going to build a simple todo app to demonstrate the capabilities of the MycroForge CLI. -After this tutorial, you should have a solid foundation to start exploring and using MycroForge to develop your -projects. +In this tutorial, we'll build a simple todo app to demonstrate the capabilities of the MycroForge CLI. +By the end, you should have a solid foundation to start exploring and using MycroForge for your projects. ## General notes -The commands in this tutorial assume that you're running them from a MycroForge root directory. +The commands in this tutorial assume that you are running them from the root directory of your MycroForge project. -## Initialize the project +## Initialize the Project -Open a terminal and `cd` into the directory where your project should be created. -Run `m4g init todo-app` to initialize a new project and open the newly created project by running `code todo-app`. -Make sure you have `vscode` on you machine before running this command. If you prefer using another editor, then -manually open the generated `todo-app` folder. +Open a terminal and navigate (`cd`) to the directory where your project should be created. +Run the following command to initialize a new project and open it in VSCode: ## Setup the database diff --git a/docs/src/components/HomepageFeatures/index.tsx b/docs/src/components/HomepageFeatures/index.tsx index 5ebf53a..7656165 100644 --- a/docs/src/components/HomepageFeatures/index.tsx +++ b/docs/src/components/HomepageFeatures/index.tsx @@ -10,22 +10,22 @@ type FeatureItem = { const FeatureList: FeatureItem[] = [ { - title: 'Initialize a skeleton project quickly', + title: 'Initialize a Skeleton Project Quickly', Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default, description: ( <> - Initialize a skeleton project that supports FastAPI and SQLAlchemy with a single command. - Here is an example. m4g init todo-app + Start a new FastAPI and SQLAlchemy project with a single command. + For example: m4g init todo-app ), }, { - title: 'Generate common items', + title: 'Generate Common Items', Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default, description: ( <> - MycroForge allows you to generate boilerplate code for common items like entities, service & routers. - It can even generate a basic CRUD setup around an entity! + Use MycroForge to generate boilerplate code for entities, services, and routers. + It even supports basic CRUD setup! ), }, @@ -34,15 +34,15 @@ const FeatureList: FeatureItem[] = [ Svg: require('@site/static/img/undraw_docusaurus_react.svg').default, description: ( <> - Extend MycroForge with your own commands by creating a plugin! + Create plugins to extend MycroForge with your own custom commands. ), }, ]; -function Feature({title, Svg, description}: FeatureItem) { +function Feature({ title, Svg, description }: FeatureItem) { return ( -
+
diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx index 15464c1..207bace 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -20,7 +20,7 @@ function HomepageHeader() { - MycroForge Tutorial + Get started now!