[ADD] extensions: add a custom example admonition

closes odoo/documentation#1504

X-original-commit: 434bb66492
Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>

conf.py

@@ -116,7 +116,7 @@ extensions = [
     # Youtube and Vimeo videos integration (youtube, vimeo directives)
     'embedded_video',
 
-    'exercise_admonition',
+    'custom_admonitions',
 
     # Redirection generator
     'redirects',

content/applications/finance/accounting/fiscal_localizations/localizations/france.rst

@@ -149,10 +149,9 @@ This means that the account codes the trailing zeroes are right-trimmed, and tha
 between the account codes in the FEC file and the ones already existing in Odoo is performed only on
 the first six digits of the codes.
 
-.. admonition:: Example
+.. example::
-
+   The account code `65800000` in the file is matched against an existing `658000` account in Odoo,
-    The account code `65800000` in the file is matched against an existing `658000` account in
+   and that account is used instead of creating a new one.
-    Odoo, and that account is used instead of creating a new one.
 
 Reconcilable flag
 *****************
@@ -177,17 +176,17 @@ computed this way.
 
 The match is done with the left-most digits, starting by using all digits, then 3, then 2.
 
-.. admonition:: Example
+.. example::
 
-    +------------+------------+-----------------+---------------------+---------------------+
+   +------------+------------+-----------------+---------------------+---------------------+
-    | Name       | Code       | Full comparison | 3-digits comparison | 2-digits comparison |
+   | Name       | Code       | Full comparison | 3-digits comparison | 2-digits comparison |
-    +============+============+=================+=====================+=====================+
+   +============+============+=================+=====================+=====================+
-    | Template   | `400000`   | `400000`        | `400`               | `40`                |
+   | Template   | `400000`   | `400000`        | `400`               | `40`                |
-    +------------+------------+-----------------+---------------------+---------------------+
+   +------------+------------+-----------------+---------------------+---------------------+
-    | CompteNum  | `40100000` | `40100000`      | `401`               | `40`                |
+   | CompteNum  | `40100000` | `40100000`      | `401`               | `40`                |
-    +------------+------------+-----------------+---------------------+---------------------+
+   +------------+------------+-----------------+---------------------+---------------------+
-    | **Result** |            |                 |                     | Match **found**     |
+   | **Result** |            |                 |                     | Match **found**     |
-    +------------+------------+-----------------+---------------------+---------------------+
+   +------------+------------+-----------------+---------------------+---------------------+
 
 The type of the account is then flagged as *payable* and *reconcilable* as per the account template.
 
@@ -202,9 +201,8 @@ creating a new one.
 
 New journals have their name prefixed by the string ``FEC-``.
 
-.. admonition:: Example
+.. example::
-
+   `ACHATS` -> `FEC-ACHATS`
-    `ACHATS` -> `FEC-ACHATS`
 
 The journals are *not* archived, the user is entitled to handle them as he wishes.
 
@@ -233,24 +231,23 @@ moves and accounts:
     - A minimum of three moves is necessary for journal type identification.
     - A threshold of 70% of moves must correspond to a criteria for a journal type to be determined.
 
-.. admonition:: Example
+.. example::
+   Suppose we are analyzing the moves that share a certain `journal_id`.
 
-    Suppose we are analyzing the moves that share a certain `journal_id`
+   +------------------------------------------------------------+-------+------------+
+   | Moves                                                      | Count | Percentage |
+   +============================================================+=======+============+
+   | that have a sale account line and no purchase account line | 0     | 0          |
+   +------------------------------------------------------------+-------+------------+
+   | that have a purchase account line and no sale account line | 1     | 25%        |
+   +------------------------------------------------------------+-------+------------+
+   | that have a liquidity account line                         | 3     | **75%**    |
+   +------------------------------------------------------------+-------+------------+
+   | **Total**                                                  | 4     | 100%       |
+   +------------------------------------------------------------+-------+------------+
 
-    +------------------------------------------------------------+-------+------------+
+   The journal `type` would be `bank`, because the bank moves percentage (75%) exceeds the threshold
-    | Moves                                                      | Count | Percentage |
+   (70%).
-    +============================================================+=======+============+
-    | that have a sale account line and no purchase account line | 0     | 0          |
-    +------------------------------------------------------------+-------+------------+
-    | that have a purchase account line and no sale account line | 1     | 25%        |
-    +------------------------------------------------------------+-------+------------+
-    | that have a liquidity account line                         | 3     | **75%**    |
-    +------------------------------------------------------------+-------+------------+
-    | **Total**                                                  | 4     | 100%       |
-    +------------------------------------------------------------+-------+------------+
-
-    The journal `type` would be `bank`, because the bank moves percentage (75%)
-    exceeds the threshold (70%).
 
 Partners
 ********
@@ -299,9 +296,8 @@ One last attempt is made, grouping all lines from the same journal and date (`Jo
 `EcritureDate`). Should this grouping generate balanced moves (sum(credit) - sum(debit) = 0), then
 each different combination of journal and date creates a new move.
 
-.. admonition:: Example
+.. example::
-
+   `ACH` + `2021/05/01` --> new move on journal `ACH` with name `20210501`.
-    `ACH` + `2021/05/01` --> new move on journal `ACH` with name `20210501`.
 
 Should this attempt fail, the user is prompted an error message with all the move lines that are
 supposedly unbalanced.

content/applications/sales/subscriptions/reporting/subscription_reports.rst

@@ -36,19 +36,19 @@ concepts to the proper understanding of the following reports:
 
   - **Revenue Churn**: It corresponds to the monthly recurring revenue loss rate.
 
-  .. admonition::
+    .. example::
-     Let's imagine a 2$ increase in a subscription service.
+       Let's imagine a 2$ increase in a subscription service.
 
-     - We lost 3 customers out of the initial 20, which generates a **Logo Churn** of 15%.
+       - We lost 3 customers out of the initial 20, which generates a **Logo Churn** of 15%.
-     - | Therefore, the 56$ of MRR difference out of the initial 600$ causes a **Revenue Churn**
+       - | Therefore, the 56$ of MRR difference out of the initial 600$ causes a **Revenue Churn**
-       | of 9,33%.
+         | of 9,33%.
 
-     .. image:: media/difference-between-logo-churn-and-revenue-churn.png
+       .. image:: media/difference-between-logo-churn-and-revenue-churn.png
-        :align: center
+          :align: center
-        :alt: Difference between logo churn and revenue churn in Odoo Subscriptions
+          :alt: Difference between logo churn and revenue churn in Odoo Subscriptions
 
-     Reminder: even though they seem to evolve in the same direction most of the time, it might not
+       Reminder: even though they seem to evolve in the same direction most of the time, it might
-     be the case all the time.
+       not be the case all the time.
 
 - **Customer Lifetime Value (CLV)**: Indicates how much revenue can be expected for a customer
   during his/her entire contract. This approach emphasizes the importance of customer retention,

content/developer/reference/backend/mixins.rst

@@ -26,7 +26,7 @@ Integrating messaging features to your model is extremely easy. Simply inheritin
 the ``mail.thread`` model and adding the messaging fields (and their appropriate
 widgets) to your form view will get you up and running in no time.
 
-.. admonition:: Example
+.. example::
 
     Let's create a simplistic model representing a business trip. Since organizing
     this kind of trip usually involves a lot of people and a lot of discussion, let's
@@ -200,7 +200,7 @@ The ``mail`` module adds a powerful tracking system on fields, allowing you
 to log changes to specific fields in the record's chatter. To add tracking
 to a field, simple set the tracking attribute to True.
 
-.. admonition:: Example
+.. example::
 
     Let's track changes on the name and responsible of our business trips:
 
@@ -272,7 +272,7 @@ can override the ``_track_subtype()`` function:
     :returns: a subtype's full external id or False if no subtype is triggered
 
 
-.. admonition:: Example
+.. example::
 
     Let's add a ``state`` field on our example class and trigger a notification
     with a specific subtype when this field change values.
@@ -422,7 +422,7 @@ The urls in the actions list can be generated automatically by calling the
     :returns: link of the type selected for the record
     :rtype: str
 
-.. admonition:: Example
+.. example::
 
     Let's add a custom button to the Business Trip state change notification;
     this button will reset the state to Draft and will be only visible to a member
@@ -609,7 +609,7 @@ which means that while the alias is stored in another table, you have
 access to all these fields directly from your parent object. This allows
 you to make your alias easily configurable from the record's form view.
 
-.. admonition:: Example
+.. example::
 
     Let's add aliases on our business trip class to create expenses on the fly via
     e-mail.
@@ -738,7 +738,7 @@ and the specific widgets to display them (via the field ``activity_ids``) in the
 view and kanban view of your records (``mail_activity`` and ``kanban_activity``
 widgets, respectively).
 
-.. admonition:: Example
+.. example::
 
     Organizing a business trip is a tedious process and tracking needed activities
     like ordering plane tickets or a cab for the airport could be useful. To do so,

content/developer/reference/backend/orm.rst

@@ -174,7 +174,7 @@ into a compatible type:
 * :func:`~odoo.fields.Date.to_date` will convert to a :class:`datetime.date`
 * :func:`~odoo.fields.Datetime.to_datetime` will convert to a :class:`datetime.datetime`.
 
-.. admonition:: Example
+.. example::
 
     To parse date/datetimes coming from external sources::
 
@@ -860,7 +860,7 @@ Domain criteria can be combined using logical operators in *prefix* form:
         Individual criterion generally have a negative form (e.g. ``=`` ->
         ``!=``, ``<`` -> ``>=``) which is simpler than negating the positive.
 
-.. admonition:: Example
+.. example::
 
     To search for partners named *ABC*, from belgium or germany, whose language
     is not english::

content/developer/reference/backend/views.rst

@@ -1015,7 +1015,7 @@ take the following attributes:
     * ``plan``: If enabled and ``edit`` enabled, a "magnifying glass" button will be displayed
       on time slots to plan unassigned records into that time slot.
 
-    .. admonition:: Example
+    .. example::
 
         When you do not want to create records on the gantt view and the beginning and end
         dates are required on the model, the planning feature should be disabled

extensions/custom_admonitions/__init__.py

@@ -1,10 +1,18 @@
-""" Add a new "exercise" admonition directive. """
+""" Add new custom admonition directives. """
 
 from docutils import nodes
 from docutils.parsers.rst.directives import admonitions
 from sphinx.locale import admonitionlabels
 
 
+class example(nodes.Admonition, nodes.Element):
+    pass
+
+
+class Example(admonitions.BaseAdmonition):
+    node_class = example
+
+
 class exercise(nodes.Admonition, nodes.Element):
     pass
 
@@ -14,6 +22,11 @@ class Exercise(admonitions.BaseAdmonition):
 
 
 def setup(app):
+    app.add_directive('example', Example)
+    app.add_node(example, html=(
+        lambda self, node: self.visit_admonition(node, 'example'),
+        lambda self, node: self.depart_admonition(node),
+    ))
     app.add_directive('exercise', Exercise)
     app.add_node(exercise, html=(
         lambda self, node: self.visit_admonition(node, 'exercise'),
@@ -26,4 +39,5 @@ def setup(app):
     }
 
 
+admonitionlabels['example'] = 'Example'
 admonitionlabels['exercise'] = 'Exercise'

extensions/odoo_theme/static/scss/_variables.scss

@@ -217,6 +217,7 @@ $brand-danger  :                            #D9534F;
 
 $doc_paper_dark:                            $gray-lighter;
 $doc_paper:                                 #ffffff;
+$doc_example:                               #519161;
 $doc_exercise:                              #938E94;
 $doc_code-bg:                               #F8F8F8;
 $doc_lime:                                  #CDDC39;

extensions/odoo_theme/static/style.scss

@@ -938,13 +938,28 @@ header.o_main_header {
                 border-color: $danger;
 
                 > .alert-title, > h3 {
-                    color: darken($brand-danger,20%);
+                    color: darken($brand-danger, 20%);
+
                     &:before {
                         content: '#{$i-danger}';
                     }
                 }
             }
 
+            &.alert-example {
+                border-color: tint-color($doc_example, 30%);
+                background-color: tint-color($doc_example, 90%);
+                color: shade-color($doc_example, 35%);
+
+                > .alert-title, > h3 {
+                    color: shade-color($doc_example, 35%);
+                }
+
+                > .alert-title:before, > h3:before {
+                    content: '#{$i-knowledge}';
+                }
+            }
+
             &.alert-exercise {
                 border-color: tint-color($doc_exercise, 30%);
                 background-color: tint-color($doc_exercise, 90%);

extensions/odoo_theme/translator.py

@@ -34,6 +34,7 @@ ADMONITION_MAPPING = {
     'danger': 'alert-danger',
     'error': 'alert-danger',
 
+    'example': 'alert-example',
     'exercise': 'alert-exercise',
 }