Блог

Я использую 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'
  

источник/contents.rst:

 Contents
========

Content here
  

make-doc.bat:

 SET SPHINX_BUILD="C:Program FilesPython37Scriptssphinx-build.exe"
SET HHC="C:Program Files (x86)HTML Help Workshophhc.exe"

RMDIR /S/Q build

%SPHINX_BUILD%  source buildhtml

%SPHINX_BUILD% -b htmlhelp source buildhtmlhelp
%HHC% buildhtmlhelpexample.hhp
  

Запустите make-doc.bat , и справка HTML выглядит «ок», и example.chm все выглядит нормально.

Изменить «conf.py » использовать 'sphinx_rtd_theme' , а затем make-doc.bat снова запустить. Теперь HTML-справка выглядит «великолепно». Но при открытии example.chm сразу отображается ошибка Javascript. Эта ошибка появляется для каждой страницы, на которую вы переходите (это единственная страница в этом игрушечном проекте).

Очевидно, что существует несовместимость между компилятором sphinx_rtd_theme справки HTML и Microsoft.

Пока эта ошибка / несовместимость не будет исправлена, меня устраивает скомпилированная справка по classic теме, но я бы хотел использовать интерактивную HTML-справку sphinx_rtd_theme .

Могу ли я получить условную компиляцию на conf.py основе текущего builder?

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

Не работает, потому что builder_xxx тег не устанавливается до 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'),
            }
        },
    )