From ceed96401b02b9927687cfab81173125bde52c01 Mon Sep 17 00:00:00 2001 From: Roberto Rosario Date: Fri, 11 Sep 2015 22:51:39 -0400 Subject: [PATCH] Add app creation chapter to documentation. --- docs/index.rst | 1 + docs/topics/app_creation.rst | 143 +++++++++++++++++++++++++++++++++ docs/topics/development.rst | 149 ++++++----------------------------- 3 files changed, 170 insertions(+), 123 deletions(-) create mode 100644 docs/topics/app_creation.rst diff --git a/docs/index.rst b/docs/index.rst index 2eba239b7f..128a2227f0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,6 +30,7 @@ account. Release notes and upgrading Concepts Development + App creation Translations Contributors Licensing diff --git a/docs/topics/app_creation.rst b/docs/topics/app_creation.rst new file mode 100644 index 0000000000..288d56c87b --- /dev/null +++ b/docs/topics/app_creation.rst @@ -0,0 +1,143 @@ +============ +App creation +============ + +**Mayan EDMS** apps are essentially Django app with some extra code to register +navigation, permissions and other relationships. + + +App modules +=========== + +- __init__.py + + Should be empty if possible. No initialization code should be here, use the + ready() method of the MayanAppConfig class in the apps.py module. + +- admin.py + + Standard Django app module to define how models are to be presented in the + admin interface. + +- api_views.py + + REST API views go here. **Mayan EDMS** uses Django REST Framework API view + classes. + +- apps.py + + Contains the MayanAppConfig subclass as required by Django 1.7 and up. This + is a place to define the app name and translatable verbose name as well as + code to be execute when the modules of the app are ready. + +- classes.py + + Hold python classes to be used internally or externally. Any class defined by + the app that is not a model. + +- events.py + + Define event class instances that are later commited to a log by custom + code. + +- exceptions.py + + Custom exceptions defined by the app. + +- fields.py + + Place any custom form field classed you define here. + +- forms.py + + Standard Django app module that hold custom form classes. + +- handlers.py + + Contains the signal handlers, functions that will process a given signal + emited from this or other apps. Connect the handler functions to the + corresponding signal in the ready() method of the MayanAppConfig subclass in + apps.py + +- links.py + + Defines the links to be used by the app. Import only from the navigation app + and the local permissions.py file. + +- literals.py + + Stores magic numbers, module choices (if static), settings defaults, and + constants. Should contain all capital case variables. Must not import from + any other module. + +- managers.py + + Standard Django app module that hold custom model managers. These act as + model class method to performs actions in a series of model instances or + utilitarian actions on external models instances. + +- models.py + + Standard Django app module that defines ORM persistent data schema. + +- permissions.py + + Defines the permissions to be used to validate user access by links and views. + Imports only from the permissions app. Link or view conditions such as + testing for is_staff or is_super_user flag are defined in this same module. + +- runtime.py + + Use this module when you need the same instance of a class for the entire app. + This module acts as a shared memory space for the other modules of the app or + other apps. + +- serializers.py + + Hold Django REST Framework serializers used by the api_views.py module. + +- settings.py + + Define the config settings instances that the app will use. + +- signals.py + + Any custom defined signal goes here. + +- statistics.py + + Provides functions that will compute any sort of statistical information on + the app’s data. + +- tasks.py + + Code to be execute in the background or as an out-of-process action. + +- tests/ directory + + Hold test modules. There should be one test_*.py module for each aspect being + tested, examples: test_api.py, test_views.py, test_parsers.py, test_permissions.py + Any shared constant data used by the tests should be added to tests/literals.py + +- utils.py + + Holds utilitarian code that doesn't fit on any other app module or that is + used by several modules in the app. Anything used internally by the app that + is not a class or a literal (should be as little as possible) + +- widgets.py + + HTML widgets go here. This should be the only place with presentation + directives in the app (aside the templates). + + +Views +===== + +The module common.generics provides custom generic class based views to be used. +The basic views used to create, edit, view and delete objects in **Mayan EDMS** +are: SingleObjectCreateView, SingleObjectDetailView, SingleObjectEditView, +and SingleObjectListView + +These views handle aspects relating to view permissions, object permissions, +post action redirection and template context generation. diff --git a/docs/topics/development.rst b/docs/topics/development.rst index c5f8094443..8dac37e0bd 100644 --- a/docs/topics/development.rst +++ b/docs/topics/development.rst @@ -16,7 +16,8 @@ request on GitLab_. Make sure to add yourself to the :ref:`contributors` file. Project philosophies -------------------- -How to think about **Mayan EDMS** when doing changes or adding new features, why things are the way they are in **Mayan EDMS**. +How to think about **Mayan EDMS** when doing changes or adding new features, +why things are the way they are in **Mayan EDMS**. - Functionality must be as market/sector independent as possible, code for the 95% of use cases. - Each user must be able to configure and customize it to their needs after install. @@ -93,7 +94,9 @@ Example: ) from .models import Index, IndexInstanceNode, DocumentRenameCount -All local app module imports are in relative form, local app module name is to be referenced as little as possible, unless required by a specific feature, trick, restriction, ie: Runtime modification of the module's attributes. +All local app module imports are in relative form, local app module name is to +be referenced as little as possible, unless required by a specific feature, +trick, restriction, ie: Runtime modification of the module's attributes. Incorrect: @@ -113,12 +116,18 @@ Correct: Dependencies ~~~~~~~~~~~~ -**Mayan EDMS** apps follow a hierarchical model of dependency. Apps import from their parents or siblings, never from their children. Think plugins. A parent app must never assume anything about a possible existing child app. The documents app and the Document model are the basic entities they must never import anything else. The common and main apps are the base apps. +**Mayan EDMS** apps follow a hierarchical model of dependency. Apps import from +their parents or siblings, never from their children. Think plugins. A parent +app must never assume anything about a possible existing child app. The +documents app and the Document model are the basic entities they must never +import anything else. The common and main apps are the base apps. Variables ~~~~~~~~~ -Naming of variables should follow a Major to Minor convention, usually including the purpose of the variable as the first piece of the name, using underscores as spaces. camelCase is not used in **Mayan EDMS**. +Naming of variables should follow a Major to Minor convention, usually +including the purpose of the variable as the first piece of the name, using +underscores as spaces. camelCase is not used in **Mayan EDMS**. Examples: @@ -158,128 +167,20 @@ Quotation character used in **Mayan EDMS** for strings is the single quote. Doub General ~~~~~~~ - -Code should appear in their modules in alphabetic order or in their order of importance if it makes more sense for the specific application. -This makes visual scanning easier on modules with a large number of imports, views or classes. -Class methods that return a value should be prepended with a ``get_`` to differentiate from an object’s properties. -When a variable refers to a file it should be named as follows: +Code should appear in their modules in alphabetic order or in their order of +importance if it makes more sense for the specific application. This makes +visual scanning easier on modules with a large number of imports, views or +classes. Class methods that return a value should be prepended with a +``get_`` to differentiate from an object’s properties. When a variable refers +to a file it should be named as follows: - filename: The file’s name and extension only. - filepath: The entire path to the file including the filename. - path: A path to a directory. Flash messages should end with a period as applicable for the language. -Only exception is when the tail of the message contains an exceptions message as passed directly from the exception object. - -App anatomy -~~~~~~~~~~~ - -- __init__.py - - - Should be empty if possible. No initialization code should be here, use the ready() method of the AppConfig class in the apps.py module. - -- api.py - - - File to hold functions that are meant to be used by external apps. - - Interfaces meant to be used by other apps that are not models or classes. - -- apps.py - - - Contains the AppConfig subclass as required by Django 1.7 and up. - -- classes.py - - - Hold python classes to be used internally or externally. - - Any class defined by the app that is not a model. - -- diagnostics.py - - - Define functions that will return the state of the data of an app. - - Does not fixes the problems only finds them. - -- events.py - - - Define history type events. - -- exceptions.py - - - Exceptions defined by the app. - -- fields.py - - - Place any custom form field classed you define here. - -- handlers.py - - - Contains the signal handlers, functions that will process a given signal emited from this or other apps. - -- links.py - - - Defines the links to be used by the app. - - Import only from the navigation app and the local icons.py file. - -- literals.py - - - Stores magic numbers, module choices (if static), settings defaults, and constants. - - Should contain all capital case variables. - - Must not import from any other module. - -- maintenance.py - - - Hold functions that the user may run periodically to fix errors in the app’s data. - -- permissions.py - - - Defines the permissions to be used by links and views to validate access. - - Imports only from permissions app. - - Link or view conditions such as testing for staff or super admin status are defined in the same file. - -- runtime.py - - - Use this module when you need the same instance of a class for the entire app. This app is acts as a shared memory space for the modules of the apps or other apps. - -- settings.py - - - Define the config settings that the app will use here. - -- signals.py - - - Any custom defined signal goes here. - -- statistics.py - - - Provides functions that will computer any sort of statistical information on the app’s data. - -- tasks.py - - - Code to be execute as in the background or a as an process-of-process action. - -- utils.py - - - Hold utilitarian code that doesn't fit on any other app file or that is used by several files in the app. - - Anything used internally by the app that is not a class or a literal (should be as little as possible) - -- widgets.py - - - HTML widgets go here. This should be the only place with presentation directives in the app (aside the templates). - -Views behavior -~~~~~~~~~~~~~~ - -- Delete views: - - - Redirect to object list view if one object is deleted. - - Redirect to previous view if many are deleted. - - Previous view equals: - - - previous variable in POST or - - previous variable in GET or - - request.META.HTTP_REFERER or - - object list view or - - 'home' view - - fallback to ‘/’ - - if previous equal same view then previous should equal object list view or ‘/’ - +Only exception is when the tail of the message contains an exceptions message +as passed directly from the exception object. Source Control -------------- @@ -294,7 +195,7 @@ The project is publicly accessible, hosted and can be cloned from **GitLab** usi Git branch structure -------------------- -**Mayan EDMS** follows the model layout by Vincent Driessen in his `Successful Git Branching Model`_ blog post. Git-flow_ is a great tool for managing the repository in this way. +**Mayan EDMS** follows simplified model layout by Vincent Driessen in his `Successful Git Branching Model`_ blog post. Git-flow_ is a great tool for managing the repository in this way. ``develop`` The "next release" branch, likely unstable. @@ -308,7 +209,8 @@ Git branch structure Each release is tagged separately. -When submitting patches, please place your code in its own ``feature/`` branch prior to opening a Merge Request on GitLab_. +When submitting patches, please place your code in its own ``feature/`` branch +prior to opening a Merge Request on GitLab_. .. _Git: http://git-scm.org .. _`Successful Git Branching Model`: http://nvie.com/posts/a-successful-git-branching-model/ @@ -331,7 +233,8 @@ Steps to deploy a development version Setting up a development version using Vagrant ---------------------------------------------- -Make sure you have Vagrant and a provider properly installed as per https://docs.vagrantup.com/v2/installation/index.html +Make sure you have Vagrant and a provider properly installed as per +https://docs.vagrantup.com/v2/installation/index.html Start and provision a machine using: