How to comment a string in restructured text?

HtmlRestructuredtext

Html Problem Overview


The comment of HTML is <!-- .. -->, how can I make this comment block with restructured text? In order words, how can I comment out some of the lines in restructured text?

Html Solutions


Solution 1 - Html

From the reference:

> Arbitrary indented text may follow the > explicit markup start and will be > processed as a comment element.

..
   _This: is a comment!

..
   [and] this!

..
   this:: too!

..
   |even| this:: !

It is also possible to put the comment on the same line as the double dots:

.. Avoid this type of comment

This is however considered bad practice since it may lead to unintended consequences if the comment matches a proper markup construct, as pointed out by @CecilCurry in the comment below.

Solution 2 - Html

For comments, add 2 periods .. followed by a newline and then your comment indented.

Example:

..
  comment goes here

Solution 3 - Html

Please forgive this duplicative answer cos I'm trying to help RST newbies like me. My answer shows the CONTEXT of a comment.

I naively tried marking a line in my RST document using the answer above, DO NOT DO THIS:

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
    .. Hi everyone this line will never be seen
    Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Sphinx (or other RST formatter) will not complain, but "hi everyone" will appear in the output. Instead place a blank line before and after your comment like this:

    Lorem ipsum dolor sit amet, consectetur adipiscing elit.

    .. 
        comment Hi everyone this line will never be seen

    Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

But the downside of this is that the paragraph is ended then restarted, so you will have whitespace between.

I have not found any equivalent in RST for the C /* */ or HTML <!-- --> comment syntax that can make some text vanish totally.

Solution 4 - Html

I came across this thread, looking for a more defined way to place comments in restructuredtext. Personally, I also of course don't like the one-liner .. this is a comment. To keep comments searchable and recognizable, I propose to consider using

.. only:: comment

    This is a comment

As documented (http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html): "Undefined tags are false", such as comment.

Alternatively, one could write an extension in the style of todo, allowing syntax, such as

.. comment::
    This is a comment

Doing so without such extension of course gives error messages from the builder. But with such extension, just like todo, it would be possible to extract a list of comments from a document.

Solution 5 - Html

Check: http://docutils.sourceforge.net/docs/user/rst/quickref.html#comments

> Any text which begins with an explicit markup start but doesn't use the syntax of any of the constructs above, is a comment.

Attributions

All content for this solution is sourced from the original question on Stackoverflow.

The content on this page is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

Content TypeOriginal AuthorOriginal Content on Stackoverflow
QuestionprosseekView Question on Stackoverflow
Solution 1 - HtmljballView Answer on Stackoverflow
Solution 2 - HtmlMiguel MotaView Answer on Stackoverflow
Solution 3 - HtmlchrisinmtownView Answer on Stackoverflow
Solution 4 - HtmlDr. VView Answer on Stackoverflow
Solution 5 - HtmlyanView Answer on Stackoverflow