add docs

.github/workflows/gh-pages.yml

@@ -0,0 +1,25 @@
+name: gh-pages
+on:
+  push:
+    branches:
+      - dev
+    paths:
+      - 'docs/*'
+      - '.github/workflows/gh-pages.yml'
+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: build
+        run: make docs
+      - name: deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_build
+          cname: fastapi-admin-docs.long2ice.cn

Makefile

@@ -41,3 +41,7 @@ build: deps
 
 publish: deps
 	@poetry publish
+
+docs: deps
+	@pip install -r docs/requirements.txt
+	@sphinx-build docs/ docs/_build

README.rst

@@ -270,6 +270,14 @@ Deployment
 ==========
 Deploy fastapi app by gunicorn+uvicorn or reference https://fastapi.tiangolo.com/deployment/.
 
+Restful API Docs
+================
+See `restful api <https://api-fastapi-admin.long2ice.cn:8443/admin/docs>`_ docs.
+
+Documents
+=========
+See `documents <https://fastapi-admin-docs.long2ice.cn>`_ for reference.
+
 ThanksTo
 ========
 

docs/api_reference.rst

@@ -0,0 +1,8 @@
+=============
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 3
+
+   fastapi_admin

docs/changelog.rst

@@ -0,0 +1 @@
+../CHANGELOG.rst

docs/conf.py

@@ -0,0 +1,60 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+from fastapi_admin import __version__
+
+project = 'fastapi-admin'
+copyright = '2020, long2ice'
+author = 'long2ice'
+
+release = f'v{__version__}'
+version = f'v{__version__}'
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.todo',
+    'sphinx.ext.coverage',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.githubpages',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

docs/examples.rst

@@ -0,0 +1,19 @@
+========
+Examples
+========
+
+Enums
+=====
+.. literalinclude::  ../examples/enums.py
+
+Main
+====
+.. literalinclude::  ../examples/main.py
+
+models
+======
+.. literalinclude::  ../examples/models.py
+
+Routes
+======
+.. literalinclude::  ../examples/routes.py

docs/fastapi_admin.routes.rst

@@ -0,0 +1,30 @@
+fastapi\_admin.routes package
+=============================
+
+Submodules
+----------
+
+fastapi\_admin.routes.rest module
+---------------------------------
+
+.. automodule:: fastapi_admin.routes.rest
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fastapi\_admin.routes.site module
+---------------------------------
+
+.. automodule:: fastapi_admin.routes.site
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: fastapi_admin.routes
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/fastapi_admin.rst

@@ -0,0 +1,110 @@
+fastapi\_admin package
+======================
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   fastapi_admin.routes
+
+Submodules
+----------
+
+fastapi\_admin.cli module
+-------------------------
+
+.. automodule:: fastapi_admin.cli
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fastapi\_admin.common module
+----------------------------
+
+.. automodule:: fastapi_admin.common
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fastapi\_admin.depends module
+-----------------------------
+
+.. automodule:: fastapi_admin.depends
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fastapi\_admin.enums module
+---------------------------
+
+.. automodule:: fastapi_admin.enums
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fastapi\_admin.exceptions module
+--------------------------------
+
+.. automodule:: fastapi_admin.exceptions
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fastapi\_admin.factory module
+-----------------------------
+
+.. automodule:: fastapi_admin.factory
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fastapi\_admin.models module
+----------------------------
+
+.. automodule:: fastapi_admin.models
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fastapi\_admin.responses module
+-------------------------------
+
+.. automodule:: fastapi_admin.responses
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fastapi\_admin.schemas module
+-----------------------------
+
+.. automodule:: fastapi_admin.schemas
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fastapi\_admin.shortcuts module
+-------------------------------
+
+.. automodule:: fastapi_admin.shortcuts
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+fastapi\_admin.site module
+--------------------------
+
+.. automodule:: fastapi_admin.site
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: fastapi_admin
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/get_start.rst

@@ -0,0 +1,286 @@
+===============
+Getting started
+===============
+
+.. image:: https://img.shields.io/pypi/v/fastapi-admin.svg?style=flat
+   :target: https://pypi.python.org/pypi/fastapi-admin
+.. image:: https://img.shields.io/github/license/long2ice/fastapi-admin
+   :target: https://github.com/long2ice/fastapi-admin
+.. image:: https://github.com/long2ice/fastapi-admin/workflows/gh-pages/badge.svg
+   :target: https://github.com/long2ice/fastapi-admin/actions?query=workflow:gh-pages
+.. image:: https://github.com/long2ice/fastapi-admin/workflows/pypi/badge.svg
+   :target: https://github.com/long2ice/fastapi-admin/actions?query=workflow:pypi
+
+`中文文档 <https://blog.long2ice.cn/2020/05/fastapi-admin%E5%BF%AB%E9%80%9F%E6%90%AD%E5%BB%BA%E5%9F%BA%E4%BA%8Efastapi%E4%B8%8Etortoise-orm%E7%9A%84%E7%AE%A1%E7%90%86%E5%90%8E%E5%8F%B0/>`_
+
+
+Introduction
+============
+
+FastAPI-Admin is a admin dashboard based on `fastapi <https://github.com/tiangolo/fastapi>`_ and `tortoise-orm <https://github.com/tortoise/tortoise-orm>`_.
+
+FastAPI-Admin provide crud feature out-of-the-box with just a few config.
+
+Live Demo
+=========
+Check a live Demo here `https://fastapi-admin.long2ice.cn <https://fastapi-admin.long2ice.cn/>`_.
+
+* username: ``admin``
+* password: ``123456``
+
+Data in database will restore every day.
+
+Screenshots
+===========
+
+.. image:: https://github.com/long2ice/fastapi-admin/raw/master/images/login.png
+.. image:: https://github.com/long2ice/fastapi-admin/raw/master/images/list.png
+.. image:: https://github.com/long2ice/fastapi-admin/raw/master/images/view.png
+.. image:: https://github.com/long2ice/fastapi-admin/raw/master/images/create.png
+
+Requirements
+============
+
+* `FastAPI <https://github.com/tiangolo/fastapi>`_ framework as your backend framework.
+* `Tortoise-ORM <https://github.com/tortoise/tortoise-orm>`_ as your orm framework, by the way, which is best asyncio orm so far and I'm one of the contributors😋.
+
+Quick Start
+===========
+
+Run Example Local
+~~~~~~~~~~~~~~~~~
+Look at `examples <https://github.com/long2ice/fastapi-admin/tree/master/examples>`_.
+
+1. ``git clone https://github.com/long2ice/fastapi-admin.git``.
+2. create database ``fastapi-admin`` and import from ``examples/example.sql``.
+3. ``python setup.py install``.
+4. ``env DATABASE_URL=mysql://root:123456@127.0.0.1:3306/fastapi-admin PYTHONPATH=./ python3 examples/main.py``,then you can see:
+
+.. code-block:: python
+
+    INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+    INFO:     Started reloader process [89005]
+    INFO:     Started server process [89009]
+    INFO:     Waiting for application startup.
+    INFO:     Tortoise-ORM startup
+        connections: {'default': 'mysql://root:123456@127.0.0.1:3306/fastapi-admin'}
+        apps: {'models': {'models': ['examples.models'], 'default_connection': 'default'}}
+    INFO:     Tortoise-ORM started, {'default': <tortoise.backends.mysql.client.MySQLClient object at 0x110ed6760>}, {'models': {'Category': <class 'examples.models.Category'>, 'Product': <class 'examples.models.Product'>, 'User': <class 'examples.models.User'>}}
+    INFO:     Tortoise-ORM generating schema
+    INFO:     Application startup complete.
+
+Backend Integration
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: shell
+
+    $ pip3 install fastapi-admin
+
+.. code-block:: python
+
+    from fastapi_admin.factory import app as admin_app
+
+    fast_app = FastAPI()
+
+    register_tortoise(fast_app, config=TORTOISE_ORM, generate_schemas=True)
+
+    fast_app.mount('/admin', admin_app)
+
+    @fast_app.on_event('startup')
+    async def startup():
+        admin_app.init(
+            user_model='User',
+            tortoise_app='models',
+            admin_secret='test',
+            permission=True,
+            site=Site(...)
+        )
+
+Front
+~~~~~
+See `fastapi-admin-front <https://github.com/long2ice/fastapi-admin-front>`_ for reference.
+
+Features
+========
+
+Builtin Auth And Permissions Control
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Inherit ``fastapi_admin.models.User`` and add you own fields,must contains ``is_active`` and ``is_superuser``.
+
+.. code-block:: python
+
+    from fastapi_admin.models import User as AdminUser
+
+    class AdminUser(AdminUser,Model):
+        is_active = fields.BooleanField(default=False, description='Is Active')
+        is_superuser = fields.BooleanField(default=False, description='Is Superuser')
+        status = fields.IntEnumField(Status, description='User Status')
+        created_at = fields.DatetimeField(auto_now_add=True)
+        updated_at = fields.DatetimeField(auto_now=True)
+
+Then add ``fastapi_admin.models`` to ``Tortoise-ORM`` config, example:
+
+.. code-block:: python
+
+    TORTOISE_ORM = {
+        'connections': {
+            'default': os.getenv('DATABASE_URL')
+        },
+        'apps': {
+            'models': {
+                'models': ['examples.models', 'fastapi_admin.models'],
+                'default_connection': 'default',
+            }
+        }
+    }
+
+And set ``permission=True`` to active it:
+
+.. code-block:: python
+
+        admin_app.init(
+            user_model='AdminUser',
+            admin_secret='123456',
+            models='examples.models',
+            permission=True,
+            site=Site(
+                ...
+            )
+        )
+
+And register permissions and createsuperuser:
+
+.. code-block:: shell
+
+    $ fastapi-admin -h
+    usage: fastapi-admin [-h] -c CONFIG {register_permissions,createsuperuser} ...
+
+    optional arguments:
+      -h, --help            show this help message and exit
+      -c CONFIG, --config CONFIG
+                            Tortoise-orm config dict import path,like settings.TORTOISE_ORM.
+
+    subcommands:
+      {register_permissions,createsuperuser}
+
+Custom Login
+~~~~~~~~~~~~
+You can write your own login view logic:
+
+.. code-block:: python
+
+    admin_app.init(
+        ...
+        login_view="examples.routes.login"
+    )
+
+And must return json like:
+
+.. code-block:: json
+
+    {
+        "user": {
+            "username": "admin",
+            "is_superuser": False,
+            "avatar": "https://avatars2.githubusercontent.com/u/13377178?s=460&u=d150d522579f41a52a0b3dd8ea997e0161313b6e&v=4",
+        },
+        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyfQ.HSlcYkOEQewxyPuaqcVwCcw_wkbLB50Ws1-ZxfPoLAQ",
+    }
+
+Enum Support
+~~~~~~~~~~~~
+When you define a enum field of tortoise-orm,like ``IntEnumField``,you can inherit ``fastapi_admin.enums.EnumMixin`` and impl ``choices()`` method,
+FastAPI-Admin will auto read and display and render a ``select`` widget in front.
+
+.. code-block:: python
+
+    class Status(EnumMixin, IntEnum):
+        on = 1
+        off = 2
+
+        @classmethod
+        def choices(cls):
+            return {
+                cls.on: 'ON',
+                cls.off: 'OFF'
+            }
+
+Verbose Name
+~~~~~~~~~~~~
+FastAPI-Admin will auto read ``description`` defined in tortoise-orm model ``Field`` and display in front.
+
+ForeignKeyField Support
+~~~~~~~~~~~~~~~~~~~~~~~
+If ``ForeignKeyField`` not passed in ``menu.raw_id_fields``,FastAPI-Admin will get all related objects and display ``select`` in front with ``Model.__str__``.
+
+ManyToManyField Support
+~~~~~~~~~~~~~~~~~~~~~~~
+FastAPI-Admin will render ``ManyToManyField`` with multiple ``select`` in ``form`` edit with ``Model.__str__``.
+
+JSONField Render
+~~~~~~~~~~~~~~~~
+FastAPI-Admin will render ``JSONField`` with ``jsoneditor`` as beauty interface.
+
+Search Fields
+~~~~~~~~~~~~~
+Defined ``menu.search_fields`` in ``menu`` will render a search form by fields.
+
+Xlsx Export
+~~~~~~~~~~~
+FastAPI-Admin can export searched data to excel file when define ``export=True`` in ``menu``.
+
+Bulk Actions
+~~~~~~~~~~~~
+Current FastAPI-Admin support builtin bulk action ``delete_all``,if you want write your own bulk actions:
+
+1. pass ``bulk_actions`` in ``Menu``,example:
+
+.. code-block:: python
+
+    Menu(
+        ...
+        bulk_actions=[{
+            'value': 'delete', # this is fastapi router path param.
+            'text': 'delete_all', # this will show in front.
+        }]
+    )
+
+2. write fastapi route,example:
+
+.. code-block:: python
+
+    from fastapi_admin.schemas import BulkIn
+    from fastapi_admin.factory import app as admin_app
+
+    @admin_app.post(
+        '/rest/{resource}/bulk/delete' # `delete` is defined in Menu before.
+    )
+    async def bulk_delete(
+            bulk_in: BulkIn,
+            model=Depends(get_model)
+    ):
+        await model.filter(pk__in=bulk_in.pk_list).delete()
+        return {'success': True}
+
+Default Menus
+~~~~~~~~~~~~~
+Default, FastAPI-Admin provide default menus by your models, without doing tedious works.
+
+Deployment
+==========
+Deploy fastapi app by gunicorn+uvicorn or reference https://fastapi.tiangolo.com/deployment/.
+
+Restful API Docs
+================
+See `restful api <https://api-fastapi-admin.long2ice.cn:8443/admin/docs>`_ docs.
+
+ThanksTo
+========
+
+* `fastapi <https://github.com/tiangolo/fastapi>`_ ,high performance async api framework.
+* `tortoise-orm <https://github.com/tortoise/tortoise-orm>`_ ,familiar asyncio ORM for python.
+
+License
+=======
+
+This project is licensed under the `MIT <https://github.com/long2ice/fastapi-admin/blob/master/LICENSE>`_ License.

docs/index.rst

@@ -0,0 +1,29 @@
+.. fastapi-admin documentation master file, created by
+   sphinx-quickstart on Sun Jun  7 16:40:53 2020.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to fastapi-admin's documentation!
+=========================================
+
+FastAPI-Admin is a admin dashboard based on `fastapi <https://github.com/tiangolo/fastapi>`_ and `tortoise-orm <https://github.com/tortoise/tortoise-orm>`_.
+
+FastAPI-Admin provide crud feature out-of-the-box with just a few config.
+
+Contents
+========
+
+.. toctree::
+   :maxdepth: 4
+
+   get_start
+   examples
+   api_reference
+   changelog
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx-rtd-theme
+sphinx-autodoc-typehints
+pygments
+sphinx

examples/main.py

@@ -40,10 +40,7 @@ app = create_app()
 
 @app.on_event("startup")
 async def start_up():
-    admin_app.debug = False
     admin_app.init(
-        user_model="User",
-        tortoise_app="models",
         admin_secret="test",
         permission=True,
         site=Site(

fastapi_admin/factory.py

@@ -134,10 +134,10 @@ class AdminApp(FastAPI):
     def init(
         self,
         site: Site,
-        user_model: str,
-        tortoise_app: str,
         admin_secret: str,
+        user_model: str = "User",
         permission: bool = False,
+        tortoise_app: str = "models",
         login_view: Optional[str] = None,
     ):
         """
@@ -317,5 +317,10 @@ class AdminApp(FastAPI):
         )
 
 
-app = AdminApp(openapi_prefix="/admin",)
+app = AdminApp(
+    openapi_prefix="/admin",
+    debug=False,
+    title="FastAPI-Admin",
+    description="FastAPI Admin Dashboard based on FastAPI and Tortoise ORM.",
+)
 app.add_exception_handler(HTTPException, exception_handler)

pyproject.toml

@@ -12,7 +12,7 @@ keywords = ["fastapi", "admin", "dashboard"]
 packages = [
     { include = "fastapi_admin" }
 ]
-include = ["CHANGELOG.rst", "LICENSE", "README.rst"]
+include = ["LICENSE", "README.rst"]
 
 [tool.poetry.dependencies]
 python = "^3.8"