bealdav · Jul 1, 2015 · Jul 7, 2015 · Jul 20, 2015 · Jul 22, 2015 · Sep 14, 2015
diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1,2 @@
+# generated from manifests external_dependencies
+markdown
diff --git a/screen_help/README.rst b/screen_help/README.rst
@@ -0,0 +1,182 @@
+.. image:: https://odoo-community.org/readme-banner-image
+   :target: https://odoo-community.org/get-involved?utm_source=readme
+   :alt: Odoo Community Association
+
+===========
+Screen Help
+===========
+
+.. 
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! This file is generated by oca-gen-addon-readme !!
+   !! changes will be overwritten.                   !!
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !! source digest: sha256:b113369bd035b86629b2afd3508c259b9c418b7d9cdab283d61336f951214772
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+.. |badge1| image:: https://img.shields.io/badge/maturity-Alpha-red.png
+    :target: https://odoo-community.org/page/development-status
+    :alt: Alpha
+.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
+    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
+    :alt: License: AGPL-3
+.. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fknowledge-lightgray.png?logo=github
+    :target: https://github.com/OCA/knowledge/tree/19.0/screen_help
+    :alt: OCA/knowledge
+.. |badge4| image:: https://img.shields.io/badge/weblate-Translate%20me-F47D42.png
+    :target: https://translation.odoo-community.org/projects/knowledge-19-0/knowledge-19-0-screen_help
+    :alt: Translate me on Weblate
+.. |badge5| image:: https://img.shields.io/badge/runboat-Try%20me-875A7B.png
+    :target: https://runboat.odoo-community.org/builds?repo=OCA/knowledge&target_branch=19.0
+    :alt: Try me on Runboat
+
+|badge1| |badge2| |badge3| |badge4| |badge5|
+
+Contextual help on the screens of Odoo, written in Odoo or shipped by
+modules as Markdown files.
+
+A book button in the control panel opens the help of the current screen
+in a window detached from the Odoo tab, which can stay open beside Odoo.
+
+The help of a screen is made of sections, ordered by sequence, which
+target:
+
+- a window action: shown on the screens of this action
+- or a model: shown on every screen of this model, whatever the action
+
+**The module shipping the files doesn't need to depend on
+``screen_help``.**
+
+.. IMPORTANT::
+   This is an alpha version, the data model and design can change at any time without warning.
+   Only for development or testing purpose, do not use in production.
+   `More details on development status <https://odoo-community.org/page/development-status>`_
+
+**Table of contents**
+
+.. contents::
+   :local:
+
+Configuration
+=============
+
+- Users of the *Help Editor* group (and administrators) can write the
+  help: *Settings > Technical > User Interface > Help Sections*, or the
+  *Edit* button of the help window.
+- *Settings > General Settings > Help > Multilingual Help*: a section
+  can be written for a given language. A section without language is
+  shown to everybody. The help is not translated through the standard
+  translation mechanism.
+- Dark mode: the help window follows the color scheme of the user
+  (``ir.http.color_scheme()``) when a module provides it, e.g.
+  ``web_dark_mode`` (OCA/web) or ``web_enterprise``; no dependency on
+  them.
+
+Usage
+=====
+
+**Read the help**: click the book button of the control panel. The
+button is shown when the screen has some help, or to the help editors.
+
+**Write the help in Odoo**: *Edit* button of the help window, then add a
+section targeting the action or the model of the screen.
+
+|Help window beside Odoo|
+
+**Ship the help in a module**: add Markdown files in its ``help``
+directory:
+
+::
+
+   my_module/help/sale.order.md                     # every screen of the model
+   my_module/help/sale.action_quotations.md         # one window action (xml id)
+   my_module/help/sale.action_quotations.fr_FR.md   # in French only
+
+**You don't need to depends on screen_help** to provide a such files to
+document your module, just add markdown like above
+
+An optional header orders the sections (sequence 10 by default). In the
+application help, the screens are ordered by the lowest sequence of
+their sections, then by the menu order:
+
+.. code:: markdown
+
+   ---
+   sequence: 20
+   ---
+   ## My help
+
+When ``screen_help`` is installed, the ``help`` directory of a module is
+loaded at each installation / update of the module (and for all the
+installed modules at the installation of ``screen_help``). Without
+``screen_help``, it is ignored.
+
+- a section loaded from a file can't be edited in Odoo
+- a file removed from the module removes its section at the next update
+- a file whose model or action doesn't exist (module not installed) is
+  ignored
+- the headings (``#``, ``##``, ``###``) make the table of contents of
+  the help window
+
+|Section loaded from a file|
+
+**Demo**: on a database with demo data, a tour documents each feature on
+the screen that shows it, each section pointing to the next screen like
+contacts,
+`/odoo/action-base.action_partner_form </odoo/action-base.action_partner_form>`__
+
+|Help window in dark mode|
+
+.. |Help window beside Odoo| image:: https://raw.githubusercontent.com/OCA/knowledge/19.0/screen_help/static/description/help1.png
+.. |Section loaded from a file| image:: https://raw.githubusercontent.com/OCA/knowledge/19.0/screen_help/static/description/help3.png
+.. |Help window in dark mode| image:: https://raw.githubusercontent.com/OCA/knowledge/19.0/screen_help/static/description/help2.png
+
+Bug Tracker
+===========
+
+Bugs are tracked on `GitHub Issues <https://github.com/OCA/knowledge/issues>`_.
+In case of trouble, please check there if your issue has already been reported.
+If you spotted it first, help us to smash it by providing a detailed and welcomed
+`feedback <https://github.com/OCA/knowledge/issues/new?body=module:%20screen_help%0Aversion:%2019.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
+
+Do not contact contributors directly about support or help with technical issues.
+
+Credits
+=======
+
+Authors
+-------
+
+* Akretion
+
+Contributors
+------------
+
+- `Akretion <https://www.akretion.com>`__:
+
+  - David Beal david.beal@akretion.com Assisted-by: Claude Opus 5.5
+
+Maintainers
+-----------
+
+This module is maintained by the OCA.
+
+.. image:: https://odoo-community.org/logo.png
+   :alt: Odoo Community Association
+   :target: https://odoo-community.org
+
+OCA, or the Odoo Community Association, is a nonprofit organization whose
+mission is to support the collaborative development of Odoo features and
+promote its widespread use.
+
+.. |maintainer-bealdav| image:: https://github.com/bealdav.png?size=40px
+    :target: https://github.com/bealdav
+    :alt: bealdav
+
+Current `maintainer <https://odoo-community.org/page/maintainer-role>`__:
+
+|maintainer-bealdav| 
+
+This module is part of the `OCA/knowledge <https://github.com/OCA/knowledge/tree/19.0/screen_help>`_ project on GitHub.
+
+You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.
diff --git a/screen_help/__init__.py b/screen_help/__init__.py
@@ -0,0 +1,10 @@
+from . import controllers
+from . import models
+
+
+def post_init_hook(env):
+    # help files of the modules installed before screen_help
+    for module in env["ir.module.module"].search([("state", "=", "installed")]):
+        env["help.section"]._load_markdown(module.name)
+    # help of the actions left by help_popup, if any
+    env["help.section"]._import_help_popup()
diff --git a/screen_help/__manifest__.py b/screen_help/__manifest__.py
@@ -0,0 +1,32 @@
+{
+    "name": "Screen Help",
+    "summary": "Contextual help on actions, editable in Odoo or shipped as Markdown",
+    "version": "19.0.1.0.0",
+    "development_status": "Alpha",
+    "category": "Knowledge Management",
+    "website": "https://github.com/OCA/knowledge",
+    "author": "Akretion, Odoo Community Association (OCA)",
+    "maintainers": ["bealdav"],
+    "license": "AGPL-3",
+    "depends": ["base_setup"],
+    "external_dependencies": {
+        "python": ["markdown"],
+    },
+    "data": [
+        "security/groups.xml",
+        "security/ir.model.access.csv",
+        "views/help_section.xml",
+        "views/res_config_settings.xml",
+        "views/help_page.xml",
+    ],
+    "demo": [
+        "data/demo.xml",
+        "data/demo_section.xml",
+    ],
+    "post_init_hook": "post_init_hook",
+    "assets": {
+        "web.assets_backend": [
+            "screen_help/static/src/**/*",
+        ],
+    },
+}
diff --git a/screen_help/controllers/__init__.py b/screen_help/controllers/__init__.py
@@ -0,0 +1 @@
+from . import main
diff --git a/screen_help/controllers/main.py b/screen_help/controllers/main.py
@@ -0,0 +1,39 @@
+from odoo import http
+from odoo.http import request
+
+
+class ScreenHelp(http.Controller):
+    @http.route("/screen_help", type="http", auth="user")
+    def help(self, action_id=None, model=None, menu_id=None):
+        env = request.env
+        action = env["ir.actions.act_window"].browse(int(action_id or 0)).exists()
+        model = model or action.res_model
+        if action:
+            title, prefix = action.name, f"help_{action.id}"
+        else:
+            title, prefix = env["ir.model"]._get(model).name or model, "help"
+        body, toc = env["help.section"]._for(action, model)._html(prefix)
+        return request.render(
+            "screen_help.screen_help_page",
+            {
+                **env["ir.http"].webclient_rendering_context(),
+                "title": title,
+                "body": body,
+                "toc": toc,
+                "menu_id": int(menu_id) if menu_id else False,
+                "can_edit": env.user.has_group("screen_help.group_editor"),
+                "action_id": action.id,
+                "model": model,
+            },
+        )
+
+    @http.route("/screen_help/app/<int:menu_id>", type="http", auth="user")
+    def app_help(self, menu_id):
+        env = request.env
+        menu = env["ir.ui.menu"].browse(menu_id).exists()
+        if not menu:
+            raise request.not_found()
+        return request.render(
+            "screen_help.app_help_page",
+            {**env["ir.http"].webclient_rendering_context(), "menu": menu},
+        )
diff --git a/screen_help/data/demo.xml b/screen_help/data/demo.xml
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!-- not noupdate: the function must run again at each update -->
+<odoo noupdate="0">
+    <function
+        model="help.section"
+        name="_load_markdown"
+        eval="['screen_help', 'demo_help']"
+    />
+</odoo>
diff --git a/screen_help/data/demo_section.xml b/screen_help/data/demo_section.xml
@@ -0,0 +1,21 @@
+<odoo noupdate="1">
+    <!-- section written in Odoo (editable), not shipped as a Markdown file -->
+    <record id="demo_section_users" model="help.section">
+        <field name="action_id" ref="base.action_res_users" />
+        <field name="content" type="html">
+            <h2>Help written in Odoo</h2>
+            <p>Unlike the other sections of the demo, this one is not a file
+                of a module: it is written in Odoo, with the HTML editor.</p>
+            <h3>Who can write the help</h3>
+            <ul>
+                <li>the users of the <strong>Help Editor</strong> group
+                    (the administrators are in it)</li>
+                <li>with the <em>Edit</em> button of this window, or
+                    <em>Settings &gt; Technical &gt; User Interface &gt;
+                    Help Sections</em></li>
+            </ul>
+            <h3>Next</h3>
+            <p>Open <em>Settings &gt; Users &amp; Companies &gt; Companies</em>.</p>
+        </field>
+    </record>
+</odoo>
diff --git a/screen_help/demo_help/base.action_partner_form.fr_FR.md b/screen_help/demo_help/base.action_partner_form.fr_FR.md
@@ -0,0 +1,14 @@
+---
+sequence: 15
+---
+
+## Aide dans une langue
+
+Cette section n'est visible que des utilisateurs en français : elle vient du fichier
+`base.action_partner_form.fr_FR.md`. Elle complète les sections sans langue, montrées à
+tout le monde : ce n'est pas une traduction.
+
+Exemple : le **SIRET** est obligatoire pour les sociétés clientes.
+
+Pour choisir la langue d'une section écrite dans Odoo, activez le réglage _Multilingual
+Help_ (_Paramètres > Paramètres généraux_, bloc _Help_).
diff --git a/screen_help/demo_help/base.action_partner_form.md b/screen_help/demo_help/base.action_partner_form.md
@@ -0,0 +1,25 @@
+## Help of a screen
+
+This help is the demo of _Screen Help_: each screen of the demo documents one of its
+features. You opened it with the book button of the control panel, shown when the screen
+has some help, or always to the help editors.
+
+### Help of an action
+
+This section targets the window action of the screen: a module ships it as the file
+`help/base.action_partner_form.md`, named after the xml id of the action.
+
+| Element of the window | Use                                                   |
+| --------------------- | ----------------------------------------------------- |
+| Sidebar               | table of contents, made from the headings of the help |
+| _Print_               | prints the help of the screen                         |
+| _Application Help_    | the help of all the screens of the application        |
+| _Edit_                | edits the help in the Odoo tab (help editors only)    |
+
+The window stays open beside Odoo: keep it while you work.
+
+![Help window beside Odoo](/screen_help/static/description/help1.png)
+
+### Next
+
+The section below targets the model of the contacts, not this action.
diff --git a/screen_help/demo_help/base.action_res_company_form.md b/screen_help/demo_help/base.action_res_company_form.md
@@ -0,0 +1,19 @@
+## Help of an application
+
+Click _Application Help_ at the top of this window: it shows the help of all the screens
+of the current application (here _Settings_: the users and the companies), one chapter
+per screen, ordered by the lowest sequence of their sections, then by the menu order.
+The help of a model is shown once, with its first screen.
+
+### Look of the window
+
+- **Logo**: the logo of the company, at the top of the window
+- **Print**: the help, without the buttons and the sidebar
+- **Dark mode**: follows the color scheme of the user, when a module provides it
+  (`web_dark_mode` of OCA/web, or `web_enterprise`)
+
+![Help window in dark mode](/screen_help/static/description/help2.png)
+
+### Next
+
+Open _Settings > Technical > User Interface > Help Sections_.
diff --git a/screen_help/demo_help/res.partner.md b/screen_help/demo_help/res.partner.md
@@ -0,0 +1,28 @@
+---
+sequence: 20
+---
+
+## Help of a model
+
+This section targets the model `res.partner`: it is shown on every screen of the
+contacts, whatever the action. A module ships it as the file `help/res.partner.md`,
+named after the model.
+
+### Order of the sections
+
+The sections are ordered by sequence (10 by default). The header at the top of the file
+puts this one after the help of the action:
+
+```markdown
+---
+sequence: 20
+---
+```
+
+### Table of contents
+
+The headings `#`, `##` and `###` make the table of contents of the sidebar.
+
+### Next
+
+Open _Settings > Users & Companies > Users_: a section written in Odoo.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# generated from manifests external_dependencies
		markdown