import os

import re

import shutil

import sys

from pathlib import Path

import docutils

import sphinx

from pygments.lexers import JsonLexer, XmlLexer

from sphinx.ext import graphviz

from sphinx.util import logging

_logger = logging.getLogger(__name__)

#=== General configuration ===#

# General information about the project.

project = 'Odoo'

copyright = 'Odoo S.A.'

# `version` is 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 = '18.0'

# `current_branch` is the technical name of the current branch.

# E.g., saas-15.4 -> saas-15.4; 12.0 -> 12.0, master -> master (*).

current_branch = version

# `current_version` is the Odoo version linked to the current branch.

# E.g., saas-15.4 -> 15.4; 12.0 -> 12; master -> master (*).

current_version = current_branch.replace('saas-', '').replace('.0', '')

# `current_major_branch` is the technical name of the major branch before the current branch.

# E.g., saas-15.4 -> 15.0; 12.0 -> 12.0; master -> master (*).

current_major_branch = re.sub(r'\.\d', '.0', current_branch.replace('saas-', ''))

# `current_major_version` is the Odoo version linked to the current major branch.

# E.g., saas-15.4 -> 15; 12.0 -> 12; master -> master (*).

current_major_version = current_major_branch.replace('.0', '')

# (*): We don't care for master.

# The minimal Sphinx version required to build the documentation.

needs_sphinx = '3.0.0'

# The default language in which the documentation is written. It is set to `None` because Sphinx

# considers that no language means 'en'.

language = None

# The suffix of source filenames.

source_suffix = '.rst'

# The master toctree document.

master_doc = 'index'

# List of patterns, relative to source directory, that match files and directories to ignore when

# looking for source files.

exclude_patterns = [

]

# 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'

# Whether scaled down images should be be wrapped in a `<a/>` tag linking to the image file or not.

html_scaled_image_link = False

# If true, '()' will be appended to :func: etc. cross-reference text

add_function_parentheses = True

#=== Extensions configuration ===#

source_read_replace_vals = {

}

# 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_sources_candidate_dirs = (Path('odoo'), Path('../odoo'))

odoo_sources_dirs = [

d for d in odoo_sources_candidate_dirs if d.is_dir() and (d / 'odoo-bin').exists()

]

odoo_dir_in_path = False

if not odoo_sources_dirs:

_logger.warning(

"Could not find Odoo sources directory in neither of the following folders:\n"

"%(dir_list)s\n"

"The 'Developer' documentation will be built but autodoc directives will be skipped.\n"

"In order to fully build the 'Developer' documentation, clone the repository with "

"`git clone https://github.com/odoo/odoo` or create a symbolic link.",

{'dir_list': '\n'.join([f'\t- {d.resolve()}' for d in odoo_sources_candidate_dirs])},

)

else:

if (3, 6) < sys.version_info < (3, 7):

# Running odoo needs python 3.7 min but monkey patch version_info to be compatible with 3.6.

sys.version_info = (3, 7, 0)

odoo_dir = odoo_sources_dirs[0].resolve()

source_read_replace_vals['ODOO_RELPATH'] = '/../' + str(odoo_sources_dirs[0])

sys.path.insert(0, str(odoo_dir))

import odoo.addons

odoo.addons.__path__.append(str(odoo_dir) + '/addons')

from odoo import release as odoo_release # Don't collide with Sphinx's 'release' config option

odoo_version = '.'.join(str(s) for s in odoo_release.version_info[:2]).replace('~', '-') # Change saas~XX.Y to saas-XX.Y

odoo_version = 'master' if 'alpha' in odoo_release.version else odoo_version

if release != odoo_version:

_logger.warning(

"Found Odoo sources in %(directory)s but with version '%(odoo_version)s' incompatible "

"with documentation version '%(doc_version)s'.\n"

"The 'Developer' documentation will be built but autodoc directives will be skipped.\n"

"In order to fully build the 'Developer' documentation, checkout the matching branch"

" with `cd odoo && git checkout %(doc_version)s`.",

{'directory': odoo_dir, 'odoo_version': odoo_version, 'doc_version': version},

)

else:

_logger.info(

"Found Odoo sources in %(directory)s matching documentation version '%(version)s'.",

{'directory': odoo_dir, 'version': release},

)

odoo_dir_in_path = True

if odoo_dir_in_path:

upgrade_util_dir = next(filter(Path.exists, [Path('upgrade-util'), Path('../upgrade-util')]), None)

if not upgrade_util_dir:

_logger.warning(

"Could not find Upgrade Utils sources directory in `upgrade_util`.\n"

"The developer documentation will be built but autodoc directives will be skipped.\n"

"In order to fully build the 'Developer' documentation, clone the repository with "

"`git clone https://github.com/odoo/upgrade-util` or create a symbolic link."

)

odoo_dir_in_path = False

else:

_logger.info(

"Found Upgrade Util sources in %(directory)s",

{'directory': upgrade_util_dir.resolve()},

)

from odoo import upgrade

upgrade.__path__.append(str((upgrade_util_dir / 'src').resolve()))

# Mapping between odoo models related to master data and the declaration of the

# data. This is used to point users to available xml_ids when giving values for

# a field with the autodoc_field extension.

model_references = {

}

# The Sphinx extensions to use, as module names.

# They can be extensions coming with Sphinx (named 'sphinx.ext.*') or custom ones.

extensions = [

]

if odoo_dir_in_path:

# GitHub links generation

extensions += [

'sphinx.ext.linkcode',

'github_link',

# Parse Python docstrings (autodoc, automodule, autoattribute directives)

'sphinx.ext.autodoc',

'autodoc_field',

]

else:

extensions += [

'autodoc_placeholder',

]

extensions.append('sphinx.ext.graphviz' if shutil.which('dot') else 'graphviz_placeholder')

todo_include_todos = False

intersphinx_mapping = {

}

github_user = 'odoo'

github_project = 'documentation'

locale_dirs = ['../locale/']

templates_path = ['../extensions']

# custom docname_to_domain to divide the translations of applications in subdirectories

sphinx.transforms.i18n.docname_to_domain = (

sphinx.util.i18n.docname_to_domain

) = lambda docname, compact: docname.split('/')[1 if docname.startswith('applications/') else 0]

# The version names that should be shown in the version switcher, if the config option `versions`

# is populated. If a version is passed to `versions` but is not listed here, it will not be shown.

versions_names = {

}

# The language names that should be shown in the language switcher, if the config option `languages`

# is populated. If a language is passed to `languages` but is not listed here, it will not be shown.

languages_names = {

}

# The directory in which files holding redirect rules used by the 'redirects' extension are listed.

redirects_dir = 'redirects/'

sphinx_tabs_disable_tab_closing = True

sphinx_tabs_disable_css_loading = True

# Autodoc ordering

autodoc_member_order = 'bysource'

#=== Options for HTML output ===#

html_theme = 'odoo_theme'

# The name of the Pygments (syntax highlighting) style to use.

# See extensions/odoo_theme/pygments_override.py

pygments_style = 'odoo'

# The paths that contain custom themes, relative to this directory.

html_theme_path = ['extensions']

# 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.

html_favicon = os.path.join(html_theme_path[0], html_theme, 'static', 'img', 'favicon.ico')

# 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".

html_static_path = ['static']

html_permalinks = True

# Additional JS & CSS files that can be imported with the 'custom-js' and 'custom-css' metadata.

# Lists are empty because the files are specified in extensions/themes.

html_js_files = []

html_css_files = []

# PHP lexer option to not require <?php

highlight_options = {

'php': {'startinline': True},

}

#=== Options for LaTeX output ===#

latex_elements = {

}

latex_additional_files = ['static/latex/odoo.sty']

# Grouping the document tree into LaTeX files. List of tuples:

# (source start file, target name, title, author, documentclass [howto, manual, or own class]).

latex_documents = [

]

# List of languages that have legal translations (excluding EN). The keys must be in

# `languages_names`. These translations will have a link to their versions of the legal

# contracts, instead of the default EN one. The main legal documents are not part of the

# translations since they have legal meaning.

legal_translations = ['de', 'es', 'fr', 'nl', 'pt_BR']

# 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'

# If true, show URL addresses after external links.

latex_show_urls = 'True'

# https://github.com/sphinx-doc/sphinx/issues/4054#issuecomment-329097229

def source_read_replace(app, docname, source):

source[0] = result

def setup(app):

patch(to_patch)

def _generate_alternate_urls(app, pagename, templatename, context, doctree):

_localize()