<commit_before>The OpenERP Web open-source project
===================================

Getting involved
----------------

Translations
++++++++++++

Bug reporting
+++++++++++++

Source code repository
++++++++++++++++++++++

Merge proposals
+++++++++++++++

Writing documentation
+++++++++++++++++++++

The OpenERP Web project documentation uses Sphinx_ for the literate
documentation (this document for instance), the development guides
(for Python and Javascript alike) and the Python API documentation
(via autodoc_).

For the Javascript API, documentation should be written using the
`JsDoc Toolkit`_.

Guides and main documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The meat and most important part of all documentation. Should be
written in plain english, using reStructuredText_ and taking advantage
of `Sphinx's extensions`_, especially `cross-references`_.

Python API Documentation
~~~~~~~~~~~~~~~~~~~~~~~~

All public objects in Python code should have a docstring written in
RST, using Sphinx's `Python domain`_ [#]_:

* Functions and methods documentation should be in their own
  docstring, using Sphinx's `info fields`_

  For parameters types, built-in and stdlib types should be using the
  combined syntax::

      :param dict foo: what the purpose of foo is

  unless a more extensive explanation needs to be given (e.g. the
  specification that the input should be a list of 3-tuple needs to
  use ``:type:`` even though all types involved are built-ins). Any
  other type should be specified in full with a cross-reference using
  the ``:type:`` field::

      :param foo: what the purpose of foo is
      :type foo: :class:`some.addon.Class`

  Likewise, mentions of other methods (including within the same
  class), modules or types should be cross-referenced.

* Classes should likewise be documented using their own docstring, and
  should include the documentation of their construction (``__init__``<commit_msg>[IMP] Sphinx will automatically cross-reference return types it understands, for direct class references no need to manually cross-ref<commit_after>The OpenERP Web open-source project
===================================

Getting involved
----------------

Translations
++++++++++++

Bug reporting
+++++++++++++

Source code repository
++++++++++++++++++++++

Merge proposals
+++++++++++++++

Writing documentation
+++++++++++++++++++++

The OpenERP Web project documentation uses Sphinx_ for the literate
documentation (this document for instance), the development guides
(for Python and Javascript alike) and the Python API documentation
(via autodoc_).

For the Javascript API, documentation should be written using the
`JsDoc Toolkit`_.

Guides and main documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The meat and most important part of all documentation. Should be
written in plain english, using reStructuredText_ and taking advantage
of `Sphinx's extensions`_, especially `cross-references`_.

Python API Documentation
~~~~~~~~~~~~~~~~~~~~~~~~

All public objects in Python code should have a docstring written in
RST, using Sphinx's `Python domain`_ [#]_:

* Functions and methods documentation should be in their own
  docstring, using Sphinx's `info fields`_

  For parameters types, built-in and stdlib types should be using the
  combined syntax::

      :param dict foo: what the purpose of foo is

  unless a more extensive explanation needs to be given (e.g. the
  specification that the input should be a list of 3-tuple needs to
  use ``:type:`` even though all types involved are built-ins). Any
  other type should be specified in full using the ``:type:`` field::

      :param foo: what the purpose of foo is
      :type foo: some.addon.Class

  Mentions of other methods (including within the same class), modules
  or types in descriptions (of anything, including parameters) should
  be cross-referenced.

* Classes should likewise be documented using their own docstring, and
  should include the documentation of their construction (``__init__``
{'fraction_non_alphanumeric': 0.13882646691635456, 'fraction_numerical': 0.0004993757802746567, 'mean_word_length': 4.7310443490701, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4295409', 'n_tokens_mistral': 1027, 'n_tokens_neox': 960, 'n_words': 490}