257 lines
8.0 KiB
Python
257 lines
8.0 KiB
Python
# Configuration file for the Sphinx documentation builder.
|
||
#
|
||
# For the full list of built-in configuration values, see the documentation:
|
||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||
|
||
# -- Project information -----------------------------------------------------
|
||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||
|
||
import os
|
||
import os.path
|
||
import subprocess
|
||
import shutil
|
||
import re
|
||
import sys
|
||
import datetime
|
||
from pathlib import Path
|
||
import sphinx_rtd_theme
|
||
|
||
SDK_BASE = Path(__file__).resolve().parents[2]
|
||
HTML_STATIC_DIR = Path(__file__).resolve().parents[0] / "_static"
|
||
HTML_ASSETS_DIR = Path(__file__).resolve().parents[1] / "assets"
|
||
DOXY_OUT = Path(__file__).resolve().parents[0] / "_static" / "api_doc"
|
||
|
||
sys.path.insert(0, str(SDK_BASE / "docs" / "_ext"))
|
||
|
||
os.environ["SDK_BASE"] = str(SDK_BASE)
|
||
project = 'Arcs Software Development Kit'
|
||
copyright = '2020-%s, LISTENAI' % datetime.date.today().year
|
||
author = '聆思科技固件组'
|
||
|
||
# -- General configuration ---------------------------------------------------
|
||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
|
||
|
||
extensions = [
|
||
'sphinx_rtd_theme',
|
||
'myst_parser',
|
||
"sphinx.ext.todo",
|
||
"sphinx.ext.extlinks",
|
||
'sphinx.ext.duration',
|
||
"sphinx.ext.viewcode",
|
||
'sphinxcontrib.moderncmakedomain',
|
||
"external_content",
|
||
"doxyrunner",
|
||
"sphinx_tabs.tabs",
|
||
"source_link" # 自动添加源码链接
|
||
]
|
||
|
||
templates_path = ['_templates']
|
||
|
||
DOXY_OUT.mkdir(parents = True, exist_ok = True)
|
||
doxyrunner_doxygen = os.environ.get("DOXYGEN_EXECUTABLE", "doxygen")
|
||
doxyrunner_doxyfile = SDK_BASE / "docs" / "doxygen" / "Doxyfile"
|
||
doxyrunner_outdir = DOXY_OUT
|
||
doxyrunner_fmt = True
|
||
doxyrunner_fmt_vars = {"SDK_BASE": str(SDK_BASE)}
|
||
doxyrunner_outdir_var = "DOXYGEN_OUTPUT_DIR"
|
||
|
||
# List of patterns, relative to source directory, that match files and
|
||
# directories to ignore when looking for source files.
|
||
# This pattern also affects html_static_path and html_extra_path.
|
||
exclude_patterns = [
|
||
# 示例章节文件（sample_build.rst, sample_flash.rst）仅用于 include，不作为独立页面
|
||
"sample_build.rst",
|
||
"sample_flash.rst",
|
||
]
|
||
html_extra_path = []
|
||
|
||
source_suffix = {
|
||
'.rst': 'restructuredtext',
|
||
'.md': 'markdown',
|
||
}
|
||
|
||
external_content_contents = [
|
||
(SDK_BASE, "docs/*.rst"),
|
||
(SDK_BASE, "CHANGELOG.md"),
|
||
(SDK_BASE / "docs/zh", "[!_]*"),
|
||
(SDK_BASE, "drivers/**/*.rst"),
|
||
(SDK_BASE, "drivers/**/*.md"),
|
||
(SDK_BASE, "boards/*.rst"),
|
||
(SDK_BASE, "boards/**/*.md"),
|
||
(SDK_BASE, "components/**/*.rst"),
|
||
(SDK_BASE, "components/**/*.md"),
|
||
(SDK_BASE, "samples/**/*.rst"),
|
||
(SDK_BASE, "samples/**/*.md"),
|
||
(SDK_BASE, "demos/**/*.rst"),
|
||
(SDK_BASE, "demos/**/*.md"),
|
||
(SDK_BASE, "tools/**/*.rst"),
|
||
(SDK_BASE, "tools/**/*.md"),
|
||
## modules目录下存在很多不规范的README.md，指定添加构建目录
|
||
(SDK_BASE, "modules/fs/README.md"),
|
||
(SDK_BASE, "modules/lisa_shell/README.md"),
|
||
(SDK_BASE, "modules/usb/device/uvc/README.md"),
|
||
]
|
||
|
||
external_content_exclude = [
|
||
"drivers/porting_docs/**/*.md",
|
||
"drivers/lisa_device/**/*.md",
|
||
"drivers/Devices_Docs_Spec.md",
|
||
"samples/drivers/hal/**/README.md",
|
||
"samples/Samples_Spec.md",
|
||
"samples/drivers/devices/Devices_Samples_Spec.md",
|
||
"samples/modules/sqlite3/README.md",
|
||
"components/acomp/logger/**/README.md",
|
||
"demos/face_detect/src/button/FlexibleButton/README.md",
|
||
]
|
||
|
||
# Keep template files from being deleted by external_content
|
||
# Note: CSS/JS files are in docs/assets/ which is outside the source dir
|
||
external_content_keep = [
|
||
"_templates/*",
|
||
"_templates/**/*",
|
||
]
|
||
|
||
|
||
# -- Options for HTML output -------------------------------------------------
|
||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||
|
||
html_theme = 'sphinx_rtd_theme'
|
||
html_theme_options = {
|
||
"logo_only": True,
|
||
"prev_next_buttons_location": None
|
||
}
|
||
html_show_sphinx = False
|
||
html_logo = r'../assets/logo.svg'
|
||
html_static_path = [str(HTML_STATIC_DIR), str(HTML_ASSETS_DIR)]
|
||
html_last_updated_fmt = "%b %d, %Y"
|
||
html_domain_indices = False
|
||
html_split_index = True
|
||
html_show_sphinx = False
|
||
|
||
# Version switcher configuration
|
||
html_context = {
|
||
# 当前版本
|
||
'current_version': 'latest',
|
||
# 版本列表
|
||
'versions': [
|
||
('latest', 'https://docs2.listenai.com/arcs-sdk/latest/zh/html/index.html'),
|
||
('v0.1.0', 'https://docs2.listenai.com/arcs-sdk/v0.1.0/zh/html/index.html'),
|
||
('v0.1.1', 'https://docs2.listenai.com/arcs-sdk/v0.1.1/zh/html/index.html'),
|
||
('v0.1.2', 'https://docs2.listenai.com/arcs-sdk/v0.1.2/zh/html/index.html'),
|
||
],
|
||
# 显示版本警告横幅(可选)
|
||
'display_github': False,
|
||
}
|
||
|
||
# Add custom CSS and JS files
|
||
html_css_files = [
|
||
'version-switcher.css',
|
||
'feedback-widget.css',
|
||
]
|
||
|
||
html_js_files = [
|
||
'version-switcher.js',
|
||
'feedback-widget.js',
|
||
]
|
||
|
||
suppress_warnings = ['toc.excluded',
|
||
'toc.not_readable',
|
||
'toc.not_included', # 允许 sample_build.rst、sample_flash.rst 等被 include 的文件不在 toctree 中
|
||
'toc.secnum','toc.circular','epub.duplicated_toc_entry','autosectionlabel.*',
|
||
'app.add_source_parser',
|
||
'myst.header',
|
||
'ref.doc',
|
||
'ref.ref',
|
||
'myst.domains',
|
||
'myst.xref_missing']
|
||
|
||
myst_heading_anchors = 2
|
||
|
||
myst_enable_extensions = [
|
||
"amsmath",
|
||
"colon_fence",
|
||
"deflist",
|
||
"dollarmath",
|
||
"fieldlist",
|
||
"html_admonition",
|
||
"html_image",
|
||
"replacements",
|
||
"smartquotes",
|
||
"strikethrough",
|
||
"substitution",
|
||
"tasklist",
|
||
]
|
||
|
||
def setup(app):
|
||
"""Sphinx setup hook to add custom HTML for version switcher"""
|
||
def add_version_switcher(app, pagename, templatename, context, doctree):
|
||
"""Add version switcher HTML to every page"""
|
||
versions = context.get('versions', [])
|
||
current_version = context.get('current_version', '')
|
||
|
||
if versions:
|
||
version_html = '''
|
||
<div class="rst-versions" data-toggle="rst-versions" role="note">
|
||
<span class="rst-current-version" data-toggle="rst-current-version">
|
||
<span class="fa fa-book"> 文档版本 </span>
|
||
<span class="current-version-label">v: {}</span>
|
||
<span class="fa fa-caret-down"></span>
|
||
</span>
|
||
<div class="rst-other-versions">
|
||
<dl>
|
||
<dt>版本</dt>
|
||
'''.format(current_version)
|
||
|
||
for version_name, version_url in versions:
|
||
if version_name == current_version:
|
||
version_html += f' <dd><strong>{version_name}</strong></dd>\n'
|
||
else:
|
||
version_html += f' <dd><a href="{version_url}">{version_name}</a></dd>\n'
|
||
|
||
version_html += ''' </dl>
|
||
</div>
|
||
</div>
|
||
'''
|
||
context['version_switcher_html'] = version_html
|
||
|
||
app.connect('html-page-context', add_version_switcher)
|
||
|
||
|
||
# -- Source Link Configuration -----------------------------------------------
|
||
# 配置源码链接扩展
|
||
|
||
# 仓库基础 URL (仅配置到 /-/tree/ 之前的部分,分支名会自动根据版本添加)
|
||
# 支持 GitHub/GitLab 或内部 Git 仓库
|
||
# 例如: 'https://github.com/listenai/arcs-sdk' (会自动添加 /tree/分支名)
|
||
# 'https://cloud.listenai.com/CSKG836746/arcs-sdk/public/arcs-sdk' (会自动添加 /-/tree/分支名)
|
||
source_link_base_url = os.environ.get(
|
||
"SOURCE_LINK_BASE_URL",
|
||
"https://cloud.listenai.com/CSKG836746/arcs-sdk/public/arcs-sdk/-/tree/master"
|
||
)
|
||
|
||
# 文档版本到 Git 分支的映射
|
||
# 如果版本不在映射中,会使用以下规则:
|
||
# - 'latest' -> 'master'
|
||
# - 'v0.1.0' -> 'release/v0.1.0'
|
||
source_link_version_branches = {
|
||
'latest': 'master',
|
||
'v0.1.0': 'release/v0.1.0',
|
||
'v0.1.1': 'release/v0.1.1',
|
||
# 添加更多版本映射...
|
||
}
|
||
|
||
# 哪些文档需要添加源码链接 (支持通配符)
|
||
source_link_patterns = [
|
||
"samples/**/*.md",
|
||
"samples/**/*.rst",
|
||
"demos/**/*.md",
|
||
"demos/**/*.rst",
|
||
]
|
||
|
||
# 是否显示本地路径
|
||
source_link_show_local_path = True
|
||
|
||
# 源码位置标签文本
|
||
source_link_label = "📁 源码位置"
|
||
|