From 894165a94923bb4efc58cdf57471535744248019 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= Date: Wed, 3 Nov 2021 20:08:35 +0000 Subject: [PATCH] [IMP] developer: normalize reference in js doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The preferred format for (frontend) references is now: "frontend/filename/section", or something close to that. closes odoo/documentation#1291 Signed-off-by: Géry Debongnie (ged) --- .../applications/general/developer_mode.rst | 4 +-- .../reference/frontend/framework_overview.rst | 24 ++++++------- .../reference/frontend/javascript_modules.rst | 16 ++++----- .../frontend/javascript_reference.rst | 4 +-- .../reference/frontend/owl_components.rst | 8 ++--- .../reference/frontend/registries.rst | 24 ++++++------- .../developer/reference/frontend/services.rst | 34 +++++++++---------- 7 files changed, 57 insertions(+), 57 deletions(-) diff --git a/content/applications/general/developer_mode.rst b/content/applications/general/developer_mode.rst index 9d6b34634..93d6675aa 100644 --- a/content/applications/general/developer_mode.rst +++ b/content/applications/general/developer_mode.rst @@ -56,8 +56,8 @@ debug mode, add `?debug=0` instead. .. tip:: Additional modes are available for developers: `?debug=assets` enables the - :ref:`assets mode `, and `?debug=tests` enables - the :ref:`tests mode `. + :ref:`assets mode `, and `?debug=tests` enables + the :ref:`tests mode `. Locate the mode tools ===================== diff --git a/content/developer/reference/frontend/framework_overview.rst b/content/developer/reference/frontend/framework_overview.rst index 926922813..c57e2ad5f 100644 --- a/content/developer/reference/frontend/framework_overview.rst +++ b/content/developer/reference/frontend/framework_overview.rst @@ -90,7 +90,7 @@ simply a component that displays all components registered in the ``main_components`` registry. This is how other parts of the system can extend the web client. -.. _javascript/environment: +.. _frontend/framework/environment: Environment =========== @@ -108,12 +108,12 @@ the shared ``env`` object: * - `qweb` - required by Owl (contains all templates) * - `bus` - - :ref:`main bus `, used to coordinate some generic events + - :ref:`main bus `, used to coordinate some generic events * - `services` - all deployed :ref:`services ` (should usually be accessed with the `useService` hook) * - `debug` - - string. If non empty, the web client is in :ref:`debug mode ` + - string. If non empty, the web client is in :ref:`debug mode ` * - `_t` - translation function * - `isSmall` @@ -234,7 +234,7 @@ could mean a different thing depending on the situation). not to overuse it! Many problems can be solved in a standard way without modifying the context. -.. _javascript/user-context: +.. _frontend/framework/user_context: User Context ------------ @@ -316,7 +316,7 @@ and its context will be extended with the `default_period_id` value. This is a very important usecase that lets developers combine actions together by providing some information to the next action. -.. _javascript/pyjs: +.. _frontend/framework/pyjs: Python Interpreter ================== @@ -364,7 +364,7 @@ The ``py`` javascript code exports 5 functions: :param Object context: an object that provides an additional evaluation context :returns: any the resulting value of the expression, with respect to the context -.. _javascript/domains: +.. _frontend/framework/domains: Domains ======= @@ -492,12 +492,12 @@ The `Domain` class also provides 4 useful static methods to combine domains: Returns a domain representing either the intersection or the union of all the domains, depending on the value of the operator argument. -.. _javascript/bus: +.. _frontend/framework/bus: Bus === -The web client :ref:`environment ` object contains an event +The web client :ref:`environment ` object contains an event bus, named `bus`. Its purpose is to allow various parts of the system to properly coordinate themselves, without coupling them. The `env.bus` is an owl `EventBus `_, @@ -568,7 +568,7 @@ It is mostly interesting for testing purposes: all code using the browser object can be tested easily by mocking the relevant functions for the duration of the test. -.. _javascript/debug_mode: +.. _frontend/framework/debug_mode: Debug mode ========== @@ -584,7 +584,7 @@ mode is not active. Otherwise, it is active. If the string contains `assets` or `tests`, then the corresponding specific sub modes are activated (see below). Both modes can be active at the same time, for example with the string `assets,tests`. -The `debug` mode current value can be read in the :ref:`environment`: +The `debug` mode current value can be read in the :ref:`environment`: `env.debug`. .. tip:: @@ -600,7 +600,7 @@ The `debug` mode current value can be read in the :ref:`environment` -.. _javascript/debug_mode/assets: +.. _frontend/framework/assets_debug_mode: Assets mode ----------- @@ -609,7 +609,7 @@ The `debug=assets` sub mode is useful to debug javascript code: once activated, the :ref:`assets` bundles are no longer minified, and source-maps are generated as well. This makes it useful to debug all kind of javascript code. -.. _javascript/debug_mode/tests: +.. _frontend/framework/tests_debug_mode: Tests mode ---------- diff --git a/content/developer/reference/frontend/javascript_modules.rst b/content/developer/reference/frontend/javascript_modules.rst index 577a491f2..dd16e3ab0 100644 --- a/content/developer/reference/frontend/javascript_modules.rst +++ b/content/developer/reference/frontend/javascript_modules.rst @@ -4,9 +4,9 @@ Javascript Modules Odoo supports three different kinds of javascript files: -- :ref:`plain javascript files ` (no module system), -- :ref:`native javascript module `. -- :ref:`Odoo modules ` (using a custom module system), +- :ref:`plain javascript files ` (no module system), +- :ref:`native javascript module `. +- :ref:`Odoo modules ` (using a custom module system), As described in the :ref:`assets management page `, all javascript files are bundled together and served to the browser. @@ -18,7 +18,7 @@ specific low level purposes. All new javascript files should be created in the native javascript module system. The custom module system is only useful for old, not yet converted files. -.. _javascript/plain_javascript: +.. _frontend/modules/plain_js: Plain Javascript files ====================== @@ -44,7 +44,7 @@ execute them precisely in that order). .. note:: In Odoo, all external libraries are loaded as plain javascript files. -.. _javascript/native_js_module: +.. _frontend/modules/native_js: Native Javascript Modules ========================= @@ -54,7 +54,7 @@ is simpler, and brings the benefits of a better developer experience with a bett integration with the IDE. There is a very important point to know: Odoo needs to know which files -should be translated into :ref:`Odoo modules ` and which +should be translated into :ref:`Odoo modules ` and which files should not be translated. This is an opt-in system: Odoo will look at the first line of a JS file and check if it contains the string *@odoo-module*. If so, it will automatically be converted to an Odoo module. @@ -132,7 +132,7 @@ But :file:`file_c` need to use the full name: Aliased modules --------------- -Because :ref:`Odoo modules ` follow a different module naming pattern, a system exists to allow a smooth +Because :ref:`Odoo modules ` follow a different module naming pattern, a system exists to allow a smooth transition towards the new system. Currently, if a file is converted to a module (and therefore follow the new naming convention), other files not yet converted to ES6-like syntax in the project won't be able to require the module. Aliases are here to map old names with new ones by creating a @@ -258,7 +258,7 @@ them if you encounter issues with, or are constrained by the limitations of, nat within the same Odoo addon. -.. _javascript/odoo_module: +.. _frontend/modules/odoo_module: Odoo Module System =================== diff --git a/content/developer/reference/frontend/javascript_reference.rst b/content/developer/reference/frontend/javascript_reference.rst index 2ba9c6211..a0ccaf2a5 100644 --- a/content/developer/reference/frontend/javascript_reference.rst +++ b/content/developer/reference/frontend/javascript_reference.rst @@ -134,10 +134,10 @@ For most Odoo code, we want to use a module system. Because of the way assets work in Odoo (and in particular, the fact that each installed odoo addon can modify the list of files contained in a bundle), Odoo has to resolve modules browser side. To do that, Odoo provides a small module system described just -below (see :ref:`javascript/odoo_module`). +below (see :ref:`frontend/modules/odoo_module`). However, Odoo also provides support for native javascript modules (see -:ref:`javascript/native_js_module`). These modules +:ref:`frontend/modules/native_js`). These modules will simply be translated by the server into odoo modules. It is encouraged to write all javascript code as a native module, for a better IDE integration. In the future, the Odoo module system should be considered an implementation detail, diff --git a/content/developer/reference/frontend/owl_components.rst b/content/developer/reference/frontend/owl_components.rst index b4b488706..7d7854a31 100644 --- a/content/developer/reference/frontend/owl_components.rst +++ b/content/developer/reference/frontend/owl_components.rst @@ -149,12 +149,12 @@ checkboxes or datepickers. This page explains how to use these generic component * - Technical Name - Short Description - * - :ref:`CheckBox ` + * - :ref:`CheckBox ` - a simple checkbox component with a label next to it - * - :ref:`Dropdown ` + * - :ref:`Dropdown ` - full-featured dropdown -.. _frontend/checkbox: +.. _frontend/owl/checkbox: CheckBox -------- @@ -193,7 +193,7 @@ Props - `boolean` - if true, the checkbox is disabled, otherwise it is enabled -.. _frontend/dropdown: +.. _frontend/owl/dropdown: Dropdown -------- diff --git a/content/developer/reference/frontend/registries.rst b/content/developer/reference/frontend/registries.rst index 6fbf193f8..22ceec15d 100644 --- a/content/developer/reference/frontend/registries.rst +++ b/content/developer/reference/frontend/registries.rst @@ -104,16 +104,16 @@ Reference List * - Category - Content - * - :ref:`main_components ` + * - :ref:`main_components ` - top level components - * - :ref:`services ` + * - :ref:`services ` - all services that should be activated - * - :ref:`systray ` + * - :ref:`systray ` - components displayed in the systray zone in the navbar - * - :ref:`user_menuitems ` + * - :ref:`user_menuitems ` - menu items displayed in the user menu (top right of navbar) -.. _registries/main_components: +.. _frontend/registries/main_components: Main components registry ------------------------ @@ -141,7 +141,7 @@ this: Component: LoadingIndicator, }); -.. _registries/services: +.. _frontend/registries/services: Service registry ---------------- @@ -163,7 +163,7 @@ framework. registry.category("services").add("myService", myService); -.. _registries/systray: +.. _frontend/registries/systray: Systray registry ---------------- @@ -178,7 +178,7 @@ with the following three keys: - `Component`: the component class that represents the item. Its root element should be a `
  • ` tag, otherwise it might not be styled properly. - `props (optional)`: props that should be given to the component -- `isDisplayed (optional)`: a function that takes the :ref:`env ` +- `isDisplayed (optional)`: a function that takes the :ref:`env ` and returns a boolean. If true, the systray item is displayed. Otherwise it is removed. @@ -210,7 +210,7 @@ The sequence number defaults to 50. If given, this number will be used to order the items. The lowest sequence is on the right and the highest sequence is on the left in the systray menu. -.. _registries/usermenu: +.. _frontend/registries/usermenu: Usermenu registry ----------------- @@ -219,7 +219,7 @@ The user menu registry (category: `user_menuitems`) contains all menu items that are shown when opening the user menu (the navbar element with the user name, on the top right). -User menu items are defined by a function taking the :ref:`env ` +User menu items are defined by a function taking the :ref:`env ` and returning a plain object, containing the following information: * `description` : the menu item text, @@ -244,5 +244,5 @@ Example: }; } -:ref:`Effect registry` --------------------------------------------------- \ No newline at end of file +:ref:`Effect registry` +--------------------------------------------------------- \ No newline at end of file diff --git a/content/developer/reference/frontend/services.rst b/content/developer/reference/frontend/services.rst index f0f7c5068..755aa3335 100644 --- a/content/developer/reference/frontend/services.rst +++ b/content/developer/reference/frontend/services.rst @@ -116,20 +116,20 @@ Reference List * - Technical Name - Short Description - * - :ref:`cookie ` + * - :ref:`cookie ` - read or modify cookies - * - :ref:`effect ` + * - :ref:`effect ` - display graphical effects - * - :ref:`notification ` + * - :ref:`notification ` - display notifications - * - :ref:`rpc ` + * - :ref:`rpc ` - send requests to the server - * - :ref:`title ` + * - :ref:`title ` - read or modify the window title - * - :ref:`user ` + * - :ref:`user ` - provides some information related to the current user -.. _services/cookie: +.. _frontend/services/cookie: Cookie service -------------- @@ -167,7 +167,7 @@ API Deletes the cookie `name`. -.. _services/effect: +.. _frontend/services/effect: Effect service -------------- @@ -270,7 +270,7 @@ RainbowMan How to add an effect ~~~~~~~~~~~~~~~~~~~~ -.. _javascript/effect_registry: +.. _frontend/services/effect_registry: The effects are stored in a registry called `effects`. You can add new effects by providing a name and a function. @@ -341,7 +341,7 @@ Here, it is called in webclient.js to make it visible everywhere for the example :width: 600 :align: center -.. _services/notification: +.. _frontend/services/notification: Notification service -------------------- @@ -455,7 +455,7 @@ A notification that closes after a second: const close = notificationService.add("I will be quickly closed"); setTimeout(close, 1000); -.. _services/rpc: +.. _frontend/services/rpc: RPC service ----------- @@ -548,11 +548,11 @@ When a rpc fails, then: If it is a network error, then the error description is simply an object ``{type: 'network'}``. - When a network error occurs, a :ref:`notification ` is + When a network error occurs, a :ref:`notification ` is displayed and the server is regularly contacted until it responds. The notification is closed as soon as the server responds. -.. _services/title: +.. _frontend/services/title: Title Service ------------- @@ -627,7 +627,7 @@ Its API is: will change the title to ``Odoo``. -.. _services/user: +.. _frontend/services/user: User service ------------ @@ -654,7 +654,7 @@ API - Description * - ``context`` - ``Object`` - - The :ref:`user context` + - The :ref:`user context` * - ``db`` - ``Object`` - Info about the database @@ -691,7 +691,7 @@ API :param object update: the object to update the context with - update the :ref:`user context` with the given object. + update the :ref:`user context` with the given object. .. code-block:: javascript @@ -701,7 +701,7 @@ API :param string key: the key of the targeted attribute - remove the value with the given key from the :ref:`user context` + remove the value with the given key from the :ref:`user context` .. code-block:: js