Добавление тега скрипта javascript в какое-то место, чтобы он работал для каждого файла в документации sphinx

Я использую Sphinx, чтобы писать заметки. Я использую расширение Mathjax для математики в заметках. Размер математики по умолчанию немного больше, чем хотелось бы. На странице Mathjax я обнаружил, что могу изменить этот размер, добавив следующий скрипт в файл HTML.

MathJax.Hub.Config({
  "HTML-CSS": {scale: 90}
});

Итак, я попытался добавить следующее в файл .rst:

.. raw:: html

    <script type="text/javascript" >
        MathJax.Hub.Config({
            "HTML-CSS": {
                scale: 90
            }
        });
    </script>

==========
Objective
==========

To change math size \\( \\alpha \\).

Вышеприведенное отлично работает для математики в этом конкретном файле .rst. Но я хочу сделать это для многих разных файлов .rst, которые являются частью одного и того же документа sphinx. Можно ли это сделать, не добавляя приведенный выше скрипт в каждый файл .rst?

Спасибо, что прочитали это, и был бы признателен, если бы вы могли помочь.


python javascript python-sphinx
person Curious2learn    schedule 25.02.2012    source источник

Ответы (5)


arrow_upward
20
arrow_downward

Это можно сделать с помощью шаблона:

  1. Создайте папку с именем templates в каталоге проекта Sphinx.

  2. В conf.py добавляем

    templates_path = ["templates"]

  3. В каталоге templates создайте файл с именем layout.html со следующим содержимым:

    {% extends "!layout.html" %}

{%- block extrahead %} 
 <script type="text/javascript">
       MathJax.Hub.Config({
           "HTML-CSS": {
               scale: 90
           }
       });
  </script>      
{% endblock %}

Элемент <script> будет включен в <head> каждой сгенерированной HTML-страницы.

Блок шаблона extrahead по умолчанию пуст. Подробнее см. в документации по шаблонам Sphinx.

person mzjn    schedule 26.02.2012
comment
Спасибо большое. Это сработало отлично! Отдельное спасибо за подробные шаги. Почему в строке {%- block extrahead} стоит -. Без тире не работает. В примерах кода, которые я видел по ссылке, нет этого -. - person Curious2learn; 28.02.2012
comment
Блок extrahead по умолчанию в sphinx/themes/basic/layout.html имеет дополнительный дефис/тире/минус (это примерно управление пробелами). Но я не могу толком объяснить, почему у вас не работает без него... - person mzjn; 28.02.2012
comment
Спасибо. Я посмотрю на это. Во всяком случае, он отлично работает с тире. Еще раз спасибо за ответ. - person Curious2learn; 01.03.2012
comment
Мне не нужен был тире. Это отлично сработало для добавления расширения Tex mhchecm.js, чтобы я мог использовать теги \ce tex для создания химических уравнений с использованием mhchem. - person Mark Mikofski; 03.08.2013
comment
Последние документы MathJax говорят используйте "text/x-mathjax-config" в качестве типа сценария вместо "text/javascript" EG <script type="text/x-mathjax-config"> - person Mark Mikofski; 07.08.2013

arrow_upward
3
arrow_downward

Другой метод:

Используйте параметр script_files в переопределенном файле layout.html.

person Kevin Horn    schedule 21.03.2012

arrow_upward
3
arrow_downward

Если вы хотите избежать изменения шаблонов, вы можете просто вызвать Sphinx add_js_file() из функции setup() в conf.py:

# conf.py

# ... other settings ...

def setup(app):
    # (create a setup() function if you don't already have one;
    # or add to the existing setup() ...)
    app.add_js_file("mathjax-config.js")

Создайте файл mathjax-config.js в исходном каталоге _static. (Проверьте параметр conf.py html_static_path. чтобы проверить статические каталоги или определить их, если это необходимо.) Sphinx скопирует их в выходной каталог во время сборки.

Также есть add_css_file(). метод для файлов css. И оба они могут использовать либо относительные пути к вашим статическим исходным каталогам, либо полные URL-адреса внешних ресурсов.

До Sphinx v1.8 эти функции назывались add_javascript() и add_stylesheet().

А в Sphinx v3.0 или более поздних версиях есть даже более простой подход, позволяющий избежать необходимости в дополнительном JS-файле.

person medmunds    schedule 27.01.2017
comment
Кажется, для этого требуется настроить расширение, верно? - person NirIzr; 09.02.2017
comment
Расширение не требуется: вы можете поместить функцию setup() в собственный файл conf.py вашего проекта. (Вашему проекту фактически разрешено быть его собственным расширением.) - person medmunds; 09.02.2017
comment
@medmunds Каким должно быть содержание mathjax-config.js в этом случае? Спасибо! - person lcnittl; 25.08.2020
comment
@lcnittl файл JS может содержать любую дополнительную конфигурацию, которая вам нужна. Используя пример из исходного вопроса в верхней части этой страницы, это может быть что-то вроде MathJax.Hub.Config({... и т. д. (Если вам нужна помощь с конкретными параметрами MathJax, вероятно, лучше задать новый вопрос.) - person medmunds; 25.08.2020
comment
@medmunds спасибо за ответ! Сначала я не был уверен, откуда возникла проблема (неверное ли содержимое js-файла или проблема в его «запуске»), но теперь я начал работать с тем, что мне нужно, с ответ @mzjn. Я мог бы действительно открыть новый вопрос, чтобы найти проблему (ваш новый ответ также не работает для моего варианта использования), потому что я думаю, что ваше решение более гладкое/более легкое. - person lcnittl; 26.08.2020
comment
@medmunds Я обязательно открою новый вопрос (хотя это может занять некоторое время), так как я заставил его работать с вашим новым ответом. В этом случае необходимо было добавить дополнительный атрибут type="text/x-mathjax-config". Ваше здоровье. - person lcnittl; 26.08.2020
comment
@medmunds Я решил это сейчас. Это не стоит еще одного вопроса, но я думаю, было бы неплохо, если бы вы могли включить его в свой ответ (ответы), иначе они не будут работать. Метод этого ответа требует window.MathJax = {...} вместо MathJax.Hub.Config({...}) для правильной работы, поскольку MathJax не обязательно инициируется в этот момент или недоступен из сценария mathjax-config.js (см. docs.mathjax.org/en/v2.7-latest/ ). Спасибо за рассмотрение редактирования! - person lcnittl; 01.09.2020

arrow_upward
1
arrow_downward

В Sphinx 3.0 и более поздних версиях самый простой способ добавить короткие фрагменты конфигурации JavaScript — это вызвать app.add_js_file(None, body="...JS code...") в функции настройки conf.py. Пример:

# In your Sphinx project's conf.py:

# 1. Add whatever JS code you need as a string constant.
#    (This example is from the original question.)
MATHJAX_CONFIG_JS = """
MathJax.Hub.Config({
  "HTML-CSS": {scale: 90}
});
"""

# 2. Create a setup() function if you don't already have one.
#    (If you do, just add to your existing setup() function.)
def setup(app):
    # 3. Tell Sphinx to add your JS code. Sphinx will insert
    #    the `body` into the html inside a <script> tag:
    app.add_js_file(None, body=MATHJAX_CONFIG_JS)

При таком подходе вам не нужно создавать отдельный статический файл JS.

(Парам body был добавлен в Sphinx 3.0; в более ранних версиях вы по-прежнему можете использовать add_js_file() со статическим файлом JS — см. мой предыдущий ответ , И для всего, что длиннее короткого фрагмента конфигурации, в любом случае, вероятно, лучше использовать внешний файл.)

person medmunds    schedule 25.08.2020
comment
Это снова я :) Я думаю, что в этом случае type="text/x-mathjax-config" обязателен, так как инициация MathJax запустит эти скрипты (см. docs.mathjax.org/en/v2.7-latest/ ). Также здесь, спасибо за рассмотрение редактирования! - person lcnittl; 01.09.2020

arrow_upward
0
arrow_downward

Самым простым решением для конфигурации только conf.py может быть использование значения конфигурации расширения MathJax mathjax_config (доступно с 1.8). Значение mathjax_config передается в MathJax.Hub.Config().

В вашем конкретном случае добавьте следующее к conf.py:

mathjax_config = {
    "HTML-CSS": {"scale": 90},
}
person lcnittl    schedule 16.09.2020