From a2ee70de23a7257788d2ff8090c36825f3b4f80a Mon Sep 17 00:00:00 2001 From: Legolas Bloom Date: Wed, 10 Oct 2018 15:36:04 +0800 Subject: [PATCH 1/4] release ready for 1.2.0 --- README.md | 2 +- docs/changelog.rst | 6 ++++-- docs/index.rst | 4 ++-- 3 files changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2c59340..efc1cf0 100644 --- a/README.md +++ b/README.md @@ -6,4 +6,4 @@ A flask project generator. -[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/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..16f344f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -Welcome to hobbit-core's documentation! +Hobbit-core's documentation ======================================= `changelog `_ // @@ -18,7 +18,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:: From f28fea6c8f03acca5382f5e3942042cfcbcf906a Mon Sep 17 00:00:00 2001 From: Legolas Bloom Date: Wed, 10 Oct 2018 20:27:48 +0800 Subject: [PATCH 2/4] finished project tree doc --- docs/index.rst | 69 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 67 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 16f344f..a65ab78 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -46,6 +46,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 +70,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,10 +95,66 @@ 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. + +exts.py +^^^^^^^ + +To avoid circular imports in Flask and flask extention, exts.py used. `Why use exts.py to instance extension? `_ + +models +^^^^^^ + +Create your models here. + +run.py +^^^^^^ + +schemas +^^^^^^^ + +Create your marshmallow scheams here. + +utils +^^^^^ + +All common utils here. + +views +^^^^^ + +Create your views here. + +deploy.sh +--------- + +A script for deploy. + +docker-compose.yml +^^^^^^^^^^^^^^^^^^ + +Base docker compose file. Run app:: + + docker-compose up + +docs +---- + +API doc etc. + +logs +---- + +All logs for app, nginx etc. + + +tests +----- + +Create your tests here. Recommended use `pytest `_. API From 2fe08030fe14ac7dc801448e549472b64603c4ba Mon Sep 17 00:00:00 2001 From: Legolas Bloom Date: Wed, 10 Oct 2018 21:27:22 +0800 Subject: [PATCH 3/4] add cn doc --- docs/api.rst | 71 +++++++++++++++++++ docs/index.rst | 75 ++------------------ docs/index_cn.rst | 171 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 246 insertions(+), 71 deletions(-) create mode 100644 docs/api.rst create mode 100644 docs/index_cn.rst diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..40fdf5f --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,71 @@ +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/index.rst b/docs/index.rst index a65ab78..ba08d11 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,9 @@ Hobbit-core's documentation `changelog `_ // `github `_ // `pypi `_ // -`issues `_ +`issues `_ // +`API doc `_ // +`中文文档 `_ **Why do we need this project?** Answer is `Convention over configuration. `_ @@ -157,76 +159,6 @@ tests Create your tests here. Recommended use `pytest `_. -API -=== - -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: - - Indices and tables ================== @@ -240,3 +172,4 @@ Others :maxdepth: 2 changelog + api diff --git a/docs/index_cn.rst b/docs/index_cn.rst new file mode 100644 index 0000000..f2b8a05 --- /dev/null +++ b/docs/index_cn.rst @@ -0,0 +1,171 @@ +Hobbit-core's documentation +======================================= + +`changelog `_ // +`github `_ // +`pypi `_ // +`issues `_ // +`API文档 `_ // +`EN version `_ + +**为什么我开发了这个项目？** 可以参考这一设计范式： `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 From c9f5761b7832f40fc055fa693d71e91dd4a1ba2b Mon Sep 17 00:00:00 2001 From: Legolas Bloom Date: Thu, 11 Oct 2018 14:52:26 +0800 Subject: [PATCH 4/4] add introduction --- README.md | 2 +- docs/api.rst | 4 ++-- docs/index.rst | 13 +++++-------- docs/index_cn.rst | 9 ++++++--- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index efc1cf0..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. [https://hobbit-core.readthedocs.io/en/latest/](https://hobbit-core.readthedocs.io/en/latest/) diff --git a/docs/api.rst b/docs/api.rst index 40fdf5f..ae07bc9 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,5 +1,5 @@ -API Documentation -================= +Hobbit-core's API Documentation +=============================== hobbit_core.hobbit ------------------ diff --git a/docs/index.rst b/docs/index.rst index ba08d11..a9a316a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,5 +1,5 @@ Hobbit-core's documentation -======================================= +=========================== `changelog `_ // `github `_ // @@ -8,6 +8,10 @@ Hobbit-core's documentation `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. `_ @@ -152,19 +156,12 @@ logs All logs for app, nginx etc. - tests ----- Create your tests here. Recommended use `pytest `_. -Indices and tables -================== - -* :ref:`search` - - Others ====== diff --git a/docs/index_cn.rst b/docs/index_cn.rst index f2b8a05..3eb7645 100644 --- a/docs/index_cn.rst +++ b/docs/index_cn.rst @@ -1,5 +1,5 @@ -Hobbit-core's documentation -======================================= +Hobbit-core中文文档 +=================== `changelog `_ // `github `_ // @@ -8,6 +8,10 @@ Hobbit-core's documentation `API文档 `_ // `EN version `_ +基于 Flask + SQLAlchemy + marshmallow + webargs 的 flask 项目生成器。 + +包含 RESTful API、单元测试、gitlab-ci/cd、docker compose 一套解决方案。后续考虑更好的自动文档工具（目前有 apispec ）。 + **为什么我开发了这个项目？** 可以参考这一设计范式： `Convention over configuration. `_ @@ -154,7 +158,6 @@ logs 运行时的log文件。 - tests -----