[IMP] spreadsheet_oca : Improve documentation

spreadsheet_oca/README.rst

@@ -7,7 +7,7 @@ Spreadsheet Oca
    !! This file is generated by oca-gen-addon-readme !!
    !! changes will be overwritten.                   !!
    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-   !! source digest: sha256:e5b362410ca5c8eed5057aba019e80bb65406834896e2299d36cf6bc86a83560
+   !! source digest: sha256:4214e988c2bc92cac7718d1e1e21d292c7e2821e3151138232f3d8cef77b2c4b
    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 
 .. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
@@ -30,11 +30,55 @@ Spreadsheet Oca
 
 This module adds a functionality for adding and editing Spreadsheets using Odoo CE.
 
+It is an alternative to the proprietary module ``spreadsheet_edition`` of Odoo Enterprise Edition.
+
 **Table of contents**
 
 .. contents::
    :local:
 
+Usage
+=====
+
+**Create a new spreadsheet**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Go to 'Spreadsheet' menu
+* Click on 'Create'
+* Put a name, then click on the "Edit" button
+
+.. figure:: https://raw.githubusercontent.com/OCA/spreadsheet/16.0/spreadsheet_oca/static/description/spreadsheet_create.png
+
+* At this point you switch to spreadsheet editing mode.
+  The editor is named ``o-spreadsheet`` and looks like another common spreadsheet web editors.
+  (OnlyOffice, Ethercalc, Google Sheets (non-free)).
+
+.. figure:: https://raw.githubusercontent.com/OCA/spreadsheet/16.0/spreadsheet_oca/static/description/spreadsheet_edit.png
+
+* You can use common functions ``SUM()``, ``AVERAGE()``, etc. in the cells.
+  For a complete list of functions and their syntax,
+  Refer to the documentation https://github.com/odoo/o-spreadsheet/
+  or go to https://odoo.github.io/o-spreadsheet/ and click on "Insert > Function".
+
+.. figure:: https://raw.githubusercontent.com/OCA/spreadsheet/16.0/spreadsheet_oca/static/description/o-spreadsheet.png
+
+* Note: Business Odoo module can add "business functions".
+  This is currently the case for the accounting module, which adds the following features:
+
+    * ``ODOO.CREDIT(account_codes, date_range)``: Get the total credit for the specified account(s) and period.
+    * ``ODOO.DEBIT(account_codes, date_range)``: Get the total debit for the specified account(s) and period.
+    * ``ODOO.BALANCE(account_codes, date_range)``: Get the total balance for the specified account(s) and period.
+    * ``ODOO.FISCALYEAR.START(day)``: Returns the starting date of the fiscal year encompassing the provided date.
+    * ``ODOO.FISCALYEAR.END(day)``: Returns the ending date of the fiscal year encompassing the provided date.
+    * ``ODOO.ACCOUNT.GROUP(type)``: Returns the account ids of a given group where type should be a value of the ``account_type`` field of ``account.account`` model.
+      (``income``, ``asset_receivable``, etc.)
+
+Development
+===========
+
+If you want to develop custom business functions, you can add others, based on the file
+https://github.com/odoo/odoo/blob/16.0/addons/spreadsheet_account/static/src/accounting_functions.js
+
 Known issues / Roadmap
 ======================
 

spreadsheet_oca/__manifest__.py

@@ -17,6 +17,7 @@
         "data/spreadsheet_spreadsheet_import_mode.xml",
         "wizards/spreadsheet_spreadsheet_import.xml",
     ],
+    "demo": ["demo/spreadsheet_spreadsheet.xml"],
     "assets": {
         "web.assets_backend": [
             "spreadsheet_oca/static/src/spreadsheet/spreadsheet.scss",

spreadsheet_oca/demo/demo_spreadsheet.json

@@ -0,0 +1,54 @@
+{
+  "version": 12.5,
+  "sheets": [
+    {
+      "id": "Sheet1",
+      "name": "Demo Sheet 1",
+      "colNumber": 26,
+      "rowNumber": 100,
+      "rows": {},
+      "cols": {},
+      "merges": [],
+      "cells": {
+        "A1": {"style": 1, "content": "First Value", "border": 1},
+        "A2": {"format": 1, "content": "30.55", "border": 1},
+        "B1": {"style": 1, "content": "Second Value", "border": 1},
+        "B2": {"format": 1, "content": "50", "border": 1},
+        "C1": {"style": 1, "content": "Total", "border": 1},
+        "C2": {"format": 1, "content": "=sum(A2:B2)", "border": 1},
+        "A3": {"border": 2},
+        "B3": {"border": 2},
+        "C3": {"border": 2},
+        "D1": {"border": 3},
+        "D2": {"border": 3}
+      },
+      "conditionalFormats": [],
+      "figures": [],
+      "filterTables": [],
+      "areGridLinesVisible": true,
+      "isVisible": true
+    }
+  ],
+  "entities": {},
+  "styles": {"1": {"bold": true, "align": "center"}},
+  "formats": {"1": "[$$]#,##0.00"},
+  "borders": {
+    "1": {
+      "top": ["thin", "#000"],
+      "bottom": ["thin", "#000"],
+      "left": ["thin", "#000"],
+      "right": ["thin", "#000"]
+    },
+    "2": {"top": ["thin", "#000"]},
+    "3": {"left": ["thin", "#000"]}
+  },
+  "revisionId": "START_REVISION",
+  "uniqueFigureIds": true,
+  "odooVersion": 5,
+  "globalFilters": [],
+  "pivots": {},
+  "pivotNextId": 1,
+  "lists": {},
+  "listNextId": 1,
+  "chartOdooMenusReferences": {}
+}

spreadsheet_oca/demo/spreadsheet_spreadsheet.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<odoo>
+    <record id="demo_spreadsheet" model="spreadsheet.spreadsheet">
+        <field name="name">Demo spreadsheet</field>
+        <field
+            name="data"
+            type="base64"
+            file="spreadsheet_oca/demo/demo_spreadsheet.json"
+        />
+
+    </record>
+</odoo>

spreadsheet_oca/readme/DESCRIPTION.rst

@@ -1 +1,3 @@
 This module adds a functionality for adding and editing Spreadsheets using Odoo CE.
+
+It is an alternative to the proprietary module ``spreadsheet_edition`` of Odoo Enterprise Edition.

spreadsheet_oca/readme/DEVELOP.rst

@@ -0,0 +1,2 @@
+If you want to develop custom business functions, you can add others, based on the file
+https://github.com/odoo/odoo/blob/16.0/addons/spreadsheet_account/static/src/accounting_functions.js

spreadsheet_oca/readme/USAGE.rst

@@ -0,0 +1,32 @@
+**Create a new spreadsheet**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Go to 'Spreadsheet' menu
+* Click on 'Create'
+* Put a name, then click on the "Edit" button
+
+.. figure:: ../static/description/spreadsheet_create.png
+
+* At this point you switch to spreadsheet editing mode.
+  The editor is named ``o-spreadsheet`` and looks like another common spreadsheet web editors.
+  (OnlyOffice, Ethercalc, Google Sheets (non-free)).
+
+.. figure:: ../static/description/spreadsheet_edit.png
+
+* You can use common functions ``SUM()``, ``AVERAGE()``, etc. in the cells.
+  For a complete list of functions and their syntax,
+  Refer to the documentation https://github.com/odoo/o-spreadsheet/
+  or go to https://odoo.github.io/o-spreadsheet/ and click on "Insert > Function".
+
+.. figure:: ../static/description/o-spreadsheet.png
+
+* Note: Business Odoo module can add "business functions".
+  This is currently the case for the accounting module, which adds the following features:
+
+    * ``ODOO.CREDIT(account_codes, date_range)``: Get the total credit for the specified account(s) and period.
+    * ``ODOO.DEBIT(account_codes, date_range)``: Get the total debit for the specified account(s) and period.
+    * ``ODOO.BALANCE(account_codes, date_range)``: Get the total balance for the specified account(s) and period.
+    * ``ODOO.FISCALYEAR.START(day)``: Returns the starting date of the fiscal year encompassing the provided date.
+    * ``ODOO.FISCALYEAR.END(day)``: Returns the ending date of the fiscal year encompassing the provided date.
+    * ``ODOO.ACCOUNT.GROUP(type)``: Returns the account ids of a given group where type should be a value of the ``account_type`` field of ``account.account`` model.
+      (``income``, ``asset_receivable``, etc.)

spreadsheet_oca/static/description/index.html

@@ -367,58 +367,116 @@ <h1 class="title">Spreadsheet Oca</h1>
 !! This file is generated by oca-gen-addon-readme !!
 !! changes will be overwritten.                   !!
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-!! source digest: sha256:e5b362410ca5c8eed5057aba019e80bb65406834896e2299d36cf6bc86a83560
+!! source digest: sha256:4214e988c2bc92cac7718d1e1e21d292c7e2821e3151138232f3d8cef77b2c4b
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
 <p><a class="reference external image-reference" href="https://odoo-community.org/page/development-status"><img alt="Beta" src="https://img.shields.io/badge/maturity-Beta-yellow.png" /></a> <a class="reference external image-reference" href="http://www.gnu.org/licenses/agpl-3.0-standalone.html"><img alt="License: AGPL-3" src="https://img.shields.io/badge/licence-AGPL--3-blue.png" /></a> <a class="reference external image-reference" href="https://github.com/OCA/spreadsheet/tree/16.0/spreadsheet_oca"><img alt="OCA/spreadsheet" src="https://img.shields.io/badge/github-OCA%2Fspreadsheet-lightgray.png?logo=github" /></a> <a class="reference external image-reference" href="https://translation.odoo-community.org/projects/spreadsheet-16-0/spreadsheet-16-0-spreadsheet_oca"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external image-reference" href="https://runboat.odoo-community.org/builds?repo=OCA/spreadsheet&amp;target_branch=16.0"><img alt="Try me on Runboat" src="https://img.shields.io/badge/runboat-Try%20me-875A7B.png" /></a></p>
 <p>This module adds a functionality for adding and editing Spreadsheets using Odoo CE.</p>
+<p>It is an alternative to the proprietary module <tt class="docutils literal">spreadsheet_edition</tt> of Odoo Enterprise Edition.</p>
 <p><strong>Table of contents</strong></p>
 <div class="contents local topic" id="contents">
 <ul class="simple">
-<li><a class="reference internal" href="#known-issues-roadmap" id="toc-entry-1">Known issues / Roadmap</a><ul>
-<li><a class="reference internal" href="#adding-new-lines-on-pivot-tables" id="toc-entry-2">Adding new lines on pivot tables</a></li>
+<li><a class="reference internal" href="#usage" id="toc-entry-1">Usage</a><ul>
+<li><a class="reference internal" href="#create-a-new-spreadsheet" id="toc-entry-2"><strong>Create a new spreadsheet</strong></a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#bug-tracker" id="toc-entry-3">Bug Tracker</a></li>
-<li><a class="reference internal" href="#credits" id="toc-entry-4">Credits</a><ul>
-<li><a class="reference internal" href="#authors" id="toc-entry-5">Authors</a></li>
-<li><a class="reference internal" href="#contributors" id="toc-entry-6">Contributors</a></li>
-<li><a class="reference internal" href="#maintainers" id="toc-entry-7">Maintainers</a></li>
+<li><a class="reference internal" href="#development" id="toc-entry-3">Development</a></li>
+<li><a class="reference internal" href="#known-issues-roadmap" id="toc-entry-4">Known issues / Roadmap</a><ul>
+<li><a class="reference internal" href="#adding-new-lines-on-pivot-tables" id="toc-entry-5">Adding new lines on pivot tables</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#bug-tracker" id="toc-entry-6">Bug Tracker</a></li>
+<li><a class="reference internal" href="#credits" id="toc-entry-7">Credits</a><ul>
+<li><a class="reference internal" href="#authors" id="toc-entry-8">Authors</a></li>
+<li><a class="reference internal" href="#contributors" id="toc-entry-9">Contributors</a></li>
+<li><a class="reference internal" href="#maintainers" id="toc-entry-10">Maintainers</a></li>
 </ul>
+</li>
+</ul>
+</div>
+<div class="section" id="usage">
+<h1><a class="toc-backref" href="#toc-entry-1">Usage</a></h1>
+<div class="section" id="create-a-new-spreadsheet">
+<h2><a class="toc-backref" href="#toc-entry-2"><strong>Create a new spreadsheet</strong></a></h2>
+<ul class="simple">
+<li>Go to ‘Spreadsheet’ menu</li>
+<li>Click on ‘Create’</li>
+<li>Put a name, then click on the “Edit” button</li>
+</ul>
+<div class="figure">
+<img alt="https://raw.githubusercontent.com/OCA/spreadsheet/16.0/spreadsheet_oca/static/description/spreadsheet_create.png" src="https://raw.githubusercontent.com/OCA/spreadsheet/16.0/spreadsheet_oca/static/description/spreadsheet_create.png" />
+</div>
+<ul class="simple">
+<li>At this point you switch to spreadsheet editing mode.
+The editor is named <tt class="docutils literal"><span class="pre">o-spreadsheet</span></tt> and looks like another common spreadsheet web editors.
+(OnlyOffice, Ethercalc, Google Sheets (non-free)).</li>
+</ul>
+<div class="figure">
+<img alt="https://raw.githubusercontent.com/OCA/spreadsheet/16.0/spreadsheet_oca/static/description/spreadsheet_edit.png" src="https://raw.githubusercontent.com/OCA/spreadsheet/16.0/spreadsheet_oca/static/description/spreadsheet_edit.png" />
+</div>
+<ul class="simple">
+<li>You can use common functions <tt class="docutils literal">SUM()</tt>, <tt class="docutils literal">AVERAGE()</tt>, etc. in the cells.
+For a complete list of functions and their syntax,
+Refer to the documentation <a class="reference external" href="https://github.com/odoo/o-spreadsheet/">https://github.com/odoo/o-spreadsheet/</a>
+or go to <a class="reference external" href="https://odoo.github.io/o-spreadsheet/">https://odoo.github.io/o-spreadsheet/</a> and click on “Insert &gt; Function”.</li>
+</ul>
+<div class="figure">
+<img alt="https://raw.githubusercontent.com/OCA/spreadsheet/16.0/spreadsheet_oca/static/description/o-spreadsheet.png" src="https://raw.githubusercontent.com/OCA/spreadsheet/16.0/spreadsheet_oca/static/description/o-spreadsheet.png" />
+</div>
+<ul>
+<li><p class="first">Note: Business Odoo module can add “business functions”.
+This is currently the case for the accounting module, which adds the following features:</p>
+<blockquote>
+<ul class="simple">
+<li><tt class="docutils literal">ODOO.CREDIT(account_codes, date_range)</tt>: Get the total credit for the specified account(s) and period.</li>
+<li><tt class="docutils literal">ODOO.DEBIT(account_codes, date_range)</tt>: Get the total debit for the specified account(s) and period.</li>
+<li><tt class="docutils literal">ODOO.BALANCE(account_codes, date_range)</tt>: Get the total balance for the specified account(s) and period.</li>
+<li><tt class="docutils literal">ODOO.FISCALYEAR.START(day)</tt>: Returns the starting date of the fiscal year encompassing the provided date.</li>
+<li><tt class="docutils literal">ODOO.FISCALYEAR.END(day)</tt>: Returns the ending date of the fiscal year encompassing the provided date.</li>
+<li><tt class="docutils literal">ODOO.ACCOUNT.GROUP(type)</tt>: Returns the account ids of a given group where type should be a value of the <tt class="docutils literal">account_type</tt> field of <tt class="docutils literal">account.account</tt> model.
+(<tt class="docutils literal">income</tt>, <tt class="docutils literal">asset_receivable</tt>, etc.)</li>
+</ul>
+</blockquote>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="development">
+<h1><a class="toc-backref" href="#toc-entry-3">Development</a></h1>
+<p>If you want to develop custom business functions, you can add others, based on the file
+<a class="reference external" href="https://github.com/odoo/odoo/blob/16.0/addons/spreadsheet_account/static/src/accounting_functions.js">https://github.com/odoo/odoo/blob/16.0/addons/spreadsheet_account/static/src/accounting_functions.js</a></p>
 </div>
 <div class="section" id="known-issues-roadmap">
-<h1><a class="toc-backref" href="#toc-entry-1">Known issues / Roadmap</a></h1>
+<h1><a class="toc-backref" href="#toc-entry-4">Known issues / Roadmap</a></h1>
 <div class="section" id="adding-new-lines-on-pivot-tables">
-<h2><a class="toc-backref" href="#toc-entry-2">Adding new lines on pivot tables</a></h2>
+<h2><a class="toc-backref" href="#toc-entry-5">Adding new lines on pivot tables</a></h2>
 <p>When we add a pivot table, the number of rows is predefined according to the current data.</p>
 <p>In order to add new rows, we need to reinsert the pivot table.</p>
 </div>
 </div>
 <div class="section" id="bug-tracker">
-<h1><a class="toc-backref" href="#toc-entry-3">Bug Tracker</a></h1>
+<h1><a class="toc-backref" href="#toc-entry-6">Bug Tracker</a></h1>
 <p>Bugs are tracked on <a class="reference external" href="https://github.com/OCA/spreadsheet/issues">GitHub Issues</a>.
 In case of trouble, please check there if your issue has already been reported.
 If you spotted it first, help us to smash it by providing a detailed and welcomed
 <a class="reference external" href="https://github.com/OCA/spreadsheet/issues/new?body=module:%20spreadsheet_oca%0Aversion:%2016.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**">feedback</a>.</p>
 <p>Do not contact contributors directly about support or help with technical issues.</p>
 </div>
 <div class="section" id="credits">
-<h1><a class="toc-backref" href="#toc-entry-4">Credits</a></h1>
+<h1><a class="toc-backref" href="#toc-entry-7">Credits</a></h1>
 <div class="section" id="authors">
-<h2><a class="toc-backref" href="#toc-entry-5">Authors</a></h2>
+<h2><a class="toc-backref" href="#toc-entry-8">Authors</a></h2>
 <ul class="simple">
 <li>CreuBlanca</li>
 </ul>
 </div>
 <div class="section" id="contributors">
-<h2><a class="toc-backref" href="#toc-entry-6">Contributors</a></h2>
+<h2><a class="toc-backref" href="#toc-entry-9">Contributors</a></h2>
 <ul class="simple">
 <li>Enric Tobella</li>
 </ul>
 </div>
 <div class="section" id="maintainers">
-<h2><a class="toc-backref" href="#toc-entry-7">Maintainers</a></h2>
+<h2><a class="toc-backref" href="#toc-entry-10">Maintainers</a></h2>
 <p>This module is maintained by the OCA.</p>
 <a class="reference external image-reference" href="https://odoo-community.org"><img alt="Odoo Community Association" src="https://odoo-community.org/logo.png" /></a>
 <p>OCA, or the Odoo Community Association, is a nonprofit organization whose