From cca26f7952826601e9119478ac0edc30859d7f6a Mon Sep 17 00:00:00 2001 From: Xavier Morel Date: Tue, 5 Feb 2019 10:14:57 +0000 Subject: [PATCH 1/4] [FIX] doc: workarounds for weirdo code & refs Make UnknownNS more capable (of giving no fucks) so the documentation builder blows up less on weird-ass code at module toplevels. UnknownNS should probably be split out from NSDoc though, that requires odd workarounds in `__getitem__`. --- doc/_extensions/autojsdoc/parser/jsdoc.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/doc/_extensions/autojsdoc/parser/jsdoc.py b/doc/_extensions/autojsdoc/parser/jsdoc.py index e6bd609f298..9e9b0ba441d 100644 --- a/doc/_extensions/autojsdoc/parser/jsdoc.py +++ b/doc/_extensions/autojsdoc/parser/jsdoc.py @@ -275,11 +275,26 @@ class ClassDoc(NSDoc): d['mixins'] = self.mixins return d +DEFAULT = object() class UnknownNS(NSDoc): + params = () # TODO: log warning when (somehow) trying to access / document an unknown object as ctor? def get_property(self, name): return super(UnknownNS, self).get_property(name) or \ UnknownNS({'name': '{}.{}'.format(self.name, name)}) + def __getitem__(self, item): + if self._probably_not_property(item): + return super().__getitem__(item) + return self.get_property(item) + + def _probably_not_property(self, item): + return ( + not isinstance(item, str) + or item in (self.namekey, 'name', 'params') + or item.startswith(('_', 'guessed_')) + or item in self.parsed + ) + class Unknown(CommentDoc): @classmethod def from_(cls, source): @@ -325,7 +340,7 @@ def parse_comments(comments, doctype=None): # in case a specific doctype is given, allow overriding it anyway return guess(parsed, default=doctype) -def guess(parsed, default=NSDoc): +def guess(parsed, default=UnknownNS): if 'class' in parsed: return ClassDoc(parsed) if 'function' in parsed: From 3f8d20b7785af4749e852461f0bd8a077b52e87e Mon Sep 17 00:00:00 2001 From: Xavier Morel Date: Tue, 5 Feb 2019 10:15:47 +0000 Subject: [PATCH 2/4] [FIX] web_editor: various levels of broken in docstrings --- addons/web_editor/static/src/js/wysiwyg/plugin/helper.js | 4 ++-- addons/web_editor/static/src/js/wysiwyg/wysiwyg_iframe.js | 4 ---- .../static/src/js/wysiwyg_snippets/wysiwyg_snippets.js | 1 - 3 files changed, 2 insertions(+), 7 deletions(-) diff --git a/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js b/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js index 68542d7a4f8..0fe576adf8e 100644 --- a/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js +++ b/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js @@ -125,7 +125,7 @@ var HelperPlugin = AbstractPlugin.extend({ * Returns the number of leading breakable space in the textNode. * Note: returns 0 if the node is not a textNode. * - * @param {Node} + * @param {Node} node */ countLeadingBreakableSpace: function (node) { if (!dom.isText(node)) { @@ -704,7 +704,7 @@ var HelperPlugin = AbstractPlugin.extend({ /** * Returns the node targeted by a path * - * @param {Object[]} list of object (tagName, offset) + * @param {Object[]} path list of object (tagName, offset) * @returns {Node} */ fromPath: function (path) { diff --git a/addons/web_editor/static/src/js/wysiwyg/wysiwyg_iframe.js b/addons/web_editor/static/src/js/wysiwyg/wysiwyg_iframe.js index 9de5c6b4cb7..be6ac41e5cb 100644 --- a/addons/web_editor/static/src/js/wysiwyg/wysiwyg_iframe.js +++ b/addons/web_editor/static/src/js/wysiwyg/wysiwyg_iframe.js @@ -193,10 +193,6 @@ Wysiwyg.include({ * * @param {Node} [DOM] * @returns {Object} - * @returns {Node} sc - start container - * @returns {Number} so - start offset - * @returns {Node} ec - end container - * @returns {Number} eo - end offset */ Wysiwyg.getRange = function (DOM) { var summernote = (DOM.defaultView || DOM.ownerDocument.defaultView)._summernoteSlave || _summernoteMaster; diff --git a/addons/web_editor/static/src/js/wysiwyg_snippets/wysiwyg_snippets.js b/addons/web_editor/static/src/js/wysiwyg_snippets/wysiwyg_snippets.js index 5df48ebf2f9..f88ae46376f 100644 --- a/addons/web_editor/static/src/js/wysiwyg_snippets/wysiwyg_snippets.js +++ b/addons/web_editor/static/src/js/wysiwyg_snippets/wysiwyg_snippets.js @@ -50,7 +50,6 @@ Wysiwyg.include({ * snippets can by url begin with '/' or an view xml_id. * * @override - * @param {string} [options.snippets] */ start: function () { var self = this; From 7065ea520c26d96e85f4e887fe871a58ae87a811 Mon Sep 17 00:00:00 2001 From: Xavier Morel Date: Tue, 5 Feb 2019 10:38:06 +0000 Subject: [PATCH 3/4] [FIX] *: various docstring formatting issues Would yield block quotes instead of code blocks or lists or whatnot. --- .../static/src/js/mass_mailing_widget.js | 6 +++--- .../static/src/js/widgets/name_and_signature.js | 3 ++- .../static/src/js/wysiwyg/plugin/helper.js | 17 +++++++++-------- .../static/src/js/wysiwyg/plugin/unbreakable.js | 12 ++++++++---- 4 files changed, 22 insertions(+), 16 deletions(-) diff --git a/addons/mass_mailing/static/src/js/mass_mailing_widget.js b/addons/mass_mailing/static/src/js/mass_mailing_widget.js index cf97d3fd9a0..e87c6a11f70 100644 --- a/addons/mass_mailing/static/src/js/mass_mailing_widget.js +++ b/addons/mass_mailing/static/src/js/mass_mailing_widget.js @@ -35,9 +35,9 @@ var MassMailingFieldHtml = FieldHtml.extend({ //-------------------------------------------------------------------------- /** - * Commit the change in 'style-inline' on an other field - * nodeOptions: - * - inline-field: fieldName to save the html value converted into inline code + * Commit the change in 'style-inline' on an other field nodeOptions: + * + * - inline-field: fieldName to save the html value converted into inline code * * @override */ diff --git a/addons/web/static/src/js/widgets/name_and_signature.js b/addons/web/static/src/js/widgets/name_and_signature.js index 53355fc7aa4..c860b0a4361 100644 --- a/addons/web/static/src/js/widgets/name_and_signature.js +++ b/addons/web/static/src/js/widgets/name_and_signature.js @@ -52,8 +52,9 @@ var NameAndSignature = Widget.extend({ * @param {string} [options.mode='draw'] - @see this.setMode * @param {string} [options.signatureType='signature'] - The type of * signature used in 'auto' mode. Can be one of the following values: + * * - 'signature': it will adapt the characters width to fit the whole - * text in the image. + * text in the image. * - 'initial': it will adapt the space between characters to fill * the image with the text. The text will be the first letter of * every word in the name, separated by dots. diff --git a/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js b/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js index 0fe576adf8e..9d346d42a27 100644 --- a/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js +++ b/addons/web_editor/static/src/js/wysiwyg/plugin/helper.js @@ -151,19 +151,20 @@ var HelperPlugin = AbstractPlugin.extend({ }, /** * Remove the dom between 2 points (respecting unbreakable rules). - * Returns an object: - * { - * node: pointA.node (updated if necessary), - * offset: pointA.offset (updated if necessary), - * changed: bool (whether changes were applied) - * } + * Returns an object:: + * + * { + * node: pointA.node (updated if necessary), + * offset: pointA.offset (updated if necessary), + * changed: bool (whether changes were applied) + * } * * @param {Object} pointA * @param {Node} pointA.node - * @param {Integer} pointA.offset + * @param {number} pointA.offset * @param {Object} pointB * @param {Node} pointB.node - * @param {Integer} pointB.offset + * @param {number} pointB.offset * @returns {Object} {node, offset, changed} */ deleteBetween: function (pointA, pointB) { diff --git a/addons/web_editor/static/src/js/wysiwyg/plugin/unbreakable.js b/addons/web_editor/static/src/js/wysiwyg/plugin/unbreakable.js index 81a90d55413..388a3b2b2c9 100644 --- a/addons/web_editor/static/src/js/wysiwyg/plugin/unbreakable.js +++ b/addons/web_editor/static/src/js/wysiwyg/plugin/unbreakable.js @@ -33,7 +33,9 @@ var Unbreakable = AbstractPlugin.extend({ //-------------------------------------------------------------------------- /** - * Change the selection if it breaks an unbreakable node. + * Change the selection if it breaks an unbreakable node: + * + * .. code-block:: xml * content_1 @@ -56,6 +58,8 @@ var Unbreakable = AbstractPlugin.extend({ + * .. code-block: none + START END RESIZE START RESIZE END content_1 content_1 content_3 content_3 (find the first allowed node) @@ -70,9 +74,9 @@ var Unbreakable = AbstractPlugin.extend({ content_6 content_8 - content_6 content_7 content_8 - content_8 content_9 content_12 content_10 - - * - * @returns {WrappedRange} - */ + * + * @returns {WrappedRange} + */ secureRange: function () { var self = this; var range = this.context.invoke('editor.createRange'); From f7e1f0645e93adb2eb78c383ac9bf9fbae80315c Mon Sep 17 00:00:00 2001 From: Xavier Morel Date: Tue, 5 Feb 2019 11:59:06 +0000 Subject: [PATCH 4/4] [IMP] doc: PYTHONPATH configuration Previously we'd `append` the extensions and odoo parent directories to sys.path, however this means if an `odoo` is already installed in a sys.path (e.g. global installation, or setup.py develop in a venv, ...) *that* will be used as the source of Python code (for autodoc) instead of the Python source being synchronised with the rst, which can lead to very odd behaviour. Prepend the doc's stuff to the PYTHONPATH instead, to ensure they get priority and the code matching the rst gets loaded. --- doc/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 3563433ff9d..0390c443e15 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -6,11 +6,11 @@ import sphinx # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. DIR = os.path.dirname(__file__) -sys.path.append( +sys.path.insert(0, os.path.abspath( os.path.join(DIR, '_extensions'))) -# autodoc -sys.path.append(os.path.abspath(os.path.join(DIR, '..'))) +# put current odoo's source on PYTHONPATH for autodoc +sys.path.insert(0, os.path.abspath(os.path.join(DIR, '..'))) # -- General configuration -----------------------------------------------------