1# Configuration file for the Sphinx documentation builder.
2#
3# This file only contains a selection of the most common options. For a full
4# list see the documentation:
5# http://www.sphinx-doc.org/en/master/config
6# -- Path setup --------------------------------------------------------------
7# If extensions (or modules to document with autodoc) are in another directory,
8# add these directories to sys.path here. If the directory is relative to the
9# documentation root, use os.path.abspath to make it absolute, like shown here.
10#
11# import os
12# import sys
13# sys.path.insert(0, os.path.abspath('.'))
14#
15# Modeles de fichiers conf.py
16# ============================
17#
18# - https://github.com/bashtage/sphinx-material/blob/master/docs/conf.py
19# - https://github.com/bashtage/arch/blob/main/doc/source/conf.py
20# - https://github.com/statsmodels/statsmodels/blob/main/docs/source/conf.py
21#
22# theme.conf
23# ===========
24# - https://github.com/bashtage/sphinx-material/blob/master/sphinx_material/sphinx_material/theme.conf
25#
26import platform
27from datetime import datetime
28from zoneinfo import ZoneInfo
29
30import sphinx
31import sphinx_material
32
33project = "Demo sphinx-material theme"
34html_title = project
35html_short_title = project
36author = "id3 Technologies"
37html_logo = "images/sphinx_avatar.png"
38html_favicon = "images/sphinx_avatar.png"
39now = datetime.now(tz=ZoneInfo("Europe/Paris"))
40master_doc = "index"
41version = "0.1.0"
42release = version
43today = f"{now.year}-{now.month:02}-{now.day:02} {now.hour:02}H ({now.tzinfo})"
44source_suffix = ".rst"
45language = None
46exclude_patterns = ["_build", ".venv", ".git"]
47
48extensions = [
49 "sphinx.ext.extlinks",
50 "sphinx.ext.intersphinx",
51 "sphinx.ext.todo",
52 "sphinx.ext.viewcode",
53 "sphinx_copybutton",
54]
55
56# https://www.sphinx-doc.org/en/master/usage/markdown.html
57extensions.append("myst_parser")
58# https://sphinx-design.readthedocs.io/en/furo-theme/get_started.html
59myst_enable_extensions = [
60 "amsmath",
61 "attrs_inline",
62 "colon_fence",
63 "deflist",
64 "dollarmath",
65 "fieldlist",
66 "html_admonition",
67 "html_image",
68 # "linkify",
69 "replacements",
70 "smartquotes",
71 "strikethrough",
72 "substitution",
73 "tasklist",
74]
75source_suffix = {
76 ".rst": "restructuredtext",
77 ".md": "markdown",
78}
79
80# https://sphinx-design.readthedocs.io/en/furo-theme/get_started.html
81extensions.append("sphinx_design")
82
83# https://sphinx-subfigure.readthedocs.io/en/latest/#usage
84extensions.append("sphinx_subfigure")
85numfig = True
86
87# https://sphinxcontrib-youtube.readthedocs.io/en/latest/usage.html#configuration
88extensions.append("sphinxcontrib.youtube")
89
90
91# Add any paths that contain templates here, relative to this directory.
92templates_path = ["_templates"]
93exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
94html_static_path = ["_static"]
95html_show_sourcelink = True
96html_sidebars = {
97 "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
98}
99extensions.append("sphinx_material")
100html_theme_path = sphinx_material.html_theme_path()
101html_context = sphinx_material.get_html_context()
102html_theme = "sphinx_material"
103
104# __begin_intersphinx_mapping__
105extensions.append("sphinx.ext.intersphinx")
106intersphinx_mapping = {
107 "tuto_doc": ("https://gdevops.frama.io/documentation/tuto", None),
108 "doc_news": ("https://gdevops.frama.io/documentation/news", None),
109 "tuto_sphinx": ("https://gdevops.frama.io/documentation/sphinx/tuto", None),
110 "tuto_formats": ("https://gdevops.frama.io/documentation/formats", None),
111 "tuto_python": ("https://gdevops.frama.io/python/tuto", None),
112 "ray": ("https://docs.ray.io/en/latest/", None),
113 "sphinx_doc": ("https://www.sphinx-doc.org/en/master/", None),
114}
115# python -m sphinx.ext.intersphinx http://informatique.gitlab.srv.int.id3.eu/Documentation/objects.inv
116# python -m sphinx.ext.intersphinx https://informatique.gitlab.srv.int.id3.eu/intranet/intranet_user/objects.inv
117# python -m sphinx.ext.intersphinx https://docs.ray.io/en/latest/objects.inv
118# python -m sphinx.ext.intersphinx https://www.sphinx-doc.org/en/master/objects.inv
119# __end_intersphinx_mapping__
120
121extensions.append("sphinx.ext.todo")
122todo_include_todos = True
123
124# material theme options (see theme.conf for more information)
125# https://github.com/bashtage/sphinx-material/blob/master/sphinx_material/sphinx_material/theme.conf
126# Colors
127# The theme color for mobile browsers. Hex color.
128# theme_color = #3f51b5
129# Primary colors:
130# red, pink, purple, deep-purple, indigo, blue, light-blue, cyan,
131# teal, green, light-green, lime, yellow, amber, orange, deep-orange,
132# brown, grey, blue-grey, white
133# Accent colors:
134# red, pink, purple, deep-purple, indigo, blue, light-blue, cyan,
135# teal, green, light-green, lime, yellow, amber, orange, deep-orange
136# color_accent = blue
137# color_primary = blue-grey
138
139html_theme_options = {
140 "base_url": "https://gdevops.frama.io/documentation/sphinx-demos",
141 "repo_url": "https://gitlab.com/gdevops/documentation/sphinx-demos",
142 "repo_name": project,
143 "repo_type": "gitlab",
144 "html_minify": False,
145 "html_prettify": False,
146 "css_minify": False,
147 "globaltoc_depth": -1,
148 # https://www.colorhexa.com/2173f3
149 "theme_color": "#a121f3",
150 "color_primary": "indigo",
151 "color_accent": "blue",
152 "master_doc": False,
153 "nav_title": f"{project} {release} ({today})",
154 "nav_links": [
155 {
156 "href": "genindex",
157 "internal": True,
158 "title": "Index",
159 },
160 {
161 "href": "https://gdevops.frama.io/documentation/linkertree",
162 "internal": False,
163 "title": "Liens documentation",
164 },
165 ],
166 "heroes": {
167 "index": "Demo sphinx-material theme",
168 },
169 "table_classes": ["plain"],
170 # "use_sidenotes": True, # L'option 'use_sidenotes' n'est pas supportée pour ce thème
171}
172# https://github.com/sphinx-contrib/yasfb
173extensions.append("yasfb")
174feed_base_url = html_theme_options["base_url"]
175feed_author = "Scribe"
176# https://sphinx-design.readthedocs.io/en/furo-theme/get_started.html
177extensions.append("sphinx_design")
178# https://sphinx-tags.readthedocs.io/en/latest/quickstart.html#installation
179extensions.append("sphinx_tags")
180tags_create_tags = True
181# Whether to display tags using sphinx-design badges.
182tags_create_badges = True
183
184
185language = "fr"
186html_last_updated_fmt = ""
187todo_include_todos = True
188
189html_use_index = True
190html_domain_indices = True
191
192
193def setup(app):
194 # pour utiliser :confval:`html_show_sourcelink`
195 app.add_object_type(
196 "confval",
197 "confval",
198 objname="configuration value",
199 indextemplate="pair: %s; configuration value",
200 )
201
202
203html_static_path = ["_static"]
204html_css_files = ["custom.css"]
205
206
207copyright = f"2023-{now.year}, {author} Built with sphinx {sphinx.__version__} Python {platform.python_version()}"
208
209# en général les images avatar font 64x64
210rst_prolog = """
211.. |sphinx| image:: /images/sphinx_avatar.png
212.. |myst| image:: /images/myst_avatar.png
213.. |breathe| image:: /images/breathe_avatar.png
214.. |doxygen| image:: /images/doxygen_avatar.png
215.. |eb| image:: /images/executable_book_avatar.png
216.. |vrt| image:: /images/vrt_avatar.png
217.. |yed| image:: /images/yed_avatar.png
218.. |arsouilles| image:: /images/arsouilles_avatar.png
219.. |FluxWeb| image:: /images/rss_avatar.webp
220"""