diff --git a/docs/index.rst b/docs/index.rst index 59ca266..ff2e770 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,9 +31,7 @@ Contribute .. toctree:: :maxdepth: 3 - pages/contribute-backend.rst - pages/contribute-frontend.rst - pages/contribute-localization.rst + pages/contribute/index.rst .. include:: includes/include_contribute.rst .. include:: includes/include_license.rst diff --git a/docs/pages/contribute/architecture.rst b/docs/pages/contribute/architecture.rst new file mode 100644 index 0000000..3969a63 --- /dev/null +++ b/docs/pages/contribute/architecture.rst @@ -0,0 +1,77 @@ +Arcitecture +=========== + +Main page +--------- + +He takes all the resources of the settings to return them to the template +``home.jinja2``. It implemented in :func:`pyramid_sacrud.views.sa_home`. + +.. figure:: /_static/pencil/home_how_it_works.png + +List of rows +------------ + +He takes all rows of resource, paginate it and return to template ``list.jinja2``. +It implemented in :class:`pyramid_sacrud.views.CRUD.List`. For select action +used :mod:`sacrud` and :meth:`sacrud.action.CRUD.read`. + +.. figure:: /_static/pencil/read_how_it_works.png + +Delete row +---------- + +He delete selected row and redirect to list of rows. It implemented in +:class:`pyramid_sacrud.views.CRUD.Delete`. For delete action used :mod:`sacrud` +and :meth:`sacrud.action.CRUD.delete`. + +.. figure:: /_static/pencil/delete_how_it_works.png + +Form for CREATE/DELETE action +----------------------------- + +If you send GET request it return HTML form for your module. To generate form +it used :mod:`sacrud_deform`. `sacrud_deform` generate form with schema from +:mod:`ColanderAlchemy` and widgets from :mod:`deform`. The main task of +:mod:`sacrud_deform` is choose the right widgets from :mod:`deform` and make +select widget for relationships. It implemented in +:class:`pyramid_sacrud.views.CRUD.Add` and used template ``create.jinja2``. + +.. figure:: /_static/pencil/add_how_it_works.png + +POST request for CREATE/DELETE action +------------------------------------- + +If you send POST request it validate form and do create/update action from +:mod:`sacrud` respectively :meth:`sacrud.action.CRUD.create` and +:meth:`sacrud.action.CRUD.update`. It implemented in +:class:`pyramid_sacrud.views.CRUD.Add`. + +.. figure:: /_static/pencil/add_post_how_it_works.png + +Future generation +----------------- + +Everything is good, but it does not allow use tree structure of resources and +has hard depency from :mod:`SQLAlchemy`, :mod:`sacrud`, :mod:`sacrud_deform` +etc... This is not good, a new generation of :mod:`pyramid_sacrud` must +represent just interface for any backends, like: + +* ziggfrom_alchemy - handle SQLAlchemy resourse +* ziggfrom_peewee - handle PeeweeORM resourse +* ziggfrom_ponyorm - handle PonyORM resourse +* ziggfrom_djangoorm - handle Django ORM resourse +* ziggfrom_mongodb - handle MongoDB resourse +* and unniversal interface writing your own backends for example: + + * you can write filesystem backend which shown files in + :mod:`pyramid_sacrud` and provide to you CRUD operations. + * OS process backend shown process in :mod:`pyramid_sacrud` and allow to kill it + * and all you can come to mind. + +ziggform_* - it's abstract modules, this is what needs to be done. I like the +idea of `ziggurat_form `_ so I use such +names. + +.. figure:: /_static/pencil/new_architecture.png + diff --git a/docs/pages/contribute-backend.rst b/docs/pages/contribute/backend.rst similarity index 100% rename from docs/pages/contribute-backend.rst rename to docs/pages/contribute/backend.rst diff --git a/docs/pages/contribute-frontend.rst b/docs/pages/contribute/frontend.rst similarity index 100% rename from docs/pages/contribute-frontend.rst rename to docs/pages/contribute/frontend.rst diff --git a/docs/pages/contribute/index.rst b/docs/pages/contribute/index.rst new file mode 100644 index 0000000..618125d --- /dev/null +++ b/docs/pages/contribute/index.rst @@ -0,0 +1,10 @@ +Contribute +========== + +.. toctree:: + :maxdepth: 3 + + architecture.rst + backend.rst + frontend.rst + localization.rst diff --git a/docs/pages/contribute-localization.rst b/docs/pages/contribute/localization.rst similarity index 100% rename from docs/pages/contribute-localization.rst rename to docs/pages/contribute/localization.rst