Исключить комментарии reStructuredText в выводе Sphinx HTML

Я хотел бы добавить несколько комментариев в документ reStructuredText, которые не отображаются, когда я создаю свою документацию. Например, я хотел бы поместить в файл следующее:

This is the source of my .rst file. I would like the following block to be excluded when the docs are built.
..
    This should not show up in the HTML.
    This should not either.

This text would show up in the HTML, as we're past the comment block.

Согласно документам Sphinx, в зависимости от средства форматирования вывода, комментарии могут быть удалены из обработанного вывода. Однако я не вижу никаких вариантов для этого в документы конфигурации вывода HTML.

Я использую Sphinx (sphinx-build) для создания своих документов. Я использовал sphinx-quickstart для настройки и, таким образом, построить через make html.

Заранее спасибо!


python-3.x python python-sphinx restructuredtext
person blthayer    schedule 22.06.2020    source источник
comment
ИМХО все строители удаляют комментарии   -  person Matt    schedule 03.07.2020

Ответы (1)


arrow_upward
3
arrow_downward

Ваш синтаксис немного неправильный. Пробелы имеют значение в reST. Вы должны разделять блоки пустой строкой, например:

This is the source of my .rst file. I would like the following block to be excluded when the docs are built.

..  This should not show up in the HTML.
    This should not either.

This text would show up in the HTML, as we're past the comment block.

Изменить

Комментарии - это блоки, а не встроенные. Синтаксиса встроенных комментариев нет. Однако вы можете злоупотреблять заменами.

.. |This is my comment that will be replaced by nothing| replace:: \

Hello |This is my comment that will be replaced by nothing| World!

Вы также можете использовать хитрость, указав класс CSS через rst-class в блок, содержащий текст, который вы хотите прокомментировать, затем используйте встроенную разметку вокруг комментария и примените собственный стиль с селектором CSS, таким как .comment>strong, который скрывает комментарий от визуального отображения в HTML.

#reST

.. rst-class:: comment

Block of text that **MY COMMENT** contains a comment.

#CSS
p.comment>strong {display:none;}
person Steve Piercy    schedule 22.06.2020