Создание буквенного текстового блока в Sphinx

1

Я хотел бы сделать дерево каталогов в docstring и сделать это без изменений в моей документации Sphinx, но у меня проблемы. Я пробовал использовать: одиночные, двойные и тройные обратные тики; literal :code: :; и буквальный .. code-block:: python чтобы заставить это работать. Я думаю, что последние два не работали, потому что этот блок также недействителен Python/code. Кроме того, я изменил количество и тип отступов и интервалов, но безрезультатно.

Мой пример (с использованием трех обратных тиков для обозначения рассматриваемого блока) приведен ниже. Поэтому мой вопрос: как сделать блок с docstring для Sphinx точно так, как показано в docstring? Я в основном хочу отключить разметку на мгновение и представить трубы и отступы, как и в текстовом файле.

В интересах полного раскрытия я нашел подобную должность, но, похоже, ОП уже отказался от Сфинкса к тому времени, когда они спросили, что должность - с 2015 года, и у них были разные ограничения (ведущие/завершающие пустые строки, против отступов и труб). Мне сумасшедшим, чтобы думать, что не было бы способа сделать это?

Пример:

class SetUp(object)
    """Set up temp folders, log files, and global variables.

    The folder tree for setting up looks as follows (using attached
    attribute names rather than paths):

    '''
    |-- workspace
        |-- folder_name (all up to this point = work_folder)
            |-- proc_id (^= process_path)
                |-- gdb_name.gdb (^= gdb_full_path)
    '''

    Using '^=' as short-hand for ''all up to this point, os.path.join()'.

    Attributes
    ----------
    (Etc)
    """
    def __init__(self, log_level, proc_id, gdb_name):
        self.folder_name = "CHECKLIST"
        self.proc_id = proc_id
        # Etc
Теги:
python-sphinx
restructuredtext

2 ответа

0
Лучший ответ

Пробел имеет смысл в reStructuredText. Отступы и новые строки могут быть сложными, особенно с code-block.

Также обратите внимание, что одиночные обратные образы отображаются как курсивом, а не встроенным кодом, в reStructuredText, тогда как в Markdown и SO они отображаются как встроенный код. Для reStructuredText используйте двойные обратные выходы для визуализации встроенных образцов кода.

Наконец, обратите внимание, что для установки первого отступа следует использовать первый разделитель docstring """. В вашем примере есть отступ с 0-пространством, за которым следует отступ в 4 пробела. Лучше иметь разделители docstring на отдельных строках, чтобы отступы появляется последовательно.

Set up temp folders, log files, and global variables.

The folder tree for setting up looks as follows (using attached attribute
names rather than paths):

.. code-block:: text

    |-- workspace
        |-- folder_name (all up to this point = work_folder)
            |-- proc_id (^= process_path)
                |-- gdb_name.gdb (^= gdb_full_path)

Using ''^='' as short-hand for '''all up to this point, os.path.join()''.

Attributes
==========
(Etc)

Изображения, как показано на изображении.

Изображение 174551

Поделиться
0

Так что это никогда не случалось со мной раньше - я нашел ответ через пять минут после публикации. Магия писать это как вопрос в действии!

"Литеральное" ключевое слово было существенным. По-видимому, способ избежать путаницы с парсером Sphinx заключается в использовании директивы "literal include". Поэтому я сохранил дерево каталогов как.txt и заменил данный блок: .. literalinclude:: dir_tree.txt. Бум - красивый зеленый код. Надеюсь, это спасет некоторых других, вырывающих их волосы, как я.

Поделиться
  • 0
    Шаг 1: напишите правильный reStructuredText, который отображает код правильно, используя .. code-block:: text вместо значения по умолчанию : за ним следуют две пустые строки (по умолчанию это интерпретируется как код Python). Шаг 2, скопируйте и вставьте reStructuredText в вашу строку документации, обеспечивая при этом надлежащие пробелы и отступы. Для примера дерева см. Github.com/Pylons/pyramid/blame/master/docs/quick_tutorial/… Обратите внимание, что я использовал символы Unicode, которые требовали дальнейшей настройки Sphinx, но вы можете увидеть, как это работает.
  • 0
    @ StevePiercy Спасибо за ваше предложение, хотя я не смог заставить его работать. Я скопировал и вставил ваш текст (из «необработанного» вида вашей страницы), заменив юникод трубами и тире. Он сломался после первой строки из-за отступа. Возможно, Unicode не сломал бы это? (Что-то, с чем я не очень знаком - я полагаю, я даже не знаю, является ли интервал на самом деле юникодом, а не табуляцией?)
Показать ещё 3 комментария

Ещё вопросы

Сообщество Overcoder
Наверх
Меню