Комментарии в reStructuredText: как закомментировать строку?

Быстрый ответ

Для добавления комментариев в reStructuredText используйте символы .., после которых необходимо поставить пробел:

.. Ваш комментарий здесь

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

Особенности использования многострочных комментариев

При использовании многострочных комментариев старайтесь сохранять одинаковые отступы и ту же структуру текста:

..
   Этот блок текста является комментарием.
   Здесь можно расположить несколько строк, соблюдая отступы.

После .. обязательно должен следовать блок текста с отступом. Это позволяет создать многострочный комментарий.

Размещение комментариев на одной строке вместе с .. может затруднить чтение кода и вызвать ошибки при его парсинге, поэтому этого следует избегать.

Работа с директивами и устранение возможных ошибок

Рекомендуется активировать разные расширения, такие как todo, чтобы облегчить работу с комментариями и делать их более заметными при внесении исправлений.

Визуализация

Символы .. скрывают текст, идущий после них, в окончательной версии документа, но сохраняют его в исходном коде:

.. Пример скрытого комментария.
    Этот текст будет недоступен при просмотре документа, но останется в коде.

Так, текст становится невидимым при просмотре документа, но сохраняет свою видимость в исходном коде.

Соблюдение лучших практик при комментировании

Однообразие оформления

В многострочных комментариях очень важно сохранять однообразие отступов. Это существенно упрощает восприятие информации.

Подробнее об этом расскажет наш спикер на видео

Различие между конструкциями разметки

Важно не путать комментарии с телефонными директивами reStructuredText. Комментарии предназначены только для внутреннего использования и никак не влияют на конечное отображение текста, в отличие от директив reStructuredText.

Информативность комментариев

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

Структурирование направленных комментариев для улучшения эффективности

Для создания комментариев с расширенными возможностями используйте директиву .. only::. Она особенно полезна при работе над документацией на основе Sphinx.

Использование расширения "todo"

Для больших проектов полезно включить расширение todo, которое позволяет создавать комментарии, отображающиеся в виде списка задач на выполнение.

Устранение возможных ошибок

Если код не распознает определенные синтаксические конструкции в комментариях, вам, скорее всего, потребуется активация соответствующего расширения. По необходимости включайте или настраивайте расширения для минимизации вероятности ошибок.

Полезные материалы

1. A ReStructuredText Primer — официальный гид по синтаксису комментариев в reStructuredText.
2. Quick reStructuredText — компактное руководство по комментированию в reStructuredText.
3. Newest 'restructuredtext+comments' Questions on Stack Overflow — дискуссии и практические примеры комментирования в reStructuredText от участников Stack Overflow.
4. 1. Restructured Text (reST) and Sphinx CheatSheet — шпаргалка по ключевым элементам синтаксиса, включая комментирование в reStructuredText.
5. reStructuredText Primer — Sphinx Documentation — вводное руководство по использованию комментариев в Sphinx и reStructuredText.
6. Getting Started with Sphinx — Read the Docs User Documentation — обзор возможностей reStructuredText в контексте документации, включая процесс комментирования.