* properly handle 3-args version of odoo.define(): just ignore the
second argument, pretty much the only use-case is dynamic
dependencies (otherwise it should be using static require() calls)
so there's little the extractor can do
* fix an issue with sys.path ordering meaning sphinx would pick up an
odoo installed into the current virtualenv (editable or not) over
the local copy it's part of
closesodoo/odoo#33538
Signed-off-by: Xavier Morel (xmo) <xmo@odoo.com>
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__`.
https://bugs.python.org/issue33899
tokenize.generate_tokens was altered to match the C tokenizer,
previously it would end the tokenization with just an ENDMARKER, in the
titled releases it adds a NEWLINE before the ENDMARKER if none is
present, this broke the parsing of jsdoc type specifications as Python's
tokenizer is used under the cover.
closesodoo/odoo#28056
Else website_sale_wishlist.wishlist blows up the documenter:
``events`` is set to sAnimations.Class.events but that is not an "own
property" of sAnimation.Class, it is instead inherited from Widget.
If delegation is not implemented, the value resolves to <nothing>,
which blows up when trying to set its name to the "property name" (by
calling ``set_name``).
doc:
* fix incorrect doc comments (documenting params which don't exist)
* correctly quote non-refs
* fix role label syntax (backticks must be escaped)
* add newline to fix warning
JS doc parser:
* fix handling of already-resolved objects
* fix handling of non-string properties (e.g. foo[0] at module toplevel)
* don't blow up if subject of .include call can't be resolved (just ignore)
Others:
* add translator support for ``problematic`` node (apparently used for
some refs by recent Sphinx)
With more than 1 level of generic type, the "closure" of generic
parameters would get tokenized by python as a single right shift (>>)
rather than two gt (>, >) leading to our own tokenizing pass getting
lost and blowing up.
Fix by explicitly recognizing and splitting (>>) into (>, >). We could
consider writing the entire tokenizer ourselves instead of
post-processing Python's but given the entire post-processing function
is currently shorter than just Pythons' tokenizer's regexes...
Anyway issue found by vsc while trying to write better docstrings.
Revert 6cb12273e2 which reverted
08d48b0fff.
Issue was the support for sub-parameters (aka @param {type} foo.bar)
where the "parent" parameter was not formal (only present in a
function's docstring, but not in the function's parameters list),
subtype creation would fail to find a root parameter to attach the
sub-parameter to.
This has not actually been fixed, but for the specific case where the
formal parameters list is *completely empty* we fall back on a list of
the docstring's parameters, which works well enough for this case.
Before this, if a new global was added to JS code (module toplevel,
function bodies are not considered) it would blow up when attempting
to resolve variable refs & uses.
Make the toplevel scope a defaultdict such that if e.g. a "foo" is
looked up in a module but not a local variable of that module it's
assumed to be an UnknownNS object (from which further UnknownNS can be
deref'd).
* fix P3 incompatibilities in doc/_extensions
* vendor pyjsdoc, strip out everything we're not using and make what's
left P3-compatible (upstream is not P3 compliant)
* drop undeclared dependency on attrs as it turns out not to be much
used
* Fix a bunch of ill-documented/incomplete/incorrect method docs
* add start of Sphinx extension to extract & integrate jsdoc into
Sphinx documentation:
- parse JS files (and don't blow up), uses a fork of pyjsparser as
the project currently does not parse comments
- extract cross-module dependency information
- parse JsDoc comments using pyjsdoc and infer structure from code &
jsdoc
- ``ast`` CLI printing a simplified AST of the input files
- ``dependencies`` creating a dependency graph of either all modules
in the provided input files or the modules matching the specified
filters (warning: will not work if missing dependencies),
generates a .dot file
- ``extractor`` generating a plain text module documentation (mix of
rst and markdown styles, not anything formal)
* sphinx extension with an "automodule" directive taking a module name
and generating the documentation for it
Christophe Simonis