# HG changeset patch # User Christophe de Vienne # Date 1420754772 -3600 # Node ID 68c13e0c0fc5391038d8f5b71f1c14c2378fc12d # Parent c67bcee932488ff02d8fc97305bee897cb09e60e [doc] Insert the dev docs in the toc Related to #4832808 diff -r c67bcee93248 -r 68c13e0c0fc5 doc/coding_standards_css.rst --- a/doc/coding_standards_css.rst Thu Jan 08 22:11:06 2015 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,33 +0,0 @@ -CSS Coding Standards --------------------- - -(Draft, to be continued) - -:Naming: camelCase - -Indentation rules -~~~~~~~~~~~~~~~~~ -- 2 espaces avant les propriétés - -- pas d'espace avant les ":", un espace après - -- 1 seul espace entre les différentes valeurs pour une même propriété - - -Documentation -~~~~~~~~~~~~~ -Please keep rules semantically linked grouped together, with a comment about -what they are for. - -Recommendation -~~~~~~~~~~~~~~ -- Try to use existing classes rather than introduce new ones - -- Keep things as simple as possible while in the framework - -- Think about later customization by application - -- Avoid introducing a new CSS file for a few lines of CSS, at least while the - framework doesn't include packing functionalities - - diff -r c67bcee93248 -r 68c13e0c0fc5 doc/coding_standards_js.rst --- a/doc/coding_standards_js.rst Thu Jan 08 22:11:06 2015 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,37 +0,0 @@ -Javascript Coding Standards ---------------------------- - -(Draft, to be continued) - -:Naming: camelCase, except for CONSTANTS - -Indentation rules -~~~~~~~~~~~~~~~~~ -- espace avant accolade ouvrante - -- retour à la ligne après accolade ouvrante (éventuellement pas - de retour à la ligne s'il y a tout sur la même ligne, mais ce n'est - pas le cas ici. - -- no tabs - - -Documentation -~~~~~~~~~~~~~ -XXX explain comment format for documentation generation - - -Coding -~~~~~~ -- Don't forget 'var' before variable definition, and semi-colon (';') after **each** statement. -- Check the firebug console for deprecation warnings - - -API usage -~~~~~~~~~ -- unless intended, use jQuery('container') rather than jqNode('container') - - -See also -~~~~~~~~ -http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml \ No newline at end of file diff -r c67bcee93248 -r 68c13e0c0fc5 doc/dev/coding_standards_css.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/dev/coding_standards_css.rst Thu Jan 08 23:06:12 2015 +0100 @@ -0,0 +1,33 @@ +CSS Coding Standards +-------------------- + +(Draft, to be continued) + +:Naming: camelCase + +Indentation rules +~~~~~~~~~~~~~~~~~ +- 2 espaces avant les propriétés + +- pas d'espace avant les ":", un espace après + +- 1 seul espace entre les différentes valeurs pour une même propriété + + +Documentation +~~~~~~~~~~~~~ +Please keep rules semantically linked grouped together, with a comment about +what they are for. + +Recommendation +~~~~~~~~~~~~~~ +- Try to use existing classes rather than introduce new ones + +- Keep things as simple as possible while in the framework + +- Think about later customization by application + +- Avoid introducing a new CSS file for a few lines of CSS, at least while the + framework doesn't include packing functionalities + + diff -r c67bcee93248 -r 68c13e0c0fc5 doc/dev/coding_standards_js.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/dev/coding_standards_js.rst Thu Jan 08 23:06:12 2015 +0100 @@ -0,0 +1,37 @@ +Javascript Coding Standards +--------------------------- + +(Draft, to be continued) + +:Naming: camelCase, except for CONSTANTS + +Indentation rules +~~~~~~~~~~~~~~~~~ +- espace avant accolade ouvrante + +- retour à la ligne après accolade ouvrante (éventuellement pas + de retour à la ligne s'il y a tout sur la même ligne, mais ce n'est + pas le cas ici. + +- no tabs + + +Documentation +~~~~~~~~~~~~~ +XXX explain comment format for documentation generation + + +Coding +~~~~~~ +- Don't forget 'var' before variable definition, and semi-colon (';') after **each** statement. +- Check the firebug console for deprecation warnings + + +API usage +~~~~~~~~~ +- unless intended, use jQuery('container') rather than jqNode('container') + + +See also +~~~~~~~~ +http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml \ No newline at end of file diff -r c67bcee93248 -r 68c13e0c0fc5 doc/dev/features_list.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/dev/features_list.rst Thu Jan 08 23:06:12 2015 +0100 @@ -0,0 +1,223 @@ +================= +CubicWeb features +================= + +This page tries to resume features found in the bare cubicweb framework, +how mature and documented they are. + +:code maturity (CM): + + - 0: experimental, not ready at all for production, may be killed + + - 1: draft / unsatisfying, api may change in a near future, much probably in long + term + + - 2: good enough, api sounds good but will probably evolve a bit with more + hindsight + + - 3: mature, backward incompatible changes unexpected (may still evolve though, + of course) + + +:documentation level (DL): + + - 0: no documentation + + - 1: poor documentation + + - 2: some valuable documentation but some parts keep uncovered + + - 3: good / complete documentation + + +Instance configuration and maintainance +======================================= + ++====================================================================+====+====+ +| FEATURE | CM | DL | ++====================================================================+====+====+ +| setup - installation | 2 | 3 | +| setup - environment variables | 3 | 2 | +| setup - running modes | 2 | 2 | +| setup - administration tasks | 2 | 2 | +| setup - configuration file | 2 | 1 | ++--------------------------------------------------------------------+----+----+ +| configuration - user / groups handling | 3 | 1 | +| configuration - site configuration | 3 | 1 | +| configuration - distributed configuration | 2 | 1 | ++--------------------------------------------------------------------+----+----+ +| multi-sources - capabilities | NA | 0 | +| multi-sources - configuration | 2 | 0 | +| multi-sources - ldap integration | 2 | 1 | ++--------------------------------------------------------------------+----+----+ +| usage - custom ReST markup | 2 | 0 | +| usage - personal preferences | 2 | 1 | ++--------------------------------------------------------------------+----+----+ + + +Core development +================ + ++====================================================================+====+====+ +| FEATURE | CM | DL | ++====================================================================+====+====+ +| base - concepts | NA | 3 | +| base - security model | NA | 2 | +| base - database initialization | 2 | 1 | ++--------------------------------------------------------------------+----+----+ +| rql - base | 2 | 2 | +| rql - write | 2 | 2 | +| rql - function | 2 | 0 | +| rql - outer joins | 2 | 1 | +| rql - aggregates | 2 | 1 | +| rql - subqueries | 2 | 0 | ++--------------------------------------------------------------------+----+----+ +| schema - base | 2 | 3 | +| schema - constraints | 3 | 2 | +| schema - security | 2 | 2 | +| schema - inheritance | 1 | 1 | +| schema - customization | 1 | 1 | +| schema - introspection | 2 | 1 | ++--------------------------------------------------------------------+----+----+ +| vregistry - appobject | 2 | 2 | +| vregistry - registration | 2 | 2 | +| vregistry - selection | 3 | 2 | +| vregistry - core selectors | 3 | 3 | +| vregistry - custom selectors | 2 | 1 | +| vregistry - debugging selection | 2 | 1 | ++--------------------------------------------------------------------+----+----+ +| entities - interfaces | 2 | ? | +| entities - customization (dc_,...) | 2 | ? | +| entities - app logic | 2 | 2 | +| entities - orm configuration | 2 | 1 | +| entities - pluggable mixins | 1 | 0 | +| entities - workflow | 3 | 2 | ++--------------------------------------------------------------------+----+----+ +| dbapi - connection | 3 | 1 | +| dbapi - data management | 1 | 1 | +| dbapi - result set | 3 | 1 | +| dbapi - transaction, undo | 2 | 0 | ++--------------------------------------------------------------------+----+----+ +| cube - layout | 2 | 3 | +| cube - new cube | 2 | 2 | ++--------------------------------------------------------------------+----+----+ +| migration - context | 2 | 1 | +| migration - commands | 2 | 2 | ++--------------------------------------------------------------------+----+----+ +| testlib - CubicWebTC | 2 | 1 | +| testlib - automatic tests | 2 | 2 | ++--------------------------------------------------------------------+----+----+ +| i18n - mark string | 3 | 2 | +| i18n - customize strings from other cubes / cubicweb | 3 | 1 | +| i18n - update catalog | 3 | 2 | ++--------------------------------------------------------------------+----+----+ +| more - reloading tips | NA | 0 | +| more - site_cubicweb | 2 | ? | +| more - adding options in configuration file | 3 | 0 | +| more - adding options in site configuration / preferences | 3 | ? | +| more - optimizing / profiling | 2 | 1 | +| more - c-c plugins | 3 | 0 | +| more - crypto services | 0 | 0 | +| more - massive import | 2 | 0 | +| more - mime type based conversion | 2 | 0 | +| more - CWCache | 1 | 0 | ++--------------------------------------------------------------------+----+----+ + + +Web UI development +================== + ++====================================================================+====+====+ +| FEATURE | CM | DL | ++====================================================================+====+====+ +| base - web request | 2 | 2 | +| base - exceptions | 2 | 0 | +| base - session, authentication | 1 | 0 | +| base - http caching | 2 | 1 | +| base - external resources | 2 | 2 | +| base - static files | 2 | ? | +| base - data sharing | 2 | 2 | +| base - graphical chart customization | 1 | 1 | ++--------------------------------------------------------------------+----+----+ +| publishing - cycle | 2 | 2 | +| publishing - error handling | 2 | 1 | +| publishing - transactions | NA | ? | ++--------------------------------------------------------------------+----+----+ +| controller - base | 2 | 2 | +| controller - view | 2 | 1 | +| controller - edit | 2 | 1 | +| controller - json | 2 | 1 | ++--------------------------------------------------------------------+----+----+ +| views - base | 2 | 2 | +| views - templates | 2 | 2 | +| views - boxes | 2 | 1 | +| views - components | 2 | 1 | +| views - primary | 2 | 1 | +| views - tabs | 2 | 1 | +| views - xml | 2 | 0 | +| views - text | 2 | 1 | +| views - table | 2 | 1 | +| views - plot | 2 | 0 | +| views - navigation | 2 | 0 | +| views - calendar, timeline | 2 | 0 | +| views - index | 2 | 2 | +| views - breadcrumbs | 2 | 1 | +| views - actions | 2 | 1 | +| views - debugging | 2 | 1 | ++--------------------------------------------------------------------+----+----+ +| form - base | 2 | 1 | +| form - fields | 2 | 1 | +| form - widgets | 2 | 1 | +| form - captcha | 2 | 0 | +| form - renderers | 2 | 0 | +| form - validation error handling | 2 | 0 | +| form - autoform | 2 | 2 | +| form - reledit | 2 | 0 | ++--------------------------------------------------------------------+----+----+ +| facets - base | 2 | ? | +| facets - configuration | 2 | 1 | +| facets - custom facets | 2 | 0 | ++--------------------------------------------------------------------+----+----+ +| css - base | 1 | 1 | +| css - customization | 1 | 1 | ++--------------------------------------------------------------------+----+----+ +| js - base | 1 | 1 | +| js - jquery | 1 | 1 | +| js - base functions | 1 | 0 | +| js - ajax | 1 | 0 | +| js - widgets | 1 | 1 | ++--------------------------------------------------------------------+----+----+ +| other - page template | 0 | 0 | +| other - inline doc (wdoc) | 2 | 0 | +| other - magic search | 2 | 0 | +| other - url mapping | 1 | 1 | +| other - apache style url rewrite | 1 | 1 | +| other - sparql | 1 | 0 | +| other - bookmarks | 2 | 1 | ++--------------------------------------------------------------------+----+----+ + + +Repository development +====================== + ++====================================================================+====+====+ +| FEATURE | CM | DL | ++====================================================================+====+====+ +| base - session | 2 | 2 | +| base - more security control | 2 | 0 | +| base - debugging | 2 | 0 | ++--------------------------------------------------------------------+----+----+ +| hooks - development | 2 | 2 | +| hooks - abstract hooks | 2 | 0 | +| hooks - core hooks | 2 | 0 | +| hooks - control | 2 | 0 | +| hooks - operation | 2 | 2 | ++--------------------------------------------------------------------+----+----+ +| notification - sending email | 2 | ? | +| notification - base views | 1 | ? | +| notification - supervisions | 1 | 0 | ++--------------------------------------------------------------------+----+----+ +| source - storages | 2 | 0 | +| source - authentication plugins | 2 | 0 | +| source - custom sources | 2 | 0 | ++--------------------------------------------------------------------+----+----+ diff -r c67bcee93248 -r 68c13e0c0fc5 doc/dev/refactoring-the-css-with-uiprops.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/dev/refactoring-the-css-with-uiprops.rst Thu Jan 08 23:06:12 2015 +0100 @@ -0,0 +1,42 @@ +========================================= +Refactoring the CSSs with UI properties +========================================= + +Overview +========= + +Managing styles progressively became difficult in CubicWeb. The +introduction of uiprops is an attempt to fix this problem. + +The goal is to make it possible to use variables in our CSSs. + +These variables are defined or computed in the uiprops.py python file +and inserted in the CSS using the Python string interpolation syntax. + +A quick example, put in ``uiprops.py``:: + + defaultBgColor = '#eee' + +and in your css:: + + body { background-color: %(defaultBgColor)s; } + + +The good practices are: + +- define a variable in uiprops to avoid repetitions in the CSS + (colors, borders, fonts, etc.) + +- define a variable in uiprops when you need to compute values + (compute a color palette, etc.) + +The algorithm implemented in CubicWeb is the following: + +- read uiprops file while walk up the chain of cube dependencies: if + cube myblog depends on cube comment, the variables defined in myblog + will have precedence over the ones in comment + +- replace the %(varname)s in all the CSSs of all the cubes + +Keep in mind that the browser will then interpret the CSSs and apply +the standard cascading mechanism. diff -r c67bcee93248 -r 68c13e0c0fc5 doc/features_list.rst --- a/doc/features_list.rst Thu Jan 08 22:11:06 2015 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,223 +0,0 @@ -================= -CubicWeb features -================= - -This page tries to resume features found in the bare cubicweb framework, -how mature and documented they are. - -:code maturity (CM): - - - 0: experimental, not ready at all for production, may be killed - - - 1: draft / unsatisfying, api may change in a near future, much probably in long - term - - - 2: good enough, api sounds good but will probably evolve a bit with more - hindsight - - - 3: mature, backward incompatible changes unexpected (may still evolve though, - of course) - - -:documentation level (DL): - - - 0: no documentation - - - 1: poor documentation - - - 2: some valuable documentation but some parts keep uncovered - - - 3: good / complete documentation - - -Instance configuration and maintainance -======================================= - -+====================================================================+====+====+ -| FEATURE | CM | DL | -+====================================================================+====+====+ -| setup - installation | 2 | 3 | -| setup - environment variables | 3 | 2 | -| setup - running modes | 2 | 2 | -| setup - administration tasks | 2 | 2 | -| setup - configuration file | 2 | 1 | -+--------------------------------------------------------------------+----+----+ -| configuration - user / groups handling | 3 | 1 | -| configuration - site configuration | 3 | 1 | -| configuration - distributed configuration | 2 | 1 | -+--------------------------------------------------------------------+----+----+ -| multi-sources - capabilities | NA | 0 | -| multi-sources - configuration | 2 | 0 | -| multi-sources - ldap integration | 2 | 1 | -+--------------------------------------------------------------------+----+----+ -| usage - custom ReST markup | 2 | 0 | -| usage - personal preferences | 2 | 1 | -+--------------------------------------------------------------------+----+----+ - - -Core development -================ - -+====================================================================+====+====+ -| FEATURE | CM | DL | -+====================================================================+====+====+ -| base - concepts | NA | 3 | -| base - security model | NA | 2 | -| base - database initialization | 2 | 1 | -+--------------------------------------------------------------------+----+----+ -| rql - base | 2 | 2 | -| rql - write | 2 | 2 | -| rql - function | 2 | 0 | -| rql - outer joins | 2 | 1 | -| rql - aggregates | 2 | 1 | -| rql - subqueries | 2 | 0 | -+--------------------------------------------------------------------+----+----+ -| schema - base | 2 | 3 | -| schema - constraints | 3 | 2 | -| schema - security | 2 | 2 | -| schema - inheritance | 1 | 1 | -| schema - customization | 1 | 1 | -| schema - introspection | 2 | 1 | -+--------------------------------------------------------------------+----+----+ -| vregistry - appobject | 2 | 2 | -| vregistry - registration | 2 | 2 | -| vregistry - selection | 3 | 2 | -| vregistry - core selectors | 3 | 3 | -| vregistry - custom selectors | 2 | 1 | -| vregistry - debugging selection | 2 | 1 | -+--------------------------------------------------------------------+----+----+ -| entities - interfaces | 2 | ? | -| entities - customization (dc_,...) | 2 | ? | -| entities - app logic | 2 | 2 | -| entities - orm configuration | 2 | 1 | -| entities - pluggable mixins | 1 | 0 | -| entities - workflow | 3 | 2 | -+--------------------------------------------------------------------+----+----+ -| dbapi - connection | 3 | 1 | -| dbapi - data management | 1 | 1 | -| dbapi - result set | 3 | 1 | -| dbapi - transaction, undo | 2 | 0 | -+--------------------------------------------------------------------+----+----+ -| cube - layout | 2 | 3 | -| cube - new cube | 2 | 2 | -+--------------------------------------------------------------------+----+----+ -| migration - context | 2 | 1 | -| migration - commands | 2 | 2 | -+--------------------------------------------------------------------+----+----+ -| testlib - CubicWebTC | 2 | 1 | -| testlib - automatic tests | 2 | 2 | -+--------------------------------------------------------------------+----+----+ -| i18n - mark string | 3 | 2 | -| i18n - customize strings from other cubes / cubicweb | 3 | 1 | -| i18n - update catalog | 3 | 2 | -+--------------------------------------------------------------------+----+----+ -| more - reloading tips | NA | 0 | -| more - site_cubicweb | 2 | ? | -| more - adding options in configuration file | 3 | 0 | -| more - adding options in site configuration / preferences | 3 | ? | -| more - optimizing / profiling | 2 | 1 | -| more - c-c plugins | 3 | 0 | -| more - crypto services | 0 | 0 | -| more - massive import | 2 | 0 | -| more - mime type based conversion | 2 | 0 | -| more - CWCache | 1 | 0 | -+--------------------------------------------------------------------+----+----+ - - -Web UI development -================== - -+====================================================================+====+====+ -| FEATURE | CM | DL | -+====================================================================+====+====+ -| base - web request | 2 | 2 | -| base - exceptions | 2 | 0 | -| base - session, authentication | 1 | 0 | -| base - http caching | 2 | 1 | -| base - external resources | 2 | 2 | -| base - static files | 2 | ? | -| base - data sharing | 2 | 2 | -| base - graphical chart customization | 1 | 1 | -+--------------------------------------------------------------------+----+----+ -| publishing - cycle | 2 | 2 | -| publishing - error handling | 2 | 1 | -| publishing - transactions | NA | ? | -+--------------------------------------------------------------------+----+----+ -| controller - base | 2 | 2 | -| controller - view | 2 | 1 | -| controller - edit | 2 | 1 | -| controller - json | 2 | 1 | -+--------------------------------------------------------------------+----+----+ -| views - base | 2 | 2 | -| views - templates | 2 | 2 | -| views - boxes | 2 | 1 | -| views - components | 2 | 1 | -| views - primary | 2 | 1 | -| views - tabs | 2 | 1 | -| views - xml | 2 | 0 | -| views - text | 2 | 1 | -| views - table | 2 | 1 | -| views - plot | 2 | 0 | -| views - navigation | 2 | 0 | -| views - calendar, timeline | 2 | 0 | -| views - index | 2 | 2 | -| views - breadcrumbs | 2 | 1 | -| views - actions | 2 | 1 | -| views - debugging | 2 | 1 | -+--------------------------------------------------------------------+----+----+ -| form - base | 2 | 1 | -| form - fields | 2 | 1 | -| form - widgets | 2 | 1 | -| form - captcha | 2 | 0 | -| form - renderers | 2 | 0 | -| form - validation error handling | 2 | 0 | -| form - autoform | 2 | 2 | -| form - reledit | 2 | 0 | -+--------------------------------------------------------------------+----+----+ -| facets - base | 2 | ? | -| facets - configuration | 2 | 1 | -| facets - custom facets | 2 | 0 | -+--------------------------------------------------------------------+----+----+ -| css - base | 1 | 1 | -| css - customization | 1 | 1 | -+--------------------------------------------------------------------+----+----+ -| js - base | 1 | 1 | -| js - jquery | 1 | 1 | -| js - base functions | 1 | 0 | -| js - ajax | 1 | 0 | -| js - widgets | 1 | 1 | -+--------------------------------------------------------------------+----+----+ -| other - page template | 0 | 0 | -| other - inline doc (wdoc) | 2 | 0 | -| other - magic search | 2 | 0 | -| other - url mapping | 1 | 1 | -| other - apache style url rewrite | 1 | 1 | -| other - sparql | 1 | 0 | -| other - bookmarks | 2 | 1 | -+--------------------------------------------------------------------+----+----+ - - -Repository development -====================== - -+====================================================================+====+====+ -| FEATURE | CM | DL | -+====================================================================+====+====+ -| base - session | 2 | 2 | -| base - more security control | 2 | 0 | -| base - debugging | 2 | 0 | -+--------------------------------------------------------------------+----+----+ -| hooks - development | 2 | 2 | -| hooks - abstract hooks | 2 | 0 | -| hooks - core hooks | 2 | 0 | -| hooks - control | 2 | 0 | -| hooks - operation | 2 | 2 | -+--------------------------------------------------------------------+----+----+ -| notification - sending email | 2 | ? | -| notification - base views | 1 | ? | -| notification - supervisions | 1 | 0 | -+--------------------------------------------------------------------+----+----+ -| source - storages | 2 | 0 | -| source - authentication plugins | 2 | 0 | -| source - custom sources | 2 | 0 | -+--------------------------------------------------------------------+----+----+ diff -r c67bcee93248 -r 68c13e0c0fc5 doc/index.rst --- a/doc/index.rst Thu Jan 08 22:11:06 2015 +0100 +++ b/doc/index.rst Thu Jan 08 23:06:12 2015 +0100 @@ -104,6 +104,15 @@ js_api/index +Developpers +~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + :glob: + + dev/* + Indexes ~~~~~~~ diff -r c67bcee93248 -r 68c13e0c0fc5 doc/refactoring-the-css-with-uiprops.rst --- a/doc/refactoring-the-css-with-uiprops.rst Thu Jan 08 22:11:06 2015 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,42 +0,0 @@ -========================================= -Refactoring the CSSs with UI properties -========================================= - -Overview -========= - -Managing styles progressively became difficult in CubicWeb. The -introduction of uiprops is an attempt to fix this problem. - -The goal is to make it possible to use variables in our CSSs. - -These variables are defined or computed in the uiprops.py python file -and inserted in the CSS using the Python string interpolation syntax. - -A quick example, put in ``uiprops.py``:: - - defaultBgColor = '#eee' - -and in your css:: - - body { background-color: %(defaultBgColor)s; } - - -The good practices are: - -- define a variable in uiprops to avoid repetitions in the CSS - (colors, borders, fonts, etc.) - -- define a variable in uiprops when you need to compute values - (compute a color palette, etc.) - -The algorithm implemented in CubicWeb is the following: - -- read uiprops file while walk up the chain of cube dependencies: if - cube myblog depends on cube comment, the variables defined in myblog - will have precedence over the ones in comment - -- replace the %(varname)s in all the CSSs of all the cubes - -Keep in mind that the browser will then interpret the CSSs and apply -the standard cascading mechanism.