Question

我正在使用Sphinx为Windows项目生成文档。我生成两种类型的文档：HTML和Microsoft编译的HTML帮助。我想用不同的主题来生成它们。

这是一个演示问题的玩具项目：

project\
   +-- source\
   |     +-- conf.py
   |     +-- contents.rst
   +-- make-doc.bat

source / conf.py：

project = 'Example'

html_theme = 'classic'
#html_theme = 'sphinx_rtd_theme'

htmlhelp_basename = 'example'

source / contents.rst：

Contents
========

Content here

make-doc.bat：

SET SPHINX_BUILD="C:\Program Files\Python37\Scripts\sphinx-build.exe"
SET HHC="C:\Program Files (x86)\HTML Help Workshop\hhc.exe"

RMDIR /S/Q build

%SPHINX_BUILD%  source build\html

%SPHINX_BUILD% -b htmlhelp source build\htmlhelp
%HHC% build\htmlhelp\example.hhp

运行make-doc.bat，HTML帮助看起来“确定”，而example.chm看起来很好。

将“ conf.py”更改为使用'sphinx_rtd_theme'，然后再次运行make-doc.bat。现在，HTML帮助看起来“很棒”。但是，当您打开example.chm时，将立即显示Javascript错误。对于您导航到的每个页面（此玩具项目中的唯一页面），都会弹出此错误。

很明显，sphinx_rtd_theme与Microsoft HTML帮助编译器之间不兼容。

在修复该错误/不兼容之前，我对使用classic主题的编译帮助感到满意，但我希望在线HTML帮助使用sphinx_rtd_theme。

我可以根据当前的构建器在conf.py中进行条件编译吗？

if tags.has('builder_htmlhelp'):
    html_theme = 'classic'
else:
    html_theme = 'sphinx_rtd_theme'

不起作用，因为builder_xxx tag直到解析conf.py之后才被设置。

更新

上面的make-doc.bat批处理脚本在实际项目中实际上并不存在。我添加了它以创建一个最小的示例来演示该问题。实际的构建环境使用setup.py和

py -3.7 setup.py build_sphinx

调用Sphinx。因此，对setup.py进行的修改可以为构建环境添加一些内容，conf.py可以检测并修改其主题，

setup.py：

from setuptools import setup

name = 'example'
version = '1.0'
release = '1.0.0'

setup(
    name=name,
    version=version,
    release=release,
    description='Help Example',
    python_requires='>=3',
    install_requires=['pywin32'],
    packages=['example'],
    command_options={
        'build_sphinx': {
            'project': ('setup.py', name),
            'version': ('setup.py', version),
            'release': ('setup.py', release),
            'source_dir': ('setup.py', 'source'),
            'builder': ('setup.py', 'html htmlhelp'),
            }
        },
    )

根据构建器选择Sphinx主题

更新

0 个答案: