[IMP] reference: reference lists styling

This commit updates the styling for reference/defition lists.

task-3729655

content/developer/reference/extract_api.rst

@@ -1,3 +1,11 @@
+.. |req| raw:: html
+
+    <em data-status="required">required</em>
+
+.. |opt| raw:: html
+
+    <em data-status="optional">optional</em>
+    
 ===========
 Extract API
 ===========
@@ -81,97 +89,92 @@ Request
 
 .. rst-class:: o-definition-list
 
-``jsonrpc`` (required)
+jsonrpc |req|
     see JSON-RPC2_
-``method`` (required)
+
+method |req|
     see JSON-RPC2_
-``id`` (required)
+
+id |req|
     see JSON-RPC2_
-``params``
+
+params
+    The object containing the actual request data.
+
     .. rst-class:: o-definition-list
 
-    ``account_token`` (required)
+    ``account_token`` |req|
         The token of the :doc:`IAP </applications/essentials/in_app_purchase>` account from which
         credits will be charged. Each successful call costs one credit.
-    ``version`` (required)
+
+    ``version`` |req|
         The version will determine the format of your requests and the format of the server response.
         You should use the :ref:`latest version available <extract_api/version>`.
-    ``documents`` (required)
+
+    ``documents`` |req|
         The document must be provided as a Base64 string in the ASCII encoding.
         The list should contain only one document. This field is a list only for legacy reasons.
         The supported formats are *pdf*, *png* and *jpg*.
-    ``dbuuid`` (optional)
+
+    ``dbuuid`` |opt|
         Unique identifier of the Odoo database.
-    ``webhook_url`` (optional)
+
+    ``webhook_url`` |opt|
         A webhook URL can be provided. An empty POST request will be sent to
         ``webhook_url/document_token`` when the result is ready.
-    ``user_infos`` (optional)
+
+    ``user_infos`` |opt|
         Information concerning the person sending the document to the extract service. It can be
         the client or the supplier (depending on the ``perspective``). This information is not
         required in order for the service to work but it greatly improves the quality of the result.
 
-        .. rst-class:: o-definition-list
+        .. raw:: html
 
-        ``user_company_vat`` (optional)
+            <details class="field-details">
+            <summary><strong>Show properties</strong></summary>
+
+        .. rst-class:: o-definition-list simple
+
+        ``user_company_vat`` |opt|
             VAT number of the user.
-        ``user_company_name`` (optional)
+
+        ``user_company_name`` |opt|
             Name of the user’s company.
-        ``user_company_country_code`` (optional)
+
+        ``user_company_country_code`` |opt|
             Country code of the user. Format:
             `ISO3166 alpha-2 <https://www.iban.com/country-codes>`_.
-        ``user_lang`` (optional)
-            The user language. Format: *language_code + _ + locale* (e.g. fr_FR, en_US).
-        ``user_email`` (optional)
-            The user email.
-        ``purchase_order_regex`` (optional)
-            Regex for purchase order identification. Will default to Odoo PO format if not provided.
-        ``perspective`` (optional)
-            .. rst-class:: o-definition-list
 
+        ``user_lang`` |opt|
+            The user language. Format: *language_code + _ + locale* (e.g. fr_FR, en_US).
+
+        ``user_email`` |opt|
+            The user email.
+
+        ``purchase_order_regex`` |opt|
+            Regex for purchase order identification. Will default to Odoo PO format if not provided.
+
+        ``perspective`` |opt|
             Can be ``client`` or ``supplier``. This field is useful for invoices only.
             ``client`` means that the user information provided are related to the client of the
-            invoice.
-            ``supplier`` means that it's related to the supplier.
-            If not provided, client will be used.
+            invoice. ``supplier`` means that it's related to the supplier.
+            If not provided, `client` will be used.
 
-.. code-block:: js
+        .. raw:: html
 
-    {
-        "jsonrpc": "2.0",
-        "method": "call",
-        "params": {
-            "account_token": string,
-            "version": int,
-            "documents": [string],
-            "dbuuid": string,
-            "webhook_url": string,
-            "user_infos": {
-                "user_company_vat": string,
-                "user_company_name": string,
-                "user_company_country_code": string,
-                "user_lang": string,
-                "user_email": string,
-                "purchase_order_regex": string,
-                "perspective": string,
-            },
-        },
-        "id": string,
-    }
+            </details>
 
-.. note::
-    The ``user_infos`` parameter is optional but it greatly improves the quality of the result,
-    especially for invoices. The more information you can provide, the better.
 
 Response
---------
+-------
 
 .. rst-class:: o-definition-list
 
-``jsonrpc``
+jsonrpc
     see JSON-RPC2_
-``id``
+id
     see JSON-RPC2_
-``result``
+result
     .. rst-class:: o-definition-list
 
     ``status``
@@ -226,20 +229,20 @@ Request
 
 .. rst-class:: o-definition-list
 
-``jsonrpc`` (required)
+jsonrpc |req|
     see JSON-RPC2_
-``method`` (required)
+method |req|
     see JSON-RPC2_
-``id`` (required)
+id |req|
     see JSON-RPC2_
-``params``
+params
     .. rst-class:: o-definition-list
 
-    ``version`` (required)
+    ``version`` |req|
         The version should match the version passed to the :ref:`/parse <extract_api/parse>` request.
-    ``document_token`` (required)
+    ``document_token`` |req|
         The ``document_token`` for which you want to get the current parsing status.
-    ``account_token`` (required)
+    ``account_token`` |req|
         The token of the |IAP| account that was used to submit the document.
 
 .. code-block:: js
@@ -264,11 +267,11 @@ are the name of the field and the value is the value of the field.
 
 .. rst-class:: o-definition-list
 
-``jsonrpc``
+jsonrpc
     see JSON-RPC2_
-``id``
+id
     see JSON-RPC2_
-``result``
+result
     .. rst-class:: o-definition-list
 
     ``status``
@@ -278,10 +281,8 @@ are the name of the field and the value is the value of the field.
     ``results``
         Only present if the request is successful.
 
-        .. rst-class:: o-definition-list
-
-        ``full_text_annotation``
-            Contains the unprocessed full result from the |OCR| for the document.
+    ``full_text_annotation``
+        Contains the unprocessed full result from the |OCR| for the document.
 
 ================================  =============================================================
 status                            status_msg
@@ -335,11 +336,11 @@ to be the best fit for the feature.
 
 .. rst-class:: o-definition-list
 
-``selected_value`` (optional)
+``selected_value`` |opt|
     The best candidate for this feature.
-``selected_values`` (optional)
+``selected_values`` |opt|
     The best candidates for this feature.
-``candidates`` (optional)
+``candidates`` |opt|
     List of all the candidates for this feature ordered by decreasing confidence score.
 
 .. code-block:: js
@@ -349,7 +350,7 @@ to be the best fit for the feature.
        "candidates": [candidate_12, candidate_3, candidate_4, ...]
    }
 
-candidate
+Candidate
 *********
 
 For each candidate we give its representation and position in the document. Candidates are sorted

extensions/odoo_theme/static/style.scss

@@ -870,7 +870,12 @@ abbr {
 //(ex: https://www.odoo.com/documentation/master/developer/reference/backend/orm.html#fields)
 
 .sig {
-    font-size: 0.875rem;
+    background: #F2F2F2;
+    padding: 8px;
+    border: 1px solid $o-gray-border;
+    border-bottom: none;
+    border-top-left-radius: 4px;
+    border-top-right-radius: 4px;
     .sig-prename {
         padding-left: .3rem;
 
@@ -896,14 +901,103 @@ abbr {
     }
 }
 
-dl.py, dl.js, dl.o-definition-list {
-    > dd {
-        margin-top: -0.075rem;
-        padding-left: $o-padding-s;
-        padding-top: $o-padding-xs;
-        border-left: 3px solid $o-literals-border;
+.py, .js {
+    p {
+        margin-bottom: 0;
+
+        &:has(+ div.alert) {
+            margin-bottom: 0;
+        }
     }
 
+    & > dd {
+        border: 1px solid $o-gray-border;
+        border-top: none;
+        border-bottom-left-radius: .25rem;
+        border-bottom-right-radius: .25rem;
+    }
+
+    dd {
+        .sig {
+            background: transparent;
+            border: none;
+            border-radius: 0;
+            padding: 8px 0;
+            font-weight: $font-weight-bold;
+        }
+
+        dd {
+            border: none;
+            border-radius: 0;
+        }
+
+        > dl.o-definition-list {
+            border: none;
+            border-radius: 0;
+            padding: 0;
+        }
+
+        > p:not(:last-child) {
+            padding: 1rem;
+            border-top: 1px solid $o-gray-border;
+            border-bottom: 1px solid $o-gray-border;
+
+            &:has(+ p) {
+                border-bottom: none;
+            }
+        }
+        
+        > p {
+            padding: .5rem 0;
+        }
+        
+        &.field-odd, &.field-even {
+            > p {
+                padding: 0;
+            }
+        }
+
+        > dl.attribute {
+            margin: 1rem;
+            font-size: .90rem;
+            dt {
+                border-left: 4px solid $o-gray-border;
+                padding: 0;
+            }
+
+            dd {
+                border: none;
+            }
+        }
+    }
+
+    dl > dt, dl > dd {
+        margin-top: .75rem;
+        
+        &:first-of-type {
+            margin-top: 0;
+        }
+    }
+
+    .alert {
+        margin: 1rem !important;
+        border-radius: .25rem;
+
+        + dl.field-list {
+            padding-top: 0;
+        }
+    }
+
+    .method {
+        margin: 1rem;
+    }
+}
+
+.py ul {
+    margin: 1rem 0;
+}
+
+dl.js, dl.o-definition-list {
     &.class em.property {
         font-size: $font-size-sm;
 
@@ -918,12 +1012,91 @@ dl.py, dl.js, dl.o-definition-list {
     }
 }
 
+.o-definition-list dd {
+    margin-bottom: 1rem;
+
+    &:has(.o-definition-list) {
+        margin-bottom: 0.5rem;
+    }
+
+    > p:last-child {
+        margin-bottom: 0;
+    }
+
+    .o-definition-list > dt:not(:first-of-type) {
+        border-top: 1px solid $o-gray-border;
+        padding-top: 1.25em;
+    }
+}
+
+dd > dl.o-definition-list {
+    border: 1px solid $o-gray-border;
+    border-radius: .25rem;
+    padding: 1rem;
+}
+
+.o-definition-list dt {
+    font-weight: bold;
+    font-size: 0.95rem;
+    margin-bottom: 0.2rem;
+    color: #2a2a2a;
+}
+
+.o-definition-list dt em {
+    font-style: normal;
+    font-weight: normal;
+    font-size: 0.8rem;
+    color: $text-muted;
+    margin-left: .5rem;
+}
+
+.field-details {
+    padding: 1rem;
+    border-left: 5px solid #eee;
+    background: #f9f9f9;
+    border-radius: .25rem;
+}
+
+.field-details summary {
+    font-size: 0.75rem;
+    text-transform: uppercase;
+    font-weight: bold;
+    cursor: pointer;
+}
+
+.field-details .o-definition-list.simple > dt {
+    margin-top: 1.5rem;
+
+    &:not(:first-of-type) {
+        padding-top: 0;
+        border-top: none;
+    }
+}
+
+em[data-status]::before {
+    content: "";
+    display: inline-block;
+    width: .5em;
+    height: .5em;
+    border-radius: 50%;
+    margin-right: .5em;
+    vertical-align: middle;
+}
+
+em[data-status="required"]::before {
+    background-color: #e67e22;
+}
+
+em[data-status="optional"]::before {
+    background-color: #95a5a6;
+}
+
+
 // The field-lists are generated Parameters and Arguments
 // within the References (ex: https://www.odoo.com/documentation/master/developer/reference/backend/orm.html#odoo.fields.Field)
 dl.field-list {
-    padding: .5rem;
-    border: 1px solid $o-gray-border;
     @include font-size($font-size-sm);
+    padding: 1rem;
 
     @include media-breakpoint-down(lg) {
         display: block;