diff --git a/README.md b/README.md index 2c59340..63d4533 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,6 @@ [![Documentation Status](https://readthedocs.org/projects/hobbit-core/badge/?version=latest)](https://hobbit-core.readthedocs.io/en/latest/?badge=latest) [![](https://img.shields.io/:license-mit-blue.svg?style=flat-square)](https://hobbit-core.mit-license.org) -A flask project generator. +A flask project generator. Based on Flask + SQLAlchemy + marshmallow + webargs. -[Readmedocs](https://hobbit-core.readthedocs.io/en/latest/) +[https://hobbit-core.readthedocs.io/en/latest/](https://hobbit-core.readthedocs.io/en/latest/) diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..ae07bc9 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,71 @@ +Hobbit-core's API Documentation +=============================== + +hobbit_core.hobbit +------------------ + +hobbit - A flask project generator. + +.. autofunction:: hobbit_core.hobbit.bootstrap.startproject + +hobbit_core.flask_hobbit +------------------------ + +A flask extension that take care of base utils. + +.. automodule:: hobbit_core.flask_hobbit + :members: + :undoc-members: + +db +^^ + +.. automodule:: hobbit_core.flask_hobbit.db + :members: + :undoc-members: + :exclude-members: SurrogatePK + + .. autoclass:: SurrogatePK + :members: __repr__ + +pagination +^^^^^^^^^^ + +.. automodule:: hobbit_core.flask_hobbit.pagination + :members: + :undoc-members: + +schemas +^^^^^^^ + +.. automodule:: hobbit_core.flask_hobbit.schemas + :members: + :undoc-members: + :exclude-members: PagedSchema + + .. autoclass:: PagedSchema + :members: + +utils +^^^^^ + +.. automodule:: hobbit_core.flask_hobbit.utils + :members: + :undoc-members: + + +response +^^^^^^^^ + +.. automodule:: hobbit_core.flask_hobbit.response + :members: + :undoc-members: + +err_handler +^^^^^^^^^^^ + +.. automodule:: hobbit_core.flask_hobbit.err_handler + :members: + + + diff --git a/docs/changelog.rst b/docs/changelog.rst index e5835ab..d114490 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,10 +1,12 @@ Change history ============== -1.2.0 (unreleased) +1.2.0 (2018-10-10) * Gitlab CI/CD support. -* Some useful cmds. +* Add secure_filename util. +* Enhance deploy, can deploy to multiple servers. +* Add --port option for startproject cmd. 1.1.0 (2018-09-29) ****************** diff --git a/docs/index.rst b/docs/index.rst index 34e2f2d..a9a316a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,10 +1,16 @@ -Welcome to hobbit-core's documentation! -======================================= +Hobbit-core's documentation +=========================== `changelog `_ // `github `_ // `pypi `_ // -`issues `_ +`issues `_ // +`API doc `_ // +`中文文档 `_ + +A flask project generator. Based on Flask + SQLAlchemy + marshmallow + webargs. + +A hobbit app contains RESTful API, unit test, gitlab-ci/cd、docker compose etc. **Why do we need this project?** Answer is `Convention over configuration. `_ @@ -18,7 +24,7 @@ Get it right now:: Create your flask project:: - hobbit --echo startproject -n demo -d . --example + hobbit --echo startproject -n demo -d . --example -p 5000 Run flask app:: @@ -46,6 +52,7 @@ Project Tree If not skip example(Please see --example/--no-example options), you can get project tree like this:: . + ├── Dockerfile ├── app │   ├── __init__.py │   ├── configs @@ -69,13 +76,21 @@ If not skip example(Please see --example/--no-example options), you can get proj │   └── views │   ├── __init__.py │   └── example.py + ├── deploy.sh + ├── docker-compose.yml ├── docs + ├── logs ├── requirements.txt └── tests ├── __init__.py ├── conftest.py └── test_example.py +Dockerfile +---------- + +Build image for run web server. For more information about dockerfile, please visit : `Dockerfile reference `_. + app --- @@ -86,86 +101,65 @@ configs In a hobbit app, we auto load config by FLASK_ENV. If FLASK_ENV=production, used ``configs/production.py`` file. -exts +core ^^^^ -`Why use exts.py to instance extension? `_ - +All complicated function, base class etc. -API -=== - -hobbit_core.hobbit ------------------- - -hobbit - A flask project generator. - -.. autofunction:: hobbit_core.hobbit.bootstrap.startproject +exts.py +^^^^^^^ -hobbit_core.flask_hobbit ------------------------- +To avoid circular imports in Flask and flask extention, exts.py used. `Why use exts.py to instance extension? `_ -A flask extension that take care of base utils. +models +^^^^^^ -.. automodule:: hobbit_core.flask_hobbit - :members: - :undoc-members: +Create your models here. -db -^^ +run.py +^^^^^^ -.. automodule:: hobbit_core.flask_hobbit.db - :members: - :undoc-members: - :exclude-members: SurrogatePK +schemas +^^^^^^^ - .. autoclass:: SurrogatePK - :members: __repr__ +Create your marshmallow scheams here. -pagination -^^^^^^^^^^ +utils +^^^^^ -.. automodule:: hobbit_core.flask_hobbit.pagination - :members: - :undoc-members: +All common utils here. -schemas -^^^^^^^ +views +^^^^^ -.. automodule:: hobbit_core.flask_hobbit.schemas - :members: - :undoc-members: - :exclude-members: PagedSchema +Create your views here. - .. autoclass:: PagedSchema - :members: +deploy.sh +--------- -utils -^^^^^ +A script for deploy. -.. automodule:: hobbit_core.flask_hobbit.utils - :members: - :undoc-members: +docker-compose.yml +^^^^^^^^^^^^^^^^^^ +Base docker compose file. Run app:: -response -^^^^^^^^ + docker-compose up -.. automodule:: hobbit_core.flask_hobbit.response - :members: - :undoc-members: +docs +---- -err_handler -^^^^^^^^^^^ +API doc etc. -.. automodule:: hobbit_core.flask_hobbit.err_handler - :members: +logs +---- +All logs for app, nginx etc. -Indices and tables -================== +tests +----- -* :ref:`search` +Create your tests here. Recommended use `pytest `_. Others @@ -175,3 +169,4 @@ Others :maxdepth: 2 changelog + api diff --git a/docs/index_cn.rst b/docs/index_cn.rst new file mode 100644 index 0000000..3eb7645 --- /dev/null +++ b/docs/index_cn.rst @@ -0,0 +1,174 @@ +Hobbit-core中文文档 +=================== + +`changelog `_ // +`github `_ // +`pypi `_ // +`issues `_ // +`API文档 `_ // +`EN version `_ + +基于 Flask + SQLAlchemy + marshmallow + webargs 的 flask 项目生成器。 + +包含 RESTful API、单元测试、gitlab-ci/cd、docker compose 一套解决方案。后续考虑更好的自动文档工具（目前有 apispec ）。 + +**为什么我开发了这个项目？** 可以参考这一设计范式： `Convention over configuration. `_ + + +简易教程 +======== + +快速安装:: + + pip install hobbit-core + +使用 ``hobbit`` 命令自动生成你的flask项目:: + + hobbit --echo startproject -n demo -d . --example -p 5000 + +参数 ``--example`` 会同时生成一个完整的api及其测试范例，使用以下项目启动server:: + + FLASK_APP=app/run.py flask run + +你可以在控制台看到类似如下信息:: + + * Serving Flask app "app/run.py" + * Environment: production + WARNING: Do not use the development server in a production environment. + Use a production WSGI server instead. + * Debug mode: off + * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) + +访问 ``http://127.0.0.1:5000/api/ping/`` + +有关 ``hobbit`` 的使用，直接查看帮助文档:: + + hobbit --help + + +项目结构 +======== + +如果使用 ``--example`` 参数（查看 ``--example/--no-example`` 相关帮助信息），你将会得到如下所示的项目结构:: + + . + ├── Dockerfile + ├── app + │   ├── __init__.py + │   ├── configs + │   │   ├── __init__.py + │   │   ├── default.py + │   │   ├── development.py + │   │   ├── production.py + │   │   └── testing.py + │   ├── core + │   │   └── __init__.py + │   ├── exts.py + │   ├── models + │   │   ├── __init__.py + │   │   └── example.py + │   ├── run.py + │   ├── schemas + │   │   ├── __init__.py + │   │   └── example.py + │   ├── utils + │   │   └── __init__.py + │   └── views + │   ├── __init__.py + │   └── example.py + ├── deploy.sh + ├── docker-compose.yml + ├── docs + ├── logs + ├── requirements.txt + └── tests + ├── __init__.py + ├── conftest.py + └── test_example.py + +Dockerfile +---------- + +使用docker来运行我们的web服务，基于同一个docker image运行测试，由此保证开发环境、测试环境、运行时环境一致。你可以在 `Dockerfile reference `_ 查看有关Dockerfile的语法。 + +app +--- + +app文件夹保存了所有业务层代码。基于 **约定优于配置** 范式，这个文件夹名字及所有其他文件夹名字 **禁止修改** 。 + +configs +^^^^^^^ + +基于flask设计，我们使用环境变量 ``FLASK_ENV`` 加载不同环境的配置文件。例如 ``FLASK_ENV=production`` ，会自动加载 ``configs/production.py`` 这个文件作为配置文件。 + +core +^^^^ + +core文件夹约定编写自定义的基础类库代码，复杂的业务层代码。 + +exts.py +^^^^^^^ + +flask项目很容易产生循环引用问题， ``exts.py`` 文件的目的就是避免产生这个问题。你可以看下这个解释： `Why use exts.py to instance extension? `_ + +models +^^^^^^ + +所有数据库模型定义在这里。 + +run.py +^^^^^^ + +web项目的入口。你将在这里注册路由、注册命令等等操作。 + +schemas +^^^^^^^ + +定义所有的 marshmallow scheams。我们使用marshmallow来序列化api输出，类似 ``django-rest-framework`` 的效果。 + +utils +^^^^^ + +定义所有的公用工具函数。 + +views +^^^^^ + +路由及简单业务逻辑。 + +deploy.sh +--------- + +一个简易的部署脚本。配合ci/cd系统一起工作。 + +docker-compose.yml +^^^^^^^^^^^^^^^^^^ + +基本的 docker compose 配置文件。考虑到单机部署需求，自动生成了一个简易的配置，启动项目:: + + docker-compose up + +docs +---- + +API 文档、model 设计文档、架构设计文档、需求文档等等项目相关的文档。 + +logs +---- + +运行时的log文件。 + +tests +----- + +所有的测试case. 推荐使用 `pytest `_ 测试。 + + +Others +====== + +.. toctree:: + :maxdepth: 2 + + changelog + api