finished api doc

Author: TTWShell

.gitignore

@@ -8,6 +8,10 @@ __pycache__/*
 .pytest_cache/*
 .tox/*
 
+docs/_build/*
+docs/_static/*
+docs/_templates/*
+
 hobbit_core.egg-info/*
 dist/*
 build/*

docs/conf.py

@@ -11,10 +11,12 @@
 # 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('.'))
+
+import os
+import sys
+
+ROOT_PATH = os.path.split(os.path.abspath('.'))[0]
+sys.path.insert(0, os.path.join(ROOT_PATH, 'hobbit_core'))
 
 
 # -- Project information -----------------------------------------------------
@@ -48,6 +50,7 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -83,13 +86,16 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+# https://pypi.org/project/Flask-Sphinx-Themes/
+html_theme = 'flask'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-#
-# html_theme_options = {}
+
+html_theme_options = {
+    'github_fork': 'TTWShell/hobbit-core',
+}
 
 # 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,
@@ -187,9 +193,11 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 
 # -- Options for todo extension ----------------------------------------------
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True
+todo_include_todos = True
+
+autodoc_member_order = 'bysource'

docs/index.rst

@@ -6,15 +6,59 @@
 Welcome to hobbit-core's documentation!
 =======================================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+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:
+
+flask_hobbit.db
+---------------
+
+.. automodule:: hobbit_core.flask_hobbit.db
+   :members:
+   :undoc-members:
+   :exclude-members: SurrogatePK
+
+   .. autoclass:: SurrogatePK
+       :members: __repr__
+
+flask_hobbit.pagination
+-----------------------
+
+.. automodule:: hobbit_core.flask_hobbit.pagination
+   :members:
+   :undoc-members:
+
+flask_hobbit.schemas
+--------------------
+
+.. automodule:: hobbit_core.flask_hobbit.schemas
+   :members:
+   :undoc-members:
+   :exclude-members: PagedSchema
+
+   .. autoclass:: PagedSchema
+       :members:
 
+flask_hobbit.response
+---------------------
 
+.. automodule:: hobbit_core.flask_hobbit.response
+   :members:
+   :undoc-members:
 
 Indices and tables
 ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`

hobbit_core/flask_hobbit/__init__.py

@@ -9,6 +9,8 @@
 
 
 class HobbitManager:
+    """Customizable utils management.
+    """
 
     def __init__(self, app=None, **kwargs):
         """
@@ -19,6 +21,9 @@ def __init__(self, app=None, **kwargs):
             self.init_app(app, **kwargs)
 
     def init_app(self, app, **kwargs):
+        """
+        app: The Flask application instance.
+        """
         if not isinstance(app, Flask):
             raise TypeError(
                 'flask_hobbit.HobbitManager.init_app(): '

hobbit_core/flask_hobbit/db.py

@@ -4,7 +4,16 @@
 
 
 class SurrogatePK:
-    """Base model."""
+    """A mixin that add ``id``、``created_at`` and ``updated_at`` columns
+    to any declarative-mapped class.
+
+    **id**: A surrogate integer 'primary key' column.
+
+    **created_at**: Auto save ``datetime.now()`` when row created.
+
+    **updated_at**: Auto save ``datetime.now()`` when row updated.
+    """
+
     __table_args__ = {'extend_existing': True}
 
     id = Column(Integer, primary_key=True)
@@ -15,15 +24,41 @@ class SurrogatePK:
         onupdate=func.now())
 
     def __repr__(self):
+        """You can set label property.
+
+        Returns:
+            str: ``<{classname}({pk}:{label!r})>``
+        """
         return '<{classname}({pk}:{label!r})>'.format(
             classname=type(self).__name__, pk=self.id, label=self.label or '')
 
 
 def reference_col(tablename, nullable=False, pk_name='id', **kwargs):
+    """Column that adds primary key foreign key reference.
+
+    Args:
+        tablename (str): Model.__table_name__.
+        nullable (bool): Default is False.
+        pk_name (str): Primary column's name.
+
+    Others:
+
+    See ``sqlalchemy.Column``
+
+    Examples::
+
+        role_id = reference_col('role')
+        role = relationship('Role', backref='users', cascade='all, delete')
+    """
+
     return Column(
         ForeignKey('{0}.{1}'.format(tablename, pk_name)),
         nullable=nullable, **kwargs)
 
 
 class EnumExt(enum.Enum):
+    """
+    TODO:
+        * extension.
+    """
     pass

hobbit_core/flask_hobbit/pagination.py

@@ -6,26 +6,59 @@
 
 
 class ParamsDict(dict):
-    def __init__(self, **kwargs):
-        super().__init__(**kwargs)
+    """Just available update func.
+
+    Example::
+
+        @use_kwargs(PageParams.update({...}))
+        def list_users(page, page_size, order_by):
+            pass
+
+    """
 
     def update(self, other=None):
+        """Update self by other Mapping and return self.
+        """
         ret = self.copy()
         if other is not None:
             for k, v in other.items() if isinstance(other, Mapping) else other:
                 ret[k] = v
         return ret
 
 
+#: Base params for list view func.
 PageParams = ParamsDict(
     page=fields.Int(missing=1, required=False),
     page_size=fields.Int(missing=10, required=False),
     order_by=DelimitedList(
         fields.String(missing='id'), required=False, missing=['id']),
 )
+"""Base params for list view func which contains ``page``、``page_size``、\
+   ``order_by`` params.
+
+    Example::
+
+        @use_kwargs(PageParams)
+        def list_users(page, page_size, order_by):
+            pass
+"""
 
 
 def pagination(obj, page, page_size, order_by='id', query_exp=None):
+    """A pagination for sqlalchemy query.
+
+    Args:
+        obj (db.Model): Model class like User.
+        page (int): Page index.
+        page_size (int): Row's count per page.
+        order_by (str, list): Example: 'id'、['-id', 'column_name'].
+        query_exp (flask_sqlalchemy.BaseQuery): Query like \
+            ``User.query.filter_by(id=1)``.
+
+    Returns:
+        class: Class that contains ``items``、``page``、``page_size`` and \
+            ``total`` fileds.
+    """
     if not isinstance(obj, model.DefaultMeta):
         raise Exception('first arg obj must be model.')
 

hobbit_core/flask_hobbit/response.py

@@ -12,6 +12,18 @@
 
 
 def gen_response(code, message='', detail=None):
+    """Func for generate response body.
+
+    Args:
+        code (string, int): Extension to interact with web pages. Default is \
+            http response ``status_code`` like 200、404.
+        message (string): For popup windows.
+        detail (object): For debug, detail server error msg.
+
+    Returns:
+        dict: A dict contains args.
+
+    """
     return {
         'code': str(code),
         'message': message or RESP_MSGS.get(code, '未知错误'),
@@ -20,6 +32,8 @@ def gen_response(code, message='', detail=None):
 
 
 class Result(Response):
+    """Base json response.
+    """
     status = 200
 
     def __init__(self, response=None, status=None, headers=None,
@@ -34,6 +48,8 @@ def __init__(self, response=None, status=None, headers=None,
 
 
 class SuccessResult(Result):
+    """Success response. Default status is 200, you can cover it by status arg.
+    """
     status = 200
 
     def __init__(self, code=None, message='', detail=None, status=None):
@@ -43,6 +59,8 @@ def __init__(self, code=None, message='', detail=None, status=None):
 
 
 class FailedResult(Result):
+    """Failed response. status always 400.
+    """
     status = 400
 
     def __init__(self, code=None, message='', detail=None):

hobbit_core/flask_hobbit/schemas.py

@@ -2,6 +2,30 @@
 
 
 class PagedSchema(Schema):
+    """Base schema for list api pagination.
+
+    Example::
+
+        from marshmallow import fields
+
+        from hobbit_core.flask_hobbit.schemas import PagedSchema
+
+        from . import models
+        from .exts import ma
+
+
+        class UserSchema(ma.ModelSchema):
+
+            class Meta:
+                model = models.User
+
+
+        class PagedUserSchema(PagedSchema):
+            items = fields.Nested('UserSchema', many=True)
+
+
+        paged_user_schemas = PagedUserSchema()
+    """
     total = fields.Int()
     page = fields.Int(missing=1, default=1)
     page_size = fields.Int(missing=10, default=10)

hobbit_core/hobbit/bootstrap.py

@@ -26,6 +26,39 @@ def cli(ctx, force):
 @click.pass_context
 def startproject(ctx, name, dist, template, force):
     """Create a new flask project, render from different template.
+
+    Examples::
+
+        hobbit --echo startproject -n demo -d /tmp/test
+
+    Proj tree::
+
+        .
+        ├── demo
+        │   ├── __init__.py
+        │   ├── config.py
+        │   ├── exts.py
+        │   ├── models
+        │   │   ├── __init__.py
+        │   │   └── example.py
+        │   ├── run.py
+        │   ├── schemas
+        │   │   ├── __init__.py
+        │   │   └── example.py
+        │   ├── utils.py
+        │   └── views
+        │       ├── __init__.py
+        │       └── example.py
+        ├── docs
+        ├── requirements.txt
+        └── tests
+            ├── __init__.py
+            ├── conftest.py
+            └── test_example.py
+
+    Other tips::
+
+        hobbit --help
     """
     dist = os.getcwd() if dist is None else dist
     ctx.obj['FORCE'] = force