Как обрабатывать два тире в ReST

Я использую Sphinx для документирования утилиты командной строки, написанной на Python. Я хочу иметь возможность задокументировать параметр командной строки, например --region, например:

**--region**  <region_name>

в ReST, а затем используйте Sphinx для создания моих HTML-страниц и справочных страниц.

Это прекрасно работает при создании справочных страниц, но в сгенерированном HTML -- превращается в -, что неверно. Я обнаружил, что если я изменю исходный документ ReST, чтобы он выглядел так:

**---region**  <region_name>

HTML генерируется правильно, но теперь мои справочные страницы имеют --- вместо --. Тоже неверно.

Я пытался экранировать тире символом обратной косой черты (например, \-\-), но это не дало никакого эффекта.

Любая помощь приветствуется.


python-sphinx restructuredtext
person garnaat    schedule 06.03.2013    source источник
comment
Я обнаружил, что одним из простых решений этого является обернуть двойные дефисы внутри разметки кода, например. ``--region``, а не **--region**. Могут быть более элегантные способы решить эту проблему, но это работает для меня.   -  person garnaat    schedule 07.03.2013
comment
Возможно, вы можете использовать список параметров: docutils.sourceforge.net/ документы/ref/rst/   -  person mzjn    schedule 07.03.2013
comment
Да вроде уместно. Спасибо, все время открываю для себя что-то новое в ReST!   -  person garnaat    schedule 08.03.2013

Ответы (5)


arrow_upward
4
arrow_downward

Это параметр конфигурации Sphinx, который включен по умолчанию: параметр html_use_smartypants (http://sphinx-doc.org/config.html?highlight=dash#confval-html_use_smartypants).

Если вы отключите эту опцию, вам придется использовать символ Unicode «–», если вы хотите использовать короткое тире.

person Joseph    schedule 12.03.2013
comment
Это, конечно, обходной путь. Я считаю это поведение ошибкой, потому что не может быть так сложно просто сначала заменить «--» на endash, а после «---» на emdash. - person TNT; 05.02.2014
comment
И в смысле этой особенности например :command:`sphinx-build --version` дает типографически правильную командную строку: sphinx-build —–version... - person TNT; 05.02.2014

arrow_upward
2
arrow_downward

С участием

**-\\-region**  <region_name>

он должен работать.

person Community    schedule 30.08.2017

arrow_upward
1
arrow_downward

В Sphinx 1.6 html_use_smartypants объявлен устаревшим, и больше нет необходимости устанавливать html_use_smartypants = False в conf.py или в качестве аргумента sphinx-build. Вместо этого вы должны использовать smart_quotes = False.

Если вы хотите использовать преобразования, ранее предоставленные html_use_smartypants, вместо этого рекомендуется использовать smart_quotes, например, smart_quotes = True.

Обратите внимание, что на момент написания этой статьи Read the Docs закрепляет sphinx==1.5.3, который не поддерживает параметр smart_quotes. До тех пор вам нужно будет продолжать использовать html_use_smartypants.

EDIT Похоже, что Sphinx теперь использует smartquotes вместо docutils smart_quotes. ч/т @bad_coder.

person Steve Piercy    schedule 15.08.2017
comment
Обратите внимание на то, что синтаксис изменен на smartquotes = False. Именно эта однострочная конфигурация решила для меня проблему с двойным тире --. - person bad_coder; 19.03.2021

arrow_upward
0
arrow_downward

Чтобы добавить два тире, добавьте следующее:

.. include:: <isotech.txt>

|minus|\ |minus|\ region

Обратите внимание на обратную косую черту и пробел. Это позволяет избежать пробела между знаком минус и именем параметра.

Вам нужно только включить isotech.txt один раз на страницу.

С помощью этого решения вы можете сохранить расширение smartypants и писать два дефиса в каждой части текста, который вам нужен. Не только в списках опций или литералах.

person Montecarlo    schedule 28.03.2017

arrow_upward
0
arrow_downward

Как прокомментировал @mzjn, лучший способ удовлетворить потребности исходного отправителя — использовать Списки опций.

Формат прост: последовательность строк, начинающихся с -, --, + или /, за которыми следует фактическая опция, (как минимум) два пробела, а затем описание опции:

-l     long listing
-r     reversed sorting
-t     sort by time
--all  do not ignore entries starting with .

Количество пробелов между опцией и описанием может варьироваться в зависимости от строки, их должно быть не менее двух, что обеспечивает четкое представление (как указано выше) как в исходном, так и в сгенерированном документе.

Списки опций также имеют синтаксис для аргумента опции (просто поставьте дополнительное слово или несколько слов, заключенных в <> перед двумя пробелами); подробности см. на связанной странице.

Другие ответы на этой странице были нацелены на вопрос исходного отправителя, этот отвечает на их настоящую потребность.

person caxcaxcoatl    schedule 20.06.2020