Improved docs
This commit is contained in:
parent
577d61ed42
commit
bf27a344e1
@ -20,7 +20,7 @@ spec:
|
||||
spec:
|
||||
containers:
|
||||
- name: m4g-docs
|
||||
image: m4g_docs:latest
|
||||
image: m4gdocs:latest
|
||||
imagePullPolicy: Never
|
||||
ports:
|
||||
- containerPort: 80
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Commands
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
sidebar_position: 6
|
||||
---
|
||||
|
||||
# Command plugins
|
||||
@ -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
|
||||
```
|
||||
|
||||
@ -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 <name>`
|
||||
|
||||
```
|
||||
Description:
|
||||
Initialize a new project
|
||||
|
||||
Usage:
|
||||
m4g init <name> [options]
|
||||
|
||||
Arguments:
|
||||
<name> The name of your project
|
||||
|
||||
Options:
|
||||
--without <api|db|git> Features to exclude
|
||||
-?, -h, --help Show help and usage information
|
||||
|
||||
```
|
||||
|
||||
Running this command will generate the following project structure.
|
||||
|
||||
```
|
||||
📦<project_name>
|
||||
┣ 📂.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
|
||||
Get started with MycroForge and enhance your backend development efficiency today!
|
||||
|
||||
111
docs/docs/project_layout.md
Normal file
111
docs/docs/project_layout.md
Normal file
@ -0,0 +1,111 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Project layout
|
||||
|
||||
When you generate a new project with `m4g init <project_name>`, it will create a folder like the example below.
|
||||
|
||||
```
|
||||
📦<project_name>
|
||||
┣ 📂.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.
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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. <code>m4g init todo-app</code>
|
||||
Start a new FastAPI and SQLAlchemy project with a single command.
|
||||
For example: <code>m4g init todo-app</code>
|
||||
</>
|
||||
),
|
||||
},
|
||||
{
|
||||
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 (
|
||||
<div className={clsx('col col--4')}>
|
||||
<div className={clsx('col col--4', styles.feature)}>
|
||||
<div className="text--center">
|
||||
<Svg className={styles.featureSvg} role="img" />
|
||||
</div>
|
||||
|
||||
@ -20,7 +20,7 @@ function HomepageHeader() {
|
||||
<Link
|
||||
className="button button--secondary button--lg"
|
||||
to="/docs/intro">
|
||||
MycroForge Tutorial
|
||||
Get started now!
|
||||
</Link>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user