Выберите тему Sphinx на основе сборщика - PullRequest
Новая
       19

Выберите тему Sphinx на основе сборщика

0 голосов
/ 12 апреля 2019

Я использую Sphinx для генерации документации для проекта Windows. Я создаю два типа документации: HTML и Microsoft Compiled HTML Help. Я хотел бы создать их с разными темами.

Вот игрушечный проект, который демонстрирует проблему: 

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

источник / conf.py: 

project = 'Example'

html_theme = 'classic'
#html_theme = 'sphinx_rtd_theme'

htmlhelp_basename = 'example'

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

Contents
========

Content here

макияж 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 не устанавливается до тех пор, пока не проанализирован conf.py.

Обновление

Пакетный скрипт make-doc.bat выше не существует в реальном проекте. Я добавил его, чтобы создать минимальный пример для демонстрации проблемы. Фактическая среда сборки использует setup.py и 

py -3.7 setup.py build_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'),
            }
        },
    )
...