From f3c517d2e5c7206f2abf65fd3fc91636c4360f76 Mon Sep 17 00:00:00 2001 From: long2ice Date: Tue, 22 Sep 2020 15:28:16 +0800 Subject: [PATCH] complete documentation --- .github/workflows/deploy.yml | 2 +- .github/workflows/docs.yml | 20 ++++++++ .github/workflows/pypi.yml | 2 +- Makefile | 6 ++- README.md | 4 ++ docs/menu.md | 0 docs/site.md | 0 docs/tutorial.md | 99 +++++++++++++++++++++++++++++++++++- mkdocs.yml | 5 +- 9 files changed, 129 insertions(+), 9 deletions(-) create mode 100644 .github/workflows/docs.yml delete mode 100644 docs/menu.md delete mode 100644 docs/site.md diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 0bb20a5..2730989 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -1,5 +1,5 @@ name: deploy -on: push +on: [push, pull_request] jobs: build: runs-on: ubuntu-latest diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..9117b0a --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,20 @@ +name: docs +on: + push: + paths: + - 'docs/**' + pull_request: + paths: + - 'docs/**' +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - uses: actions/setup-python@v1 + with: + python-version: '3.x' + - uses: dschep/install-poetry-action@v1.3 + - name: Deploy docs + run: make deploy-docs + diff --git a/.github/workflows/pypi.yml b/.github/workflows/pypi.yml index 8e8c6d5..561d8cd 100644 --- a/.github/workflows/pypi.yml +++ b/.github/workflows/pypi.yml @@ -18,4 +18,4 @@ jobs: uses: pypa/gh-action-pypi-publish@master with: user: __token__ - password: ${{ secrets.pypi_password }} \ No newline at end of file + password: ${{ secrets.pypi_password }} diff --git a/Makefile b/Makefile index 33e4a81..abade88 100644 --- a/Makefile +++ b/Makefile @@ -35,5 +35,7 @@ build: deps @poetry build docs: deps - @pip install -r docs/requirements.txt - @sphinx-build docs/ docs/_build \ No newline at end of file + @mkdocs build + +deploy-docs: docs + @mkdocs gh-deploy diff --git a/README.md b/README.md index 2fc403f..0730da2 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,10 @@ async def startup(): ) ``` +## Documentation + +See documentation at [https://long2ice.github.io/fastapi-admin](https://long2ice.github.io/fastapi-admin). + ## Deployment Deploy fastapi app by gunicorn+uvicorn or reference diff --git a/docs/menu.md b/docs/menu.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/site.md b/docs/site.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/tutorial.md b/docs/tutorial.md index 573c978..80cad86 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -1,7 +1,102 @@ ## Import app +First of all suppose you have a fastapi+tortoise-orm project and running normally, then first you should is import admin app from `fastapi-admin` and mount in root fastapi app. + +```python hl_lines="6" +from fastapi_admin.factory import app as admin_app + +def create_app(): + fast_app = FastAPI(debug=False) + register_tortoise(fast_app, config=TORTOISE_ORM) + fast_app.mount("/admin", admin_app) + return fast_app + + +app = create_app() + +if __name__ == "__main__": + uvicorn.run("main:app", port=8000, debug=False, reload=False, lifespan="on") + +``` + +Now you can visit `http://127.0.0.1:8000/admin/docs` see all restful api comes from fastapi-admin. + ## Init App -## Site configuration +After mount admin app, you should init app now. Pay attention to that you should init admin app in fastapi `startup` event instead of run it directly. -## Menu configuration +```python +@app.on_event("startup") +async def start_up(): + await admin_app.init( # nosec + admin_secret="test", + permission=True, + admin_log=True, + site=Site( + name="FastAPI-Admin DEMO", + login_footer="FASweTAPI ADMIN - FastAPI Admin Dashboard", + login_description="FastAPI Admin Dashboard", + locale="en-US", + locale_switcher=True, + theme_switcher=True, + menus=[ + Menu(name="Home", url="/", icon="fa fa-home"), + Menu( + name="Content", + children=[ + Menu( + name="Category", + url="/rest/Category", + icon="fa fa-list", + search_fields=("slug",), + ), + Menu( + name="Config", + url="/rest/Config", + icon="fa fa-gear", + import_=True, + search_fields=("key",), + ), + Menu( + name="Product", + url="/rest/Product", + icon="fa fa-table", + search_fields=("name",), + ), + ], + ), + Menu( + name="External", + children=[ + Menu( + name="Github", + url="https://github.com/long2ice/fastapi-admin", + icon="fa fa-github", + external=True, + ), + ], + ), + Menu( + name="Auth", + children=[ + Menu( + name="User", + url="/rest/User", + icon="fa fa-user", + search_fields=("username",), + ), + Menu(name="Role", url="/rest/Role", icon="fa fa-group",), + Menu(name="Permission", url="/rest/Permission", icon="fa fa-user-plus",), + Menu( + name="AdminLog", + url="/rest/AdminLog", + icon="fa fa-align-left", + search_fields=("action", "admin", "model"), + ), + Menu(name="Logout", url="/logout", icon="fa fa-lock",), + ], + ), + ], + ), + ) +``` diff --git a/mkdocs.yml b/mkdocs.yml index 569c78b..eb71187 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,10 +10,9 @@ theme: repo: fontawesome/brands/github markdown_extensions: - pymdownx.highlight + - pymdownx.inlinehilite - pymdownx.superfences nav: - index.md - - features.md - tutorial.md - - site_define.md - - menu_define.md + - features.md