Partial cherry pick of e4b75149f7
Sphinx 1.6.7 is the minimum in debian stable and ubuntu LTS
X-original-commit: 516e7854fd61c75865bb444e3614cad20283275e
Was added at 958f9106dd but lost during design change
closesodoo/odoo#42061
X-original-commit: 560dba5313c5ca5265190dacc3bce7cbe509d30a
Signed-off-by: Martin Trigaux (mat) <mat@odoo.com>
[PEP 594] is going deprecates the `imp` standard modules in
PY3.8 in order to completely remove them in PY3.10.
The `imp` module provides the `new_module` function. It returns a new
module created solely using its name. The `types.ModuleName` is a
drop-in replacement.
Task: 2003936
[PEP 594]: https://www.python.org/dev/peps/pep-0594/\#impclosesodoo/odoo#36463
Signed-off-by: Raphael Collet (rco) <rco@openerp.com>
* order of parameters to translator swapped
* context['meta'] always set, defaulting to None if the document has no
metadata
* [3.0 prep] modifying script_files deprecated, use add_javascript /
add_js_file
* remove deprecated call to l_ (which was useless anyway as the documentation
is not translated)
Fixes#33107closesodoo/odoo#33187
Signed-off-by: Xavier Morel (xmo) <xmo@odoo.com>
* 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__`.
Odoo no longer supports python 2, thus some of these helpers can and
have been replaced by python 3 built-ins, therefore there is no need for
them to stay defined.
The removed helpers are:
* izip, imap and ifilter
* unichr, text_type
* implements_to_string, implements_iterator
* string_types, integer_types
* to_native
The python 2 shims have also been removed, and only the python 3 helpers
have been kept, because they can still be usable (i.e. accepting
both bytes and str for functions that can only accept one of the two)
[REM] pyjsparser: remove PY3 shims
They're no longer necessary as Odoo doesn't officially support python 2
anymore.
closesodoo/odoo#28519
This commit replaces calls to pycompat helpers that were intended for
python 2 <-> python 3 interoperability for python 3 builtins, as python
2 is no longer officially supported by Odoo.
This includes:
* calls to imap/izip/ifilter replaced by map/zip/filter
* uses of text_type replaced by str
* uses of unichr replaced by chr
* calls to implements_to_string, implements_iterator removed
* string_types and integer_types replaced by str, int respectively
* calls to to_native replaced by calls to to_text
This is done in preparation to the removal of these deprecated helpers
in the following commit.
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)
Odoo 11 is python 3 but the xmlrpc interface works with python 2 too.
The example should probably be migrated to use python 3.
In the meantime specify exactly these examples are python 2 to avoid the
confusion.
Fixes#24232
Also when there is both a docstring and directive-level content put
the docstring first. That seems to match what Sphinx's autodoc does
and looks less odd.
Possible future improvement: a parameter to suppress the docstring?
Possibly a way to reorder the non-docstring content (e.g. members
documentation)?
Remove wrong slash trailing
Now, in V11, matching of page are done on the exact name.
Previously, the error was transparent because we was using a
dedicated controller that allow trailing slash.
https://github.com/odoo/odoo/blob/11.0/odoo/http.py#L936https://webmasters.googleblog.com/2010/04/to-slash-or-not-to-slash.htmlhttp://example.com/foo/ (with trailing slash, conventionally a directory)
http://example.com/foo (without trailing slash, conventionally a file)
Google treats each URL above separately (and equally) regardless of
whether it’s a file or a directory, or it contains a trailing slash or
it doesn’t contain a trailing slash.
Different content on / and no-/ URLs okay for Google, often less ideal for users
Special case for homepage
Rest assured that for your root URL specifically,
http://example.com is equivalent to
http://example.com/ and can’t be redirected even if you’re Chuck Norris.
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.
A comprehensive theme’s revamp, details:
=== New features ===
- Show titles permalink markers on hover
- “Scrollspy” effect for the sidebar
=== Fixes ===
- Solve an issue causing the sidebar to flicker on scroll
- Hide the sidebar if less then two links
=== Design ===
- Improve typography vertical rhythm and line height
- Visually increase separation between sections
- Review alerts and <dl> design
- Reduce cover’s size
- Reduce overall paddings/margins.
Closes#21304
* [ADD] doc: iap tutorial
Should be easier to approach than the raw APIDoc.
contains:
- overview of the flow
- tutorial (coalroller) with guidelines
- technical description of objects/helpers
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 Sphinx 1.6 compatibility leading to the "tiles" on the home page
not working anymore: 1.6 replaces BuildEnvironment.reolve_toctree by
TocTree().resolve(), while the method still exists it's not actually
called anymore
* rejigger some CSS as the second section went from one big tile to 3
smaller tiles, and got laid out as a row rather than a second 2x2
block. Recode the entire mess with flexbox, remove some stuff which
conflicted with boostrap (this screen should probably be
de-boostrapped and completely converted to flexbox or grid)
* add building CSS from LESS to the makefile, all Odoo devs should
have less installed locally (for assets)
* 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
IAP allow app publishers to charge for ongoing services. In that context, Odoo
acts mostly as a payment platform between the service user (client) and the service
provider (Odoo App developer).
* 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
* remove references to basestring & unicode (use relevant pycompat
helpers)
* remove some str calls (either entirely or replaced by relevant
helper, either text or native)
* use better API to avoid unnecessary conversions
* remove some XML declarations in views
fw-bot