[IMP] website: improve documentation of user custom files

See https://github.com/odoo/odoo/pull/29999

3 files changed, 54 insertions, 3 deletions

diff --git a/addons/website/static/src/js/user_custom_javascript.js b/addons/website/static/src/js/user_custom_javascript.js
index 7849f0a9d2a..928fb0a7b9f 100644
--- a/addons/website/static/src/js/user_custom_javascript.js
+++ b/addons/website/static/src/js/user_custom_javascript.js
@@ -1 +1,24 @@
-// Here, you can add your custom JavaScript code.
+//
+// This file is meant to regroup your javascript code. You can either copy/past
+// any code that should be executed on each page loading or write your own
+// taking advantage of the Odoo framework to create new behaviors or modify
+// existing ones. For example, doing this will greet any visitor with a 'Hello,
+// world !' message in a popup:
+//
+/*
+odoo.define('website.user_custom_code', function (require) {
+'use strict';
+
+var Dialog = require('web.Dialog');
+var sAnimations = require('website.content.snippets.animation');
+
+sAnimations.registry.HelloWorldPopup = sAnimations.Class.extend({
+    selector: '#wrapwrap',
+
+    start: function () {
+        Dialog.alert(this, "Hello, world!");
+        return this._super.apply(this, arguments);
+    },
+})
+});
+*/
diff --git a/addons/website/static/src/scss/user_custom_bootstrap_overridden.scss b/addons/website/static/src/scss/user_custom_bootstrap_overridden.scss
index f61478ec484..ecf5d4602cc 100644
--- a/addons/website/static/src/scss/user_custom_bootstrap_overridden.scss
+++ b/addons/website/static/src/scss/user_custom_bootstrap_overridden.scss
@@ -1 +1,22 @@
-// Here, you can override Bootstrap variables.
+//
+// /!\
+// This file is meant to regroup your bootstrap customizations. In that file,
+// you must define variables *ONLY*. If you want to introduce new CSS rules
+// for your website, check the 'user_custom_rules.scss' file you can also edit.
+// /!\
+//
+// You can change the value of a variable you can find in the bootstrap 4
+// documentation (or in the file /web/static/lib/bootstrap/scss/_variables.scss)
+// and Odoo will automatically adapt its design to your new bootstrap. For
+// example, doing this will make some shadows and gradients appear, especially
+// for your buttons design:
+//
+// $enable-shadows: true;
+// $enable-gradients: true;
+//
+// Notice that Odoo already overrides bootstrap variables according to your
+// choices in the "Customize Theme" dialog, you should first take a look at
+// it and do customizations this way. Indeed, if you overridde the same
+// variables, Odoo will either have to ignore them or not be able to make
+// the "Customize Theme" dialog work for these variables anymore.
+//
diff --git a/addons/website/static/src/scss/user_custom_rules.scss b/addons/website/static/src/scss/user_custom_rules.scss
index cf96bd6a046..181c4c171f8 100644
--- a/addons/website/static/src/scss/user_custom_rules.scss
+++ b/addons/website/static/src/scss/user_custom_rules.scss
@@ -1 +1,8 @@
-// Here, you can add your custom CSS rules.
+//
+// This file is meant to regroup your design customizations. For example, doing
+// this will separate your footer with a dotted border using your primary color.
+//
+// footer {
+//     border-top: 5px dotted theme-color('primary');
+// }
+//