[ADD] extensions: new autofield directive, [REF] i18n/localization.rst

[william-andre]

No description provided.

[robodoo]

Pull request status dashboard.

[qdp-odoo]

just a minor cosmetic proposal/question. The rest is fine by me and can be improved latter on.

[qdp-odoo]

@odoo/doc-review let us know your opinion on the changes proposed in 8753a51

edit: changed history
14d4676
915e122
271252e
86f7266

[oco-odoo]

Twice's the charm ! 🥳

[oco-odoo]

Funny that the example above doesn't respect that :p Should we even bother recommanding anything here ? It actually makes no difference from a technical point of view.

[william-andre]

It is annoying to have l10n_xx.l10nxx_chart_template. (quite repetitive) Would be easier if it was uniform.

[oco-odoo]

Why linking the doc about payable and receivable accounts here? To me, they have nothing to do with the creation of an l10n module/CoA.

[william-andre]

They help devs to understand the account types when they have to chose the right ones

[jco-odoo]

I had hopes it would explain those user types better, but it does not seem to.

[oco-odoo]

Hmmm, not convinced; to me it's giving a little too much details regarding what we are explaining here.

[william-andre]

I changed the link to the doc, maybe you'll find it more relevant

[oco-odoo]

It's missing account.tax.report.

We might also want to add account.tax.carryover.line to the drawing, if we really want something complete (not sure it's not too much here).

[william-andre]

Is it good like this?

[oco-odoo]

?

[william-andre]

?

[Feyensv]

I love the idea of an autofield documenter, but the rest of the "tech" changes do not bring much and break current compatibility & maintainability.

Somebody fetching only the documentation repository must be able to build the documentation (which is not the case with your changes).

Also, in all honesty, the current doc on "how to build a localization" is not a howto, but more a kind of "raw checklist" in its current state.
Unless you are already knowledgeable in the inner details of the accounting modules, I have the feeling that you are not really receiving much more help by reading the doc than by reading a localization module directly.

Did you ask newbies in your team to give their POV on this doc?
As developers, we easily believe everything is easy to understand in our own scope and to oversimplify the our explanations.

"Good news: you are not alone on this incomprehension. Bad news: you have to figure it out a bit." ---> What's the use of a documentation if it says "We leave you in your own mess" ?

[Feyensv]

Nope, this should be avoided. A sphinx extension should be independent of the local code.
Specify this in the config if really needed, but for me, this kind of reference is not very useful and easily broken.
The dev can easily grep and find the file generating the base data.

Furthermore, the static reference <https://github.com/odoo/odoo/blob/15.0/{reference} below doesn't consider the current version of the doc.

[william-andre]

The dev can easily grep and find the file generating the base data.

Let's delete the docs then? Devs can find everything from the source code.

[william-andre]

I put it in the config

[Feyensv]

As said before, a sphinx extension should be independent and not contain this kind of parameter list.

I'm thinking of a better way to support the custom Odoo Architecture, without this "hack" of a list of classes.
At worst, we drop those cross references. If the file hierarchy is clean, I believe it's still better than this custom list 🤔

[william-andre]

I changed the reference system using :ref: and .. autoodooclass:

[Feyensv]

Suggested change

	annotation[attrname] = dict
	field = self.object
	if field.type == 'many2one':
	annotation[attrname] = int
	elif field.type in ('one2many', 'many2many'):
	annotation[attrname] = List[odoo.fields.Command]
	elif field.type in ('selection', 'reference', 'char', 'text', 'html'):
	annotation[attrname] = str
	elif field.type == 'boolean':
	annotation[attrname] = bool
	elif field.type in ('float', 'monetary'):
	annotation[attrname] = float
	elif field.type == 'integer':
	annotation[attrname] = int
	elif field.type == 'date':
	annotation[attrname] = datetime.date
	elif field.type == 'datetime':
	annotation[attrname] = datetime.datetime
	annotation[attrname] = self.object.__class__

You can directly reference the documented Odoo Field class.

[william-andre]

What? No? That would return the fields class, not the type that we are expecting to input for that field.
When you do

sell.env['res.users'].write({'name': something})

You don't expect something to be an instance of fields.Char, but str

[Feyensv]

Yes, I expect something to be a char but we're documenting Odoo fields. I want the users to know what's behind a field, not only as value, but also as behavior, implied orm logic, choices of values, ...

If the display of a selection, reference, char, text & html fields is the same, then the autofield documenter doesn't do its job right...
Furthermore, we are in the dev doc, I expect the readers to know how to set the different types of fields (and if they don't, clicking on the class reference will redirect them to the needed documentation, even if some improvements are probably needed in the orm documentation).

[william-andre]

I completely disagree with that. I can add some better typing using the python module with the same name for fields if you want, but I am sure that I don't want fields.Char.
The end user, which might not be a real dev with a lot of experience, but just someone looking to do some RPC calls or to import/export data with the tools, doesn't care about the details of the field.

[Feyensv]

Please provide either an introduction in the different rst files, or in the source code for the classes.

Raw tech content without any text should be avoided as much as possible.
It would be way better to have an introduction on the concept/meaning behind the tech model.

[william-andre]

We will add some in the source code. But branches are not synchronized, and we need more time for that part.

[Feyensv]

Please do not use static references to github code, it won't be maintained and updated with the documentation versions.
The code is easy to find, this documentation targets developers, it's not needed.

[william-andre]

It doesn't target devs. And trust me, it is not that easy to find.

To quote you:

Did you ask newbies in your team to give their POV on this doc?
As developers, we easily believe everything is easy to understand in our own scope and to oversimplify the our explanations.

And yes. I asked newbies.

[Feyensv]

If it doesn't target devs, why is it in the developer/ section then ?

[william-andre]

It targets devs, but some are more "hardcore" than others. We often have PRs of ppl who can barely use a version control system for instance. Or devs du dimanche who want to help building a localization for their country, who know how to write xml but are afraid of digging in the code.

[Feyensv]

a little note on the perf diff?

[william-andre]

There is none (tested one or two years ago, after 13.0).
It is just for readability.

[Feyensv]

IIRC, csv records are created in batch, which isn't the case for xml records 🤔

[yelizariev]

Apparently, you lost my notes about those fields. The information from autofield is not enough

Current version

My version

[yelizariev]

#1301

[william-andre]

We will create a PR that adds help on the fields. It wouldn't be synchronized anyway.

[yelizariev]

#1334 (comment)

[yelizariev]

The same about suspense accounts. Don't make conspiracy about it. People should know the truth

Current version

My version

[william-andre]

We will create a PR that adds help on the fields. It wouldn't be synchronized anyway.

[yelizariev]

Why won't it be synchronized ? You plan to add help to master branch, right?
We either need such PR to odoo/odoo v15 or keep fields description in odoo/documentation v15 for a while (and replace it with generated docs in v16). I don't like the idea to hide the knowledge and enlighten new developers during special ceremony with accounting gurus only.

[william-andre]

It isn't synchronized because runbot team says it is too difficult to do to have a batch containing both the code and the doc

[yelizariev]

The example gives 7 fields only, while it's 21 fields

  <!-- Receivable/payable accounts. -->
  <field name="property_account_receivable_id" ref="..."/>
  <field name="property_account_payable_id" ref="..."/>

  <!-- Default Income/Expense Account for a Product Template. -->
  <field name="property_account_income_id" ref="..."/>
  <field name="property_account_expense_id" ref="..."/>

  <!-- Default Income/Expense Account for a Product Category. -->
  <field name="property_account_income_categ_id" ref="..."/>
  <field name="property_account_expense_categ_id" ref="..."/>

  <!-- Cash loss/gain accounts. They correspond profit_account_id / loss_account_id fields -->
  <field name="default_cash_difference_income_account_id" ref="..."/>
  <field name="default_cash_difference_expense_account_id" ref="..."/>

  <!-- Loss/gain exchange rate accounts. -->
  <field name="income_currency_exchange_account_id" ref="..."/>
  <field name="expense_currency_exchange_account_id" ref="..."/>

  <!-- Stock valuation accounts. -->
  <field name="property_stock_account_input_categ_id" ref="..."/>
  <field name="property_stock_account_output_categ_id" ref="..."/>
  <field name="property_stock_valuation_account_id" ref="..."/>

  <!-- Tax accounts to  balance current/advance tax payments. -->
  <!-- It's used in `env['account.generic.tax.report']._generate_tax_closing_entries` -->
  <field name="property_tax_payable_account_id" ref="..."/>
  <field name="property_tax_receivable_account_id" ref="..."/>
  <field name="property_advance_tax_payment_account_id" ref="..."/>


  <!-- Base Tax Received Account -->
  <!-- Corresponds to `account_cash_basis_base_account_id` field. -->
  <!-- It's used for taxes with `tax_exigibility` equal to `on_payment` -->
  <field name="property_cash_basis_base_account_id" ref="..."/>

  <!-- POS account. -->
  <field name="default_pos_receivable_account_id" ref="..."/>

  <!-- Payment accounts. -->
  <!--
       Suspense account is used to register an unreconiled bank entries created via bank statement.
       Once it's reconciled, the suspense account in `account.move` will be replaced with a proper account.
       Suspense account is an exceptional case when account is supposed to be replaced in the transaction.
       The new account depends on `account.payment` records. There are two cases
       1. `account.payment' exists before reconciliation aka Blue lines in reconciliation wizard
       2. `account.payment' is created on reconciliation aka regular Black lines in reconciliation wizard

       For case n.1 the new account is Outstanding Receipts/Payments account and the workflow is following:

       Initial transactions:
       * Invoice/bill: Payable/Receivable vs Expenses/Sales
       * Payment:             Outstanding vs Payable/Receivable
       After creating bank statement
       * Bank entry:                 Bank vs Suspense
       After reconciliation:
       * Bank entry:                 Bank vs Outstanding

       For case n.2 the new account is Payable/Receivable account from invoice/bill and the workflow is following:

       Initial transactions:
       * Invoice/bill: Payable/Receivable vs Expenses/Sales
       After creating bank statement
       * Bank entry:                 Bank vs Suspense
       After reconciliation:
       * Bank entry:                 Bank vs Payable/Receivable
  -->
  <field name="account_journal_suspense_account_id" ref="..."/>
  <!-- Outstanding Receipts Account -->
  <field name="account_journal_payment_debit_account_id" ref="..."/>
  <!-- Outstanding Payments Account -->
  <field name="account_journal_payment_credit_account_id" ref="..."/>

[yelizariev]

Current version

[william-andre]

Because you can't put them all at the same time, you first need to create the accounts, look below in the HowTo, where the steps are done in the right order

[yelizariev]

You probably misunderstand me. I'm talking about post-data file, not about the first file account_chart_template_data

[william-andre]

You have the reference for that, no need to put an example with every single account set. I'm not even sure it exists.

[jco-odoo]

There is a lot still missing. The transfer and suspense accounts would be good to explain in a more functional documentation as well. (I like the way it is explained by @yelizariev and you can not just add that easily in the code)

[jco-odoo]

I had hopes it would explain those user types better, but it does not seem to.

[jco-odoo]

is this still todo? (or can we refer to chart_template.py?)

[qdp-odoo]

@Feyensv all good for us, can you give a r+ ?

thanks

[AntoineVDV]

Waiting for confirmation that it will build fine on odoo.com before merging.

[AntoineVDV]

@robodoo r+

[william-andre]

@robodoo rebase-ff ? 🙏

[robodoo]

I'm sorry, @william-andre. You can't method=rebase-ff.

[jco-odoo]

@AntoineVDV

[robodoo]

Because this PR has multiple commits, I need to know how to merge it:

• merge to merge directly, using the PR as merge commit message
• rebase-merge to rebase and merge, using the PR as merge commit message
• rebase-ff to rebase and fast-forward

[AntoineVDV]

@robodoo rebase-ff

[robodoo]

Merge method set to rebase and fast-forward