[IMP] odoo_theme: general cleanup

A general reorganization of the code was needed for more clarity.
The different markup styles have been grouped together under a common
"chapter", comments have been rewritten and example pages have been
added for context.

Some levels have been removed Where there were too many for no reason.
By removing one level of styles (e.g.: `#wrap`) we avoid needing to
force overrides or adding `!important` to our code.
⌙ e.g.: before commit 9ef86cd93d8c6fc0fd96b437f629237e7a562c6e,
`.o_spoilers .accordion-body >:first-child` was being involuntarily
overridden.

task-3046383

X-original-commit: 620e3c33ef
Part-of: odoo/documentation#4110

extensions/odoo_theme/static/scss/_sphinx_basic.scss

@@ -588,15 +588,15 @@ ol.upperroman {
     list-style: upper-roman;
 }
 
-:not(li) > ol > li:first-child > :first-child,
+// :not(li) > ol > li:first-child > :first-child,
-:not(li) > ul > li:first-child > :first-child {
+// :not(li) > ul > li:first-child > :first-child {
-    margin-top: 0px;
+//     margin-top: 0px;
-}
+// }
 
-:not(li) > ol > li:last-child > :last-child,
+// :not(li) > ol > li:last-child > :last-child,
-:not(li) > ul > li:last-child > :last-child {
+// :not(li) > ul > li:last-child > :last-child {
-    margin-bottom: 0px;
+//     margin-bottom: 0px;
-}
+// }
 
 ol.simple ol p,
 ol.simple ul p,

extensions/odoo_theme/static/scss/_variables.scss

@@ -1,9 +1,3 @@
-$o-grid-breakpoint-xxl: 1400px;
-$o-grid-breakpoint-xxxl: 1680px;
-
-$o-container-max-width-xxl:1380px;
-$o-container-max-width-xxxl: 1560px;
-
 // Typography
 // ===============================================
 $o-font-family-serif:                         'Roboto Slab', Georgia, "Times New Roman", Times, serif;

extensions/odoo_theme/static/style.scss

@@ -20,6 +20,7 @@ body {
         text-underline-position: from-font;
 
         &.external:not(.image-reference):after {
+            //see https://www.odoo.com/documentation/master/contributing/documentation/rst_cheat_sheet.html#external-hyperlinks
             content: '#{$i-external-link}';
             margin: 0 $o-icon-margin;
             font-family: icomoon, sans-serif !important;
@@ -36,13 +37,6 @@ body {
         @include o-scroll-padding()
     }
 
-    abbr {
-        text-underline-offset: 2px;
-
-        &[title="Pull Request"] {
-            @include o-easter-egg();
-        }
-    }
 }
 
 .hidden {
@@ -51,11 +45,6 @@ body {
     visibility: hidden !important;
 }
 
-span.viewcode-link {
-    float: none;
-    margin-left: .3rem;
-}
-
 //------------------------------------------------------------------------------
 // Header with logo, searchbar and switchers
 //------------------------------------------------------------------------------
@@ -199,7 +188,7 @@ header {
 }
 
 //------------------------------------------------------------------------------
-// Left side nav toctree
+// Navigation - Left side-nav toctree
 //------------------------------------------------------------------------------
 
 .o_side_nav {
@@ -370,8 +359,9 @@ header {
         padding-left: 0;
     }
 }
+
 //------------------------------------------------------------------------------
-// On this page local toctree
+// Navigation - "On This Page" local toctree
 //------------------------------------------------------------------------------
 
 aside.o_page_toc {
@@ -425,7 +415,7 @@ header {
 }
 
 //------------------------------------------------------------------------------
-// Main page content
+// Layout
 //------------------------------------------------------------------------------
 
 #wrap {
@@ -439,97 +429,9 @@ header {
         grid-template-columns: minmax(0,$o-side-nav-width) minmax(0,auto) minmax(0,$o-on-page-width);
         margin-top: $o-headers-height;
     }
-
-    // Literals Styles (ex: https://www.odoo.com/documentation/master/developer/reference/backend/orm.html#fields)
-    .o_code, .sig [class^="sig-"] {
-        @include o-code;
 }
 
-    .o_code {
+main.container-fluid {
-        padding: 0 .3rem;
-
-        &.file {
-            padding-right: .4rem;
-            background-color: $blue-100;
-            font-family: $font-family-base;
-            font-weight: $o-font-weight-medium;
-            font-style: italic;
-            color: $blue-700;
-        }
-    }
-
-    .sig {
-        .sig-prename {
-            padding-left: .3rem;
-
-            &+ .sig-name {
-                padding-right: .3rem;
-            }
-        }
-
-        em.property + .sig-name {
-            padding-left: .3rem;
-        }
-
-        .sig-paren:last-of-type {
-            padding-right: .3rem;
-        }
-    }
-
-    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;
-        }
-
-        &.class em.property {
-            font-size: $font-size-sm;
-
-            &:first-child {
-                border-bottom: 3px solid $o-literals-border;
-            }
-
-            &:not(:first-child) {
-                @include o-code;
-                padding: 0 .3rem;
-            }
-        }
-    }
-
-    dl:not([class]) dd {
-        margin-left: $o-margin-s;
-    }
-
-    dl.field-list {
-        padding: .5rem;
-        border: 1px solid $o-gray-border;
-        @include font-size($font-size-sm);
-
-        @include media-breakpoint-down(lg) {
-            display: block;
-        }
-
-        > dt {
-            padding-left: 0;
-        }
-
-        ul {
-            list-style: none;
-            padding-left: 0;
-
-            li:not(:last-child) {
-                padding-bottom: $o-padding-xs;
-            }
-        }
-    }
-
-    iframe {
-        max-width: 100%;
-    }
-
-    main {
     position: relative;
     grid-area: main;
     padding-bottom: $o-padding-l;
@@ -547,10 +449,16 @@ header {
     &.o_index, &.o_fullwidth_page, &.o_has_code_column {
         grid-column-end: toc;
     }
+}
+
+//------------------------------------------------------------------------------
+// Content
+//------------------------------------------------------------------------------
 
 // Homepage
+// https://www.odoo.com/documentation/master/index.html
 
-        &.o_index {
+.o_index {
     .o_content_fw_banner {
         align-items: center;
         margin: 0 -0.75rem $o-margin-m;
@@ -591,8 +499,9 @@ header {
     }
 }
 
-        // First level legal page and pages with toctrees (i.e.: User Docs, Install & Maintain, Developer, Contributing)
+// First level legal page and pages with toctrees
-        &.o_fullwidth_page div.toctree-wrapper > ul {
+// (ex: https://www.odoo.com/documentation/master/developer.html)
+.o_fullwidth_page div.toctree-wrapper > ul {
     flex-wrap: wrap;
     display: flex;
 
@@ -612,8 +521,10 @@ header {
     }
 }
 
-        // pages with column for code on the right
+// Pages with a column for code on the right
-        &.o_has_code_column {
+// (ex: https://www.odoo.com/documentation/master/applications/finance/accounting/getting_started/memento.html)
+
+.o_has_code_column {
     article.doc-body {
         @include media-breakpoint-up(xl) {
             .o_git_link {
@@ -661,7 +572,7 @@ header {
     }
 }
 
-        &.o_hide_toc .toctree-wrapper {
+.o_hide_toc .toctree-wrapper {
     display: none;
 }
 
@@ -843,10 +754,52 @@ header {
     }
 }
 
-        .guilabel, .menuselection {
+iframe {
-            font-weight: $font-weight-bold;
+    max-width: 100%;
 }
 
+.container .container:not([class^="col"]) {
+    margin: 0;
+    padding: 0;
+}
+
+ul, ol {
+    text-align: left;
+}
+
+ol ol {
+    list-style: lower-alpha;
+
+    > li:before {
+        content: none;
+    }
+}
+
+//------------------------------------------------------------------------------
+// Markups
+// (see https://www.odoo.com/documentation/master/contributing/documentation/rst_cheat_sheet.html#markups)
+//------------------------------------------------------------------------------
+
+// Technical Terms (Literals)
+.o_code, .sig [class^="sig-"] {
+    @include o-code;
+}
+
+.o_code {
+    padding: 0 .3rem;
+
+//File
+    &.file {
+        padding-right: .4rem;
+        background-color: $blue-100;
+        font-family: $font-family-base;
+        font-weight: $o-font-weight-medium;
+        font-style: italic;
+        color: $blue-700;
+    }
+}
+
+// Definitions
 .dfn{
     @include font-size($font-size-sm);
     line-height: 1;
@@ -869,24 +822,99 @@ header {
     }
 }
 
+//Abbreviations
+abbr {
+    text-underline-offset: 2px;
 
-        .container .container:not([class^="col"]) {
+    &[title="Pull Request"] {
-            margin: 0;
+        @include o-easter-egg();
-            padding: 0;
+    }
 }
 
-        ul, ol {
+//GUI Element & Menu Selection
-            text-align: left;
+.guilabel, .menuselection {
+    font-weight: $font-weight-bold;
 }
 
-        ol ol {
+// API and Reference Styles
-            list-style: lower-alpha;
+//(ex: https://www.odoo.com/documentation/master/developer/reference/backend/orm.html#fields)
 
-            > li:before {
+.sig {
-                content: none;
+    .sig-prename {
+        padding-left: .3rem;
+
+        &+ .sig-name {
+            padding-right: .3rem;
         }
     }
 
+    em.property + .sig-name {
+        padding-left: .3rem;
+    }
+
+    .sig-paren:last-of-type {
+        padding-right: .3rem;
+    }
+}
+
+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;
+    }
+
+    &.class em.property {
+        font-size: $font-size-sm;
+
+        &:first-child {
+            border-bottom: 3px solid $o-literals-border;
+        }
+
+        &:not(:first-child) {
+            @include o-code;
+            padding: 0 .3rem;
+        }
+    }
+}
+
+// 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);
+
+    @include media-breakpoint-down(lg) {
+        display: block;
+    }
+
+    > dt {
+        padding-left: 0;
+    }
+
+    ul {
+        list-style: none;
+        padding-left: 0;
+
+        li:not(:last-child) {
+            padding-bottom: $o-padding-xs;
+        }
+    }
+}
+
+dl:not([class]) dd {
+    margin-left: $o-margin-s;
+}
+
+// Child of source-code URL
+// ex: https://www.odoo.com/documentation/16.0/developer/reference/backend/orm.html#odoo.models.AbstractModel
+span.viewcode-link {
+    float: none;
+    margin-left: .3rem;
+}
+
 //------------------------------------------------------------------------------
 // Alerts
 //------------------------------------------------------------------------------
@@ -922,6 +950,13 @@ header {
                 display:none;
             }
         }
+        .graphviz {
+            overflow-x: auto;
+            white-space: nowrap;
+            img {
+                max-width: unset;
+            }
+        }
     }
 
     // Custom Admonitions
@@ -998,15 +1033,6 @@ header {
         background: $gray-200;
     }
 }
-        .graphviz {
-            overflow-x: auto;
-            white-space: nowrap;
-            img {
-                max-width: unset;
-            }
-        }
-    }
-}
 
 //------------------------------------------------------------------------------
 // Spoilers
@@ -1173,6 +1199,7 @@ header {
 //------------------------------------------------------------------------------
 // Footer
 //------------------------------------------------------------------------------
+
 footer {
     .o_get_help {
         padding-top: $o-padding-l;