doc/source/project.rst

   1 The OpenERP Web open-source project
   2 ===================================
   3
   4 Getting involved
   5 ----------------
   6
   7 Translations
   8 ++++++++++++
   9
  10 Bug reporting
  11 +++++++++++++
  12
  13 Source code repository
  14 ++++++++++++++++++++++
  15
  16 Merge proposals
  17 +++++++++++++++
  18
  19 Writing documentation
  20 +++++++++++++++++++++
  21
  22 The OpenERP Web project documentation uses Sphinx_ for the literate
  23 documentation (this document for instance), the development guides
  24 (for Python and Javascript alike) and the Python API documentation
  25 (via autodoc_).
  26
  27 For the Javascript API, documentation should be written using the
  28 `JsDoc Toolkit`_.
  29
  30 Guides and main documentation
  31 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  32
  33 The meat and most important part of all documentation. Should be
  34 written in plain english, using reStructuredText_ and taking advantage
  35 of `Sphinx's extensions`_, especially `cross-references`_.
  36
  37 Python API Documentation
  38 ~~~~~~~~~~~~~~~~~~~~~~~~
  39
  40 All public objects in Python code should have a docstring written in
  41 RST, using Sphinx's `Python domain`_ [#]_:
  42
  43 * Functions and methods documentation should be in their own
  44   docstring, using Sphinx's `info fields`_
  45
  46   For parameters types, built-in and stdlib types should be using the
  47   combined syntax::
  48
  49       :param dict foo: what the purpose of foo is
  50
  51   unless a more extensive explanation needs to be given (e.g. the
  52   specification that the input should be a list of 3-tuple needs to
  53   use ``:type:`` even though all types involved are built-ins). Any
  54   other type should be specified in full using the ``:type:`` field::
  55
  56       :param foo: what the purpose of foo is
  57       :type foo: some.addon.Class
  58
  59   Mentions of other methods (including within the same class), modules
  60   or types in descriptions (of anything, including parameters) should
  61   be cross-referenced.
  62
  63 * Classes should likewise be documented using their own docstring, and
  64   should include the documentation of their construction (``__init__``
  65   and ``__new__``), using the `info fields`_  as well.
  66
  67 * Attributes (class and instance) should be documented in their
  68   class's docstrin via the ``.. attribute::`` directiveg, following
  69   the class's own documentation.
  70
  71 * The relation between modules and module-level attributes is similar:
  72   modules should be documented in their own docstring, public module
  73   attributes should be documented in the module's docstring using the
  74   ``.. data::`` directive.
  75
  76 Javascript API documentation
  77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  78
  79 Javascript API documentation uses JsDoc_, a javascript documentation
  80 toolkit with a syntax similar to (and inspired by) JavaDoc's.
  81
  82 Due to limitations of JsDoc, the coding patterns in OpenERP Web and
  83 the Sphinx integration, there are a few peculiarities to be aware of
  84 when writing javascript API documentation:
  85
  86 * Namespaces and classes *must* be explicitly marked up even if they
  87   are not documented, or JsDoc will not understand what they are and
  88   will not generate documentation for their content.
  89
  90   As a result, the bare minimum for a namespace is::
  91
  92       /** @namespace */
  93       foo.bar.baz = {};
  94
  95   while for a class it is::
  96
  97       /** @class */
  98       foo.bar.baz.Qux = [...]
  99
 100 * Because the OpenERP Web project uses `John Resig's Class
 101   implementation`_ instead of direct prototypal inheritance [#]_,
 102   JsDoc fails to infer class scopes (and constructors or super
 103   classes, for that matter) and has to be told explicitly.
 104
 105   See :ref:`js-class-doc` for the complete rundown.
 106
 107 * Much like the JavaDoc, JsDoc does not include a full markup
 108   language. Instead, comments are simply marked up in HTML.
 109
 110   This has a number of inconvenients:
 111
 112   * Complex documentation comments become nigh-unreadable to read in
 113     text editors (as opposed to IDEs, which may handle rendering
 114     documentation comments on the fly)
 115
 116   * Though cross-references are supported by JsDoc (via ``@link`` and
 117     ``@see``), they only work within the JsDoc
 118
 119   * More general impossibility to integrate correctly with Sphinx, and
 120     e.g. reference JavaScript objects from a tutorial, or have all the
 121     documentation live at the same place.
 122
 123   As a result, JsDoc comments should be marked up using RST, not
 124   HTML. They may use Sphinx's cross-references as well.
 125
 126 .. _js-class-doc:
 127
 128 Documenting a Class
 129 *******************
 130
 131 The first task when documenting a class using JsDoc is to *mark* that
 132 class, so JsDoc knows it can be used to instantiate objects (and, more
 133 importantly as far as it's concerned, should be documented with
 134 methods and attributes and stuff).
 135
 136 This is generally done through the ``@class`` tag, but this tag has a
 137 significant limitation: it "believes" the constructor and the class
 138 are one and the same [#]_. This will work for constructor-less
 139 classes, but because OpenERP Web uses Resig's class the constructor is
 140 not the class itself but its ``init()`` method.
 141
 142 Because this pattern is common in modern javascript code bases, JsDoc
 143 supports it: it is possible to mark an arbitrary instance method as
 144 the *class specification* by using the ``@constructs`` tag.
 145
 146 .. warning:: ``@constructs`` is a class specification in and of
 147     itself, it *completely replaces* the class documentation.
 148
 149     Using both a class documentation (even without ``@class`` itself)
 150     and a constructor documentation is an *error* in JsDoc and will
 151     result in incorrect behavior and broken documentation.
 152
 153 The second issue is that Resig's class uses an object literal to
 154 specify instance methods, and because JsDoc does not know anything
 155 about Resig's class, it does not know about the role of the object
 156 literal.
 157
 158 As with constructors, though, JsDoc provides a pluggable way to tell
 159 it about methods: the ``@lends`` tag. It specifies that the object
 160 literal "lends" its properties to the class being built.
 161
 162 ``@lends`` must be specified right before the opening brace of the
 163 object literal (between the opening paren of the ``#extend`` call and
 164 the brace), and takes the full qualified name of the class being
 165 created as a parameter, followed by the character ``#`` or by
 166 ``.prototype``. This latter part tells JsDoc these are instance
 167 methods, not class (static) methods..
 168
 169 Finally, specifying a class's superclass is done through the
 170 ``@extends`` tag, which takes a fully qualified class name as a
 171 parameter.
 172
 173 Here are a class without a constructor, and a class with one, so that
 174 everything is clear (these are straight from the OpenERP Web source,
 175 with the descriptions and irrelevant atttributes stripped):
 176
 177 .. code-block:: javascript
 178
 179     /**
 180      * <Insert description here, not below>
 181      *
 182      * @class
 183      * @extends openerp.base.search.Field
 184      */
 185     openerp.base.search.CharField = openerp.base.search.Field.extend(
 186         /** @lends openerp.base.search.CharField# */ {
 187             // methods here
 188     });
 189
 190 .. code-block:: javascript
 191
 192
 193     openerp.base.search.Widget = openerp.base.Controller.extend(
 194         /** @lends openerp.base.search.Widget# */{
 195         /**
 196          * <Insert description here, not below>
 197          *
 198          * @constructs
 199          * @extends openerp.base.Controller
 200          *
 201          * @param view the ancestor view of this widget
 202          */
 203         init: function (view) {
 204             // construction of the instance
 205         },
 206         // bunch of other methods
 207     });
 208
 209 OpenERP Web over time
 210 ---------------------
 211
 212 Release process
 213 +++++++++++++++
 214
 215 OpenSUSE packaging: http://blog.lowkster.com/2011/04/packaging-python-packages-in-opensuse.html
 216
 217 Roadmap
 218 +++++++
 219
 220 Release notes
 221 +++++++++++++
 222
 223 .. [#] because Python is the default domain, the ``py:`` markup prefix
 224        is optional and should be left out.
 225
 226 .. [#] Resig's Class still uses prototypes under the hood, it doesn't
 227        reimplement its own object system although it does add several
 228        helpers such as the ``_super()`` instance method.
 229
 230 .. [#] Which is the case in normal Javascript semantics. Likewise, the
 231        ``.prototype`` / ``#`` pattern we will see later on is due to
 232        JsDoc defaulting to the only behavior it can rely on: "normal"
 233        Javascript prototype-based type creation.
 234
 235 .. _reStructuredText:
 236     http://docutils.sourceforge.net/rst.html
 237 .. _Sphinx:
 238     http://sphinx.pocoo.org/index.html
 239 .. _Sphinx's extensions:
 240     http://sphinx.pocoo.org/markup/index.html
 241 .. _Python domain:
 242     http://sphinx.pocoo.org/domains.html#the-python-domain
 243 .. _info fields:
 244     http://sphinx.pocoo.org/domains.html#info-field-lists
 245 .. _autodoc:
 246     http://sphinx.pocoo.org/ext/autodoc.html
 247         ?highlight=autodoc#sphinx.ext.autodoc
 248 .. _cross-references:
 249     http://sphinx.pocoo.org/markup/inline.html#xref-syntax
 250 .. _JsDoc:
 251 .. _JsDoc Toolkit:
 252     http://code.google.com/p/jsdoc-toolkit/
 253 .. _John Resig's Class implementation:
 254     http://ejohn.org/blog/simple-javascript-inheritance/