Более согласованные темы Сфинкса - PullRequest
Новая
       10

Более согласованные темы Сфинкса

6 голосов
/ 01 октября 2019

Рассмотрим следующую функцию 

# in mymodule.py:

def myfunc(num,mystring):
    """
    replicates a string

    :param num: a positive integer
    :param mystring: a string
    :return: string concatenated with itself num times

    :Example:
        >>> num = 3
        >>> mystring = "lol"
        >>> myfunc(num, mystring)
        "lollollol"
    """
    return num*mystring

Если я использую Sphinx для генерации кода из моей строки документации, это выглядит так (на этот раз я использую тему по умолчанию haiku, без особых изменений вrst или conf.py file):

enter image description here

Существуют ли какие-либо темы - или любые другие обходные пути - которые решают проблемы, которые я указал цветами?

Я пробовал разные, но никто не работал, но я не мог получить ни одного из пунктов 1.-4. на работу.

РЕДАКТИРОВАТЬ Идея состоит в том, что я не хочу редактировать HTML, что является слишком громоздким. Я хочу внести изменения только в файлы conf.py и index.rst в моем каталоге Sphinx docs, чтобы внести указанные изменения.

1 Ответ

4 голосов
/ 08 октября 2019

Настройка CSS сама по себе не может решить эту проблему. Даже если вы можете использовать ::before и после ::after селекторов, я думаю, что JavaScript лучше подходит для этого.

Вы можете добавить пользовательский файл Javascript, используя html_js_files опция в conf.py . Ваши требования 1, 2 и 3 должны быть возможны при использовании этого. 

#  ...

html_js_files = ['custom.js']

# ...

Если вы используете приведенный выше код в conf.py , тогда ваш custom.js файл должен быть расположен следующим образом 

docs/
  _static/
    custom.css
    custom.js
  _templates/
  index.rst
  api.rst
  ...

Пример

Перед добавлением custom.js

enter image description here

My custom.js file 

window.onload = function () {
    // Change 'Parameters' to 'Arguments' 
    first_dt_elements = document.querySelectorAll('dl.field-list > dt:first-child');
    for(let i = 0; i< first_dt_elements.length; i++){
        first_dt_elements[i].innerText="Arguments";
    }
    // arguments same font and typeface etc..
    dl_methods = document.querySelectorAll('dl.function, dl.method');
    parameter_texts = []
    for(let i = 0; i< dl_methods.length; i++){
        params = [];
        param_elems=dl_methods[i].querySelectorAll('.sig-param');
        for (let j = 0; j< param_elems.length; j++){
            params.push(param_elems[j].innerText);
        }
        for( let k=0; k<params.length; k++){
            str = dl_methods[i].innerHTML;
            dl_methods[i].innerHTML= str.replace(
                RegExp(params[k], "g"), 
                '<span style="color:red;font-family:monospace;font-style:normal;">'
                + params[k] +
                '</span>'
            );
        }
    }
}

После повторного построения HTML

enter image description here

Относительно необязательного требования 4

Сфинкс использует фрагментов для выделения синатекса. Если вас это не устраивает, вы можете использовать Highlightjs , Prismjs , Код Google prettify и т. Д., Загрузив и включив их через html_js_files. Но это также подсветка синтаксиса . Семантические маркеры, которые подсвечивают переменные, доступны для python, но я не слышал ничего о том, что можно использовать со Sphinx.

Примечание :

  • Я использую Алебастровая тема . Но эта идея должна работать на большинство тем. Однако вам придется написать файл custom.js в соответствии с вашей темой. Файл
  • My custom.js очень прост и не учитывает всевозможности.
...