* 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
9a07a459 added "override=True" to silence a Sphinx warning in about
the address node already existing, however the override=True parameter
was added in Sphinx 1.4 (alongside the warning), so this breaks in
1.2.
Only pass in override=True if we're in 1.4 or later.
Closes#18232
* add Sphinx 1.6 compatibility (use app.set_translator when
available as in that case programmatically setting
html_translator_class is broken)
* fix a bunch of code block lexers to avoid warnings & get better
coloration
* add a few options which were referred to without being actually
defined
* fix some rST formatting
In Python 3, all of these were "consolidated" under urllib(.request,
.parse, .errors) which is inconvenient.
Since we already have hard dependencies on requests and
werkzeug(.urls, which is a backport of Python 3's unicode-aware
urllib.parse) migrate *everything* to that.
A sticking point is urllib2.URLError, those were (mostly) replaced by
the slightly more general IOError which URLError extends.
In Python 3:
* various builtins and dict methods were changed to return
view/iterable objects rather than lists
* and the separate Python 2 view/iterable builtins and methods were
removed altogether
This is problematic when using these items as list (which the happens
repeatedly in Odoo), but more viciously when iterating *multiple times*
over them (which also happens, which I've messed up multiple times while
writing this, and which is a pain to debug even when you've just created
the issue).
Convert all code using these to semantics-matching cross-version
helper functions to get the LCD behaviour between P2 and P3, and
forbid the builtins via lint.
issue #8530
Sphinx.set_translator is a Sphinx 1.3 API, and we only require Sphinx
1.2 at this point. Replace the use of set_translator with explicitly
setting the ``html_translator_class`` config setting.
* alter docstring of @api.one to mark it as deprecated for 9.0,
recommend using @api.multi instead
- deprecation notes were not correctly styled, add styling
matching "warning" alerts
* move @api.one down the doc page to deemphasize it
* fix "backend" tutorial to remove all instances of ``@api.one``
closes#8527
* remove local toc sidebar in non-index documents with a toctree
* change toctree rendering to only have links on leaf nodes (don't link
to intermediate toctree'd documents)
* fix handling of no banner (and no default banner) on documents:
- don't try to build a banner URL at the top of document
- don't build a mini-banner in cards
* fix compatibility between custom HTML translator and domains creating
new nodes (and their rendering): hook translator via
app.add_translator so app.add_node can do the job correctly: with
html_translator_class the application is not aware of the new HTML
translator and add_node can't add the relevant rendering methods
* add translation for line_block and line (classes not used, point is
just to have a div for each line so "newlines" are kept
Pretty much completely rewritten theme with custom HTML translator and a
few parts of the old theme extracted to their own extensions.
Banner images thought not to be that huge after all, and not worth the
hassle of them living in a different repository.
co-authored with @stefanorigano
Xavier Morel