sdk-bsp-rzn2l-etherkit/docs/source/conf.py

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
import yaml
sys.path.insert(0, os.path.abspath('..'))

# 加载配置文件
def load_config():
    """加载配置文件"""
    config_path = os.path.join(os.path.dirname(__file__), 'config.yaml')
    if os.path.exists(config_path):
        with open(config_path, 'r', encoding='utf-8') as f:
            return yaml.safe_load(f)
    return {}

config = load_config()
project_config = config.get('project', {})
sphinx_config = config.get('sphinx', {})
repository_config = config.get('repository', {})

# -- Project information -----------------------------------------------------

project = project_config.get('name', 'SDK_Docs')
copyright = project_config.get('copyright', '2025, apache')
author = project_config.get('author', 'unknown')

# The full version, including alpha/beta/rc tags
release = project_config.get('version', '0.0.1')
# 动态设置主文档：优先使用环境变量，否则使用默认值
import os
master_doc = os.environ.get('SPHINX_MASTER_DOC', 'index_zh')

# 如果通过命令行参数指定了master_doc，则使用命令行参数的值
# 这需要在构建脚本中通过环境变量传递
if 'SPHINX_MASTER_DOC_OVERRIDE' in os.environ:
    master_doc = os.environ['SPHINX_MASTER_DOC_OVERRIDE']

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = sphinx_config.get('extensions', ['myst_parser'])

source_suffix = sphinx_config.get('source_suffix', {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
})

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
# 优先使用环境变量，然后使用配置文件，最后使用默认值
language = os.environ.get('SPHINX_LANGUAGE', project_config.get('language', 'zh_CN'))

# 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.
# 基础排除模式
base_exclude_patterns = [
    'MIGRATION_GUIDE.md',
    'OPTIMIZATION_SUMMARY.md',
    'README_NEW_BUILD_SYSTEM.md',
    'requirements.txt',
    'utils/',
    '_templates/',
    '_static/',
    '_build/',
]

# 根据环境变量设置文档排除模式
exclude_patterns = base_exclude_patterns.copy()
if 'SPHINX_EXCLUDE_PATTERNS' in os.environ:
    env_exclude_patterns = os.environ['SPHINX_EXCLUDE_PATTERNS'].split(',')
    env_exclude_patterns = [pattern.strip() for pattern in env_exclude_patterns if pattern.strip()]
    exclude_patterns.extend(env_exclude_patterns)

# 调试信息
print(f"DEBUG: master_doc = {master_doc}")
print(f"DEBUG: language = {language}")
print(f"DEBUG: exclude_patterns = {exclude_patterns}")

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation
# for a list of builtin themes.
#
html_theme = sphinx_config.get('theme', 'sphinx_rtd_theme')

# Add any paths that contain custom static files (such as style sheets) here,
# 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']

# -- Options for internationalization ----------------------------------------

# 多语言支持配置
# locale_dirs = ['../docs/locale/']
# gettext_compact = False

# -- MyST Parser configuration ----------------------------------------------

myst_enable_extensions = sphinx_config.get('myst_extensions', [
    "colon_fence",
    "deflist",
    "dollarmath",
    "html_image",
    "html_admonition",
    "replacements",
    "smartquotes",
    "strikethrough",
    "substitution",
    "tasklist",
])

# MyST图片配置
myst_gfm_only = False
myst_heading_anchors = 0

# 配置图片处理
myst_all_links_external = False
myst_url_schemes = ('http', 'https', 'mailto', 'ftp')

# 图片路径配置
html_extra_path = []
html_css_files = ['version_menu.css', 'custom.css', 'pdf_button.css', 'edit_button.css', 'language_switch.css', 'dark_mode.css']
html_js_files = ['version_menu.js', 'download_pdf.js', 'version_info.js', 'edit_on_github.js', 'language_switch.js']

# 配置图片路径处理
html_favicon = None

# 配置文档结构
html_show_sourcelink = False
html_show_sphinx = False
html_show_copyright = True

# 配置导航
html_theme_options = {
    'navigation_depth': 4,
    'titles_only': False,
    'collapse_navigation': False,
    'sticky_navigation': True,
    'includehidden': True,
}

# 配置文档结构
html_use_index = True
html_split_index = False
html_copy_source = False

# 配置导航结构
html_sidebars = {
    '**': [
        'globaltoc.html',
        'relations.html',
        'sourcelink.html',
        'searchbox.html',
    ]
}

# 配置toctree选项
html_use_index = True
html_split_index = False
html_copy_source = False

# 检测构建环境并配置URL
import os
is_github_actions = os.environ.get('GITHUB_ACTIONS') == 'true'

if is_github_actions:
    # GitHub Pages环境：使用相对URL
    html_use_relative_urls = True
    html_baseurl = ""
else:
    # 本地构建环境：使用相对URL，但禁用canonical链接
    html_use_relative_urls = True
    html_baseurl = ""
    # 禁用canonical链接以避免错误的绝对路径
    html_show_sourcelink = False


# 传递编辑基础 URL 给模板/前端脚本
def derive_edit_base_url():
    # 优先使用 config.yaml 显式配置
    explicit = (repository_config.get('edit_base_url', '') or '').strip()
    if explicit:
        return explicit.rstrip('/') + '/'

    # 其后尝试从 GitHub Actions 环境变量推断（owner/repo）
    gh_repo = os.environ.get('GITHUB_REPOSITORY', '').strip()  # e.g. owner/name
    if gh_repo and '/' in gh_repo:
        return f"https://github.com/{gh_repo}/edit/"

    # 再其次，从 git remote.origin.url 推断
    try:
        import subprocess
        origin = subprocess.run(['git', 'config', '--get', 'remote.origin.url'],
                                capture_output=True, text=True, check=True).stdout.strip()
        if origin:
            if origin.startswith('git@') and 'github.com:' in origin:
                # git@github.com:owner/repo.git
                repo_path = origin.split('github.com:')[-1]
                repo_path = repo_path[:-4] if repo_path.endswith('.git') else repo_path
                return f"https://github.com/{repo_path}/edit/"
            if origin.startswith('https://') and 'github.com' in origin:
                # https://github.com/owner/repo.git
                repo_path = origin.split('github.com/')[-1]
                repo_path = repo_path[:-4] if repo_path.endswith('.git') else repo_path
                return f"https://github.com/{repo_path}/edit/"
    except Exception:
        pass

    # 最后兜底：使用 repository.name（无法确定 owner，仅供部分场景）
    repo_name = (repository_config.get('name', '') or '').strip()
    if repo_name:
        return f"https://github.com/{repo_name}/edit/"
    return ''

html_context = {
    'edit_base_url': derive_edit_base_url(),
}
"""
LaTeX / PDF 构建配置
"""

# 使用 XeLaTeX 以更好支持 CJK 字体
latex_engine = 'xelatex'

# 配置 LaTeX 文档元信息与固定主文档名，便于脚本查找
latex_documents = [
    # (source start file, target name, title, author, documentclass)
    ('index', 'sdk-docs.tex', project, author, 'manual'),
]

# 额外 LaTeX 元素：引入中文字体与更好的换行支持
latex_elements = {
    'preamble': r'''
% CJK 支持
\usepackage{xeCJK}
\setCJKmainfont{Noto Sans CJK SC}
\setCJKsansfont{Noto Sans CJK SC}
\setCJKmonofont{Noto Sans Mono CJK SC}
% 改善中文行距与段落
\linespread{1.2}
''',
}