I can understand your frustration, most of the time the best docs is the code itself. So for a user it can be difficult.
But… with having basic knowledge of python or none I’m sure you can read a test scenario, let me explain.
When we develop a module apart from the docs folder where we write what you can see on docs.tryton.org, we create some tests on the tests folder of the module. Inside that folder you can find some .rst files containing what it’s called scenarios.
Normally, a scenario is a workflow we want to test in our application. It’s a sequence of actions performed by different actors, reflecting a real-life use case of the software. A scenario can help you understand the behavior of the software and its intended use.
Even with minimal programming knowledge, this scenario is quite readable. It describes a series of actions and expected outcomes, which helps you understand the functionality of the module. You’ll see different scenarios for different workflows that the module is expected to handle. This can be a valuable resource for understanding what a piece of software is supposed to do.
For example, normally at the start of the scenario we first create all the meaningless things that we will need to work with:
Create customer::
>>> Party = Model.get('party.party')
>>> customer = Party(name='Customer')
>>> customer.sale_shipment_cost_method = 'shipment'
>>> customer.save()
Create account category::
>>> ProductCategory = Model.get('product.category')
>>> account_category = ProductCategory(name="Account Category")
>>> account_category.accounting = True
>>> account_category.account_revenue = revenue
>>> account_category.save()
Create product::
>>> ProductUom = Model.get('product.uom')
>>> ProductTemplate = Model.get('product.template')
>>> unit, = ProductUom.find([('name', '=', 'Unit')])
>>> template = ProductTemplate()
>>> template.name = 'Product'
>>> template.default_uom = unit
>>> template.type = 'goods'
>>> template.salable = True
>>> template.lead_time = dt.timedelta(0)
>>> template.list_price = Decimal('20')
>>> template.account_category = account_category
>>> template.save()
And latter we perform the actions:
Sale products with cost on shipment::
>>> Sale = Model.get('sale.sale')
>>> sale = Sale()
>>> sale.party = customer
>>> sale.carrier = carrier
>>> sale.payment_term = payment_term
>>> sale.invoice_method = 'shipment'
>>> sale.shipment_cost_method
'shipment'
>>> sale_line = sale.lines.new()
>>> sale_line.product = product
>>> sale_line.quantity = 5.0
>>> sale.click('quote')
>>> cost_line = sale.lines[-1]
>>> cost_line.product == carrier_product
True
>>> cost_line.quantity
1.0
>>> cost_line.amount
Decimal('3.00')
>>> sale.click('confirm')
>>> sale.click('process')
>>> sale.state
'processing'
>>> sale.untaxed_amount
Decimal('103.00')
You should notice:
- Every time a Model is using like Sale() means we are working with a new record, so we can define the properties
- When on the line there is no >>> or … means that is a result, so for example, this validates that the product is the correct we expect and the quantity, so True and 1.0 are responses from the system to our questions:
>>> cost_line.product == carrier_product
True
>>> cost_line.quantity
1.0
- We can make actions like a user would:
sale.click('confirm')
While it’s true that these tests are written to ensure the software works as expected, they also provide a sort of “living documentation” for the system. However, keep in mind that test scenarios alone may not give you a complete understanding of the module’s functionality, especially if it’s complex or has a lot of different features. They’re best used in conjunction with other forms of documentation.
You can check those scenarios for sale_shipment_cost on the tests folder of the repository.