xref: /DragonOS/docs/conf.py (revision 55e6f0b65f91b32638fd56581f711a816eccdcd1) 
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# https://www.sphinx-doc.org/en/master/usage/configuration.html
6
7# -- Path setup --------------------------------------------------------------
8
9# If extensions (or modules to document with autodoc) are in another directory,
10# add these directories to sys.path here. If the directory is relative to the
11# documentation root, use os.path.abspath to make it absolute, like shown here.
12#
13import os
14# import sys
15# sys.path.insert(0, os.path.abspath('.'))
16
17# -- Project information -----------------------------------------------------
18
19project = 'DragonOS'
20copyright = '2022-2024, DragonOS Community'
21author = 'longjin'
22github_org = 'DragonOS-Community'
23github_repo = 'DragonOS'
24
25# The full version, including alpha/beta/rc tags
26release = 'dev'
27
28
29# -- General configuration ---------------------------------------------------
30
31# Add any Sphinx extension module names here, as strings. They can be
32# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
33# ones.
34extensions = ['myst_parser', 'sphinx_multiversion']
35
36# Add any paths that contain templates here, relative to this directory.
37templates_path = ['_templates']
38
39# The language for content autogenerated by Sphinx. Refer to documentation
40# for a list of supported languages.
41#
42# This is also used if you do content translation via gettext catalogs.
43# Usually you set "language" from the command line for these cases.
44language = 'zh_CN'
45
46# List of patterns, relative to source directory, that match files and
47# directories to ignore when looking for source files.
48# This pattern also affects html_static_path and html_extra_path.
49exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
50source_suffix = ['.rst', '.md']
51
52# -- Options for HTML output -------------------------------------------------
53
54# The theme to use for HTML and HTML Help pages.  See the documentation for
55# a list of builtin themes.
56#
57html_theme = 'sphinx_rtd_theme'
58
59html_context = dict()
60
61# Add any paths that contain custom static files (such as style sheets) here,
62# relative to this directory. They are copied after the builtin static files,
63# so a file named "default.css" will overwrite the builtin "default.css".
64html_static_path = ['_static']
65
66html_sidebars = {
67    '**': [
68        'versioning.html',
69    ],
70}
71
72myst_enable_extensions = [
73    "amsmath",
74    "colon_fence",
75    "deflist",
76    "dollarmath",
77    "fieldlist",
78    "html_admonition",
79    "html_image",
80    "replacements",
81    "smartquotes",
82    "strikethrough",
83    "substitution",
84    "tasklist",
85]
86
87# sphinx-multiversion 指定哪个分支为 lastest 版本
88smv_latest_version = 'master'
89smv_released_pattern = r'^tags/.*$'           # Tags only
90smv_tag_whitelist = r'^(V.*|v.*)$'
91smv_branch_whitelist = "master"
92
93# Define the canonical URL if you are using a custom domain on Read the Docs
94html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
95
96# Tell Jinja2 templates the build is running on Read the Docs
97if os.environ.get("READTHEDOCS", "") == "True":
98    html_context["READTHEDOCS"] = True
99
100if os.environ.get("SPHINX_MULTIVERSION_GIT_COMMIT", "") != "":
101    html_context["commit"] = os.environ["SPHINX_MULTIVERSION_GIT_COMMIT"]
102elif os.environ.get("CURRENT_GIT_COMMIT_HASH", "") != "":
103    html_context["commit"] = os.environ["CURRENT_GIT_COMMIT_HASH"]
104
105
106# 截取前 7 位 commit hash，如果长度不足则不截取
107if "commit" in html_context:
108    html_context["commit"] = html_context["commit"][:7]
109    if os.environ.get("CURRENT_GIT_COMMIT_DIRTY", "") == "1":
110        html_context["commit"] += "-dirty"
111
112
113# -- Set GitHub URL for Edit on GitHub links ---
114html_context['display_github'] = True
115html_context['github_user'] = github_org
116html_context['github_repo'] = github_repo
117html_context['github_version'] = html_context['commit'] if 'commit' in html_context else 'master'
118html_context['conf_py_path'] = '/docs/'
119