2021-02-19 17:24:35 +07:00
import os
2021-01-29 01:05:48 +07:00
import sys
from pathlib import Path
2021-03-25 18:45:07 +07:00
from pygments . lexers import JsonLexer , XmlLexer
2021-01-29 01:05:48 +07:00
from sphinx . util import logging
_logger = logging . getLogger ( __name__ )
2021-01-29 15:27:18 +07:00
#=== General configuration ===#
2021-02-01 14:58:35 +07:00
# General information about the project.
2021-04-01 19:05:47 +07:00
project = ' Odoo '
2021-02-01 14:58:35 +07:00
copyright = ' Odoo S.A. '
2021-01-29 17:35:31 +07:00
# `version` if the version info for the project being documented, acts as replacement for |version|,
# also used in various other places throughout the built documents.
# `release` is the full version, including alpha/beta/rc tags. Acts as replacement for |release|.
version = release = ' 12.0 '
2021-01-29 15:27:18 +07:00
# The minimal Sphinx version required to build the documentation.
needs_sphinx = ' 3.0.0 '
2021-04-01 19:05:47 +07:00
# The default language in which the documentation is written. It is set to `None` because Sphinx
2021-02-01 14:58:35 +07:00
# considers that no language means 'en'.
language = None
2021-01-29 15:27:18 +07:00
# The suffix of source filenames.
source_suffix = ' .rst '
# The master toctree document.
2021-03-10 22:05:57 +07:00
master_doc = ' index '
2021-01-29 15:27:18 +07:00
# List of patterns, relative to source directory, that match files and directories to ignore when
# looking for source files.
exclude_patterns = [
' locale ' ,
' README.* ' ,
' bin ' , ' include ' , ' lib ' ,
2021-03-10 21:13:47 +07:00
' odoo ' ,
2021-01-29 15:27:18 +07:00
]
# The RST text role to use when the role is not specified. E.g.: `example`.
# We use 'literal' as default role for markdown compatibility: `foo` behaves like ``foo``.
# See https://docutils.sourceforge.io/docs/ref/rst/roles.html#standard-roles for other roles.
default_role = ' literal '
2021-01-29 17:35:31 +07:00
# If true, '()' will be appended to :func: etc. cross-reference text
2021-01-29 15:27:18 +07:00
add_function_parentheses = True
#=== Extensions configuration ===#
2021-01-29 01:05:48 +07:00
# Add extensions directory to PYTHONPATH
extension_dir = Path ( ' extensions ' )
sys . path . insert ( 0 , str ( extension_dir . absolute ( ) ) )
# Search for the directory of odoo sources to know whether autodoc should be used on the dev doc
odoo_dir = Path ( ' odoo ' )
2021-01-29 17:35:31 +07:00
odoo_dir_in_path = False
if not odoo_dir . is_dir ( ) :
2021-01-29 01:05:48 +07:00
_logger . warning (
f " Could not find Odoo sources directory at { odoo_dir . absolute ( ) } . \n "
2021-01-29 17:35:31 +07:00
f " The ' Developer ' documentation will be built but autodoc directives will be skipped. \n "
f " In order to fully build the ' Developer ' documentation, clone the repository with "
f " `git clone https://github.com/odoo/odoo` or create a symbolink link. "
2021-01-29 01:05:48 +07:00
)
2021-01-29 17:35:31 +07:00
else :
sys . path . insert ( 0 , str ( odoo_dir . absolute ( ) ) )
from odoo import release as odoo_release # Don't collide with Sphinx's 'release' config option
2021-04-01 19:24:00 +07:00
odoo_version = odoo_release . version if ' alpha ' not in odoo_release . version else ' master '
if release != odoo_version :
2021-01-29 17:35:31 +07:00
_logger . warning (
2021-04-01 19:24:00 +07:00
f " Found Odoo sources directory but with version ' { odoo_version } ' incompatible with "
f " documentation version ' { version } ' . \n "
2021-01-29 17:35:31 +07:00
f " The ' Developer ' documentation will be built but autodoc directives will be skipped. \n "
f " In order to fully build the ' Developer ' documentation, checkout the matching branch "
f " with `cd odoo && git checkout { version } `. "
)
else :
_logger . info ( f " Found Odoo sources directory matching documentation version { release } . " )
odoo_dir_in_path = True
2021-01-29 01:05:48 +07:00
# The Sphinx extensions to use, as module names.
# They can be extensions coming with Sphinx (named 'sphinx.ext.*') or custom ones.
2015-02-11 15:22:56 +07:00
extensions = [
2021-01-29 01:05:48 +07:00
# Parse Python docstrings (autodoc, automodule, autoattribute directives)
' sphinx.ext.autodoc ' if odoo_dir_in_path else ' autodoc_placeholder ' ,
# Link sources in other projects (used to build the reference doc)
' sphinx.ext.intersphinx ' ,
# Support the specialized to-do directives
2015-02-11 15:22:56 +07:00
' sphinx.ext.todo ' ,
2021-01-29 01:05:48 +07:00
# GitHub links generation
' sphinx.ext.linkcode ' ,
2020-04-01 22:00:52 +07:00
' github_link ' ,
2021-01-29 01:05:48 +07:00
# Custom Odoo theme
' odoo_theme ' ,
# Youtube and Vimeo videos integration (youtube, vimeo directives)
' embedded_video ' ,
' exercise_admonition ' ,
# Build code from git patches
' patchqueue ' ,
# Redirection generator
2020-04-01 22:00:52 +07:00
' redirects ' ,
2021-01-29 17:32:30 +07:00
# Code switcher (switcher and case directives)
' switcher ' ,
# Strange html domain logic used in memento pages
' html_domain ' ,
2015-02-11 15:22:56 +07:00
]
2021-01-29 15:27:18 +07:00
todo_include_todos = False
2015-02-11 15:22:56 +07:00
2021-01-29 15:27:18 +07:00
intersphinx_mapping = {
' python ' : ( ' https://docs.python.org/3/ ' , None ) ,
' werkzeug ' : ( ' https://werkzeug.palletsprojects.com/en/1.0.x/ ' , None ) ,
}
2015-02-11 15:22:56 +07:00
2021-01-29 15:27:18 +07:00
github_user = ' odoo '
2021-04-01 19:05:47 +07:00
github_project = ' documentation '
2015-02-11 15:22:56 +07:00
2021-01-29 15:27:18 +07:00
locale_dirs = [ ' locale/ ' ]
2021-02-01 14:58:35 +07:00
supported_languages = {
2021-03-11 00:46:20 +07:00
' de ' : ' Deutsch ' ,
2021-01-29 15:27:18 +07:00
' en ' : ' English ' ,
2021-03-22 17:58:15 +07:00
' es ' : ' Español ' ,
2021-03-11 00:46:20 +07:00
' fr ' : ' Français ' ,
' nl ' : ' Nederlands ' ,
' pt_BR ' : ' Português (BR) ' ,
2021-03-22 17:58:15 +07:00
' uk ' : ' українська ' ,
' zh_CN ' : ' 简体中文 ' ,
2021-01-29 15:27:18 +07:00
}
2015-02-11 15:22:56 +07:00
2021-01-29 01:05:48 +07:00
# The specifications of redirect rules used by the redirects extension.
2021-03-10 20:34:01 +07:00
redirects_file = ' redirects.txt '
2021-01-29 01:05:48 +07:00
#=== Options for HTML output ===#
2015-02-11 15:22:56 +07:00
2021-01-29 01:05:48 +07:00
html_theme = ' odoo_theme '
2015-02-11 15:22:56 +07:00
# The name of the Pygments (syntax highlighting) style to use.
2021-02-16 22:13:45 +07:00
pygments_style = ' odoo '
2015-02-11 15:22:56 +07:00
2021-04-01 19:05:47 +07:00
# The paths that contain custom themes, relative to this directory.
2021-01-29 01:05:48 +07:00
html_theme_path = [ ' extensions ' ]
2015-02-11 15:22:56 +07:00
2021-04-01 19:05:47 +07:00
# The name of an image file (within the static path) to use as favicon of the docs.
# This file should be a Windows icon file (.ico) being 16x16 or 32x32 pixels large.
2021-02-19 17:24:35 +07:00
html_favicon = os . path . join ( html_theme_path [ 0 ] , html_theme , ' static ' , ' img ' , ' favicon.ico ' )
2015-02-11 15:22:56 +07:00
2021-04-01 19:05:47 +07:00
# The paths that contain custom static files, relative to this directory.
# They are copied after the builtin static files, so a file named "default.css" will overwrite the
# builtin "default.css".
2021-01-29 01:05:48 +07:00
html_static_path = [ ' static ' ]
2021-01-29 03:02:32 +07:00
html_add_permalinks = ' ¶ ' # Sphinx < 3.5
html_permalinks = True # Sphinx >= 3.5
2021-04-02 22:25:04 +07:00
# The page-specific js files that can be imported with the 'custom-js' metadata directive. TODO VFE does it act as a filter? Why are there already some imports not listed here?
2021-03-19 00:27:50 +07:00
html_js_files = [ ]
2021-04-02 22:25:04 +07:00
# The page-specific css files that can be imported with the 'custom-css' metadata directive. TODO VFE does it act as a filter? Why are there already some imports not listed here?
2021-03-19 00:27:50 +07:00
html_css_files = [ ]
2015-02-11 15:22:56 +07:00
2021-03-25 18:45:07 +07:00
# PHP lexer option to not require <?php
highlight_options = {
' php ' : { ' startinline ' : True } ,
}
2021-01-29 15:27:18 +07:00
2021-01-29 01:05:48 +07:00
#=== Options for LaTeX output ===#
2015-02-11 15:22:56 +07:00
latex_elements = {
2021-01-29 01:05:48 +07:00
# The paper size ('letterpaper' or 'a4paper').
' papersize ' : ' a4paper ' ,
2016-02-15 23:56:38 +07:00
2021-01-29 01:05:48 +07:00
# Additional stuff for the LaTeX preamble.
' preamble ' : r ' \ usepackage {odoo} ' ,
' tableofcontents ' : ' ' , # no TOC
2015-02-11 15:22:56 +07:00
2021-04-01 19:05:47 +07:00
# Output manually in latex docs
2021-01-29 01:05:48 +07:00
' releasename ' : ' 14.0 ' ,
2015-02-11 15:22:56 +07:00
}
2021-01-29 01:05:48 +07:00
latex_additional_files = [ ' static/latex/odoo.sty ' ]
2016-02-15 23:56:38 +07:00
2021-04-01 19:05:47 +07:00
# Grouping the document tree into LaTeX files. List of tuples:
2021-01-29 01:05:48 +07:00
# (source start file, target name, title, author, documentclass [howto, manual, or own class]).
2015-02-11 15:22:56 +07:00
latex_documents = [
2021-03-18 22:33:10 +07:00
( ' legal/terms/enterprise_tex ' , ' odoo_enterprise_agreement.tex ' ,
2021-01-29 01:05:48 +07:00
' Odoo Enterprise Subscription Agreement ' , ' ' , ' howto ' ) ,
2021-03-18 22:33:10 +07:00
( ' legal/terms/partnership_tex ' ,
2021-01-29 15:27:18 +07:00
' odoo_partnership_agreement.tex ' , ' Odoo Partnership Agreement ' , ' ' , ' howto ' ) ,
2021-03-18 22:33:10 +07:00
( ' legal/terms/terms_of_sale ' ,
2021-01-29 15:27:18 +07:00
' terms_of_sale.tex ' , ' Odoo Terms of Sale ' , ' ' , ' howto ' ) ,
2021-01-29 01:05:48 +07:00
2021-03-18 22:33:10 +07:00
( ' legal/terms/i18n/enterprise_tex_fr ' , ' odoo_enterprise_agreement_fr.tex ' ,
2021-01-29 15:27:18 +07:00
' Odoo Enterprise Subscription Agreement (FR) ' , ' ' , ' howto ' ) ,
2021-03-18 22:33:10 +07:00
( ' legal/terms/i18n/partnership_tex_fr ' ,
2021-01-29 15:27:18 +07:00
' odoo_partnership_agreement_fr.tex ' , ' Odoo Partnership Agreement (FR) ' , ' ' , ' howto ' ) ,
2021-03-18 22:33:10 +07:00
( ' legal/terms/i18n/terms_of_sale_fr ' , ' terms_of_sale_fr.tex ' ,
2021-01-29 15:27:18 +07:00
u ' Conditions Générales de Vente Odoo ' , ' ' , ' howto ' ) ,
2021-01-29 01:05:48 +07:00
2021-03-18 22:33:10 +07:00
( ' legal/terms/i18n/enterprise_tex_nl ' , ' odoo_enterprise_agreement_nl.tex ' ,
2021-01-29 15:27:18 +07:00
' Odoo Enterprise Subscription Agreement (NL) ' , ' ' , ' howto ' ) ,
2021-01-29 01:05:48 +07:00
2021-03-18 22:33:10 +07:00
( ' legal/terms/i18n/enterprise_tex_de ' , ' odoo_enterprise_agreement_de.tex ' ,
2021-01-29 15:27:18 +07:00
' Odoo Enterprise Subscription Agreement (DE) ' , ' ' , ' howto ' ) ,
2021-01-29 01:05:48 +07:00
2021-03-18 22:33:10 +07:00
( ' legal/terms/i18n/enterprise_tex_es ' , ' odoo_enterprise_agreement_es.tex ' ,
2021-01-29 15:27:18 +07:00
' Odoo Enterprise Subscription Agreement (ES) ' , ' ' , ' howto ' ) ,
2021-03-18 22:33:10 +07:00
( ' legal/terms/i18n/partnership_tex_es ' ,
2021-01-29 15:27:18 +07:00
' odoo_partnership_agreement_es.tex ' , ' Odoo Partnership Agreement (ES) ' , ' ' , ' howto ' ) ,
2015-02-11 15:22:56 +07:00
]
2021-01-29 01:05:48 +07:00
# The name of an image file (relative to this directory) to place at the top of the title page.
latex_logo = ' static/img/odoo_logo.png '
2015-02-11 15:22:56 +07:00
# If true, show URL addresses after external links.
2021-02-01 14:58:35 +07:00
latex_show_urls = ' True '
2015-02-11 15:22:56 +07:00
2015-11-03 17:32:49 +07:00
2015-02-11 15:22:56 +07:00
def setup ( app ) :
2021-02-01 14:58:35 +07:00
# Generate all alternate URLs for each document
app . add_config_value ( ' project_root ' , None , ' env ' )
app . add_config_value ( ' canonical_version ' , None , ' env ' )
app . add_config_value ( ' versions ' , None , ' env ' )
app . add_config_value ( ' languages ' , None , ' env ' )
2021-03-25 18:45:07 +07:00
2021-04-01 19:09:03 +07:00
app . add_lexer ( ' json ' , JsonLexer )
app . add_lexer ( ' xml ' , XmlLexer )
2021-03-25 18:45:07 +07:00
2021-02-01 14:58:35 +07:00
app . connect ( ' html-page-context ' , _generate_alternate_urls )
2018-10-29 21:19:12 +07:00
2021-01-29 01:05:48 +07:00
2021-02-01 14:58:35 +07:00
def _generate_alternate_urls ( app , pagename , templatename , context , doctree ) :
""" Add keys of required alternate URLs for the current document in the rendering context.
2021-01-29 01:05:48 +07:00
2021-02-01 14:58:35 +07:00
Alternate URLS are required for :
- The canonical link tag
- The version switcher
- The language switcher and related link tags
2018-10-29 21:19:12 +07:00
"""
2021-02-01 14:58:35 +07:00
def _canonicalize ( ) :
""" Add the canonical URL for the current document in the rendering context.
The canonical version is the last released version of the documentation .
For a given language , the canonical root of a page is in the same language so that web
searches in that language don ' t redirect users to the english version of that page.
E . g . :
- / documentation / sale . html - > canonical = / documentation / 14.0 / sale . html
- / documentation / 11.0 / fr / website . html - > canonical = / documentation / 14.0 / fr / website . html
"""
# If the canonical version is not set, assume that the project has a single version
2021-02-04 21:06:13 +07:00
_canonical_version = app . config . canonical_version or app . config . version
2021-02-01 14:58:35 +07:00
_canonical_lang = ' en ' # Always 'en'. Don't take the value of the config option.
context [ ' canonical ' ] = _build_url ( _version = _canonical_version , _lang = _canonical_lang )
def _versionize ( ) :
""" Add the pairs of (version, url) for the current document in the rendering context.
The entry ' version ' is added by Sphinx in the rendering context .
"""
# If the list of versions is not set, assume that the project has no alternate version
_alternate_versions = app . config . versions and app . config . versions . split ( ' , ' ) or [ ]
context [ ' alternate_versions ' ] = [
( _alternate_version , _build_url ( _version = _alternate_version ) )
2021-03-10 23:24:48 +07:00
for _alternate_version in sorted ( _alternate_versions , reverse = True )
if _alternate_version != version and (
_alternate_version != ' master ' or pagename . startswith ( ' developer ' )
)
2021-02-01 14:58:35 +07:00
]
def _localize ( ) :
2021-04-01 19:05:47 +07:00
""" Add the pairs of (lang, code, url) for the current document in the rendering context.
2021-02-01 14:58:35 +07:00
2021-04-01 19:05:47 +07:00
E . g . : ( ' French ' , ' fr ' , ' https://.../fr_BE/... ' )
2021-02-01 14:58:35 +07:00
2021-04-01 19:05:47 +07:00
The entry ' language ' is added by Sphinx in the rendering context .
2021-02-01 14:58:35 +07:00
"""
_current_lang = app . config . language or ' en '
# Replace the context value by its translated description ("Français" instead of "french")
context [ ' language ' ] = supported_languages . get ( _current_lang )
# If the list of languages is not set, assume that the project has no alternate language
_alternate_languages = app . config . languages and app . config . languages . split ( ' , ' ) or [ ]
context [ ' alternate_languages ' ] = [
(
supported_languages . get ( _alternate_lang ) ,
_alternate_lang . split ( ' _ ' ) [ 0 ] if _alternate_lang != ' en ' else ' x-default ' ,
_build_url ( _lang = _alternate_lang ) ,
)
for _alternate_lang in _alternate_languages
if _alternate_lang in supported_languages and _alternate_lang != _current_lang
]
def _build_url ( _version = None , _lang = None ) :
_root = app . config . project_root or str ( Path ( __file__ ) . parent )
2021-02-04 21:06:13 +07:00
_version = _version or app . config . version
2021-02-01 14:58:35 +07:00
_lang = _lang or app . config . language or ' en '
_canonical_page = ( pagename + ' .html ' ) . replace ( ' index.html ' , ' ' ) . replace ( ' index/ ' , ' ' )
return f ' { _root } / { _version } { f " / { _lang } " if _lang != " en " else " " } / { _canonical_page } '
_canonicalize ( )
_versionize ( )
_localize ( )