How to comment a string in restructured text?

Question

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?

score 145 · Accepted Answer · edited Jul 22 '20 at 04:45

145

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.

edited Jul 22 '20 at 04:45

Christoffer Reijer

1,925
2
21
40

answered Jan 24 '11 at 15:41

jball

24,791
9
70
92

25

As an addendum to this helpful answer, the first form (i.e., `".. This is a comment"`) should _never_ be used in practice. Basically, considered harmful. Why? Because conditionality. Any comment defined in this way whose first line matches the syntax of any existing explicit markup construct (e.g., citation, directive, footnote, substitution) will be silently reinterpreted as that construct rather than as a comment – **which is horrible.** To prevent this, unconditionally prefix _all_ comments with a single-line `".."` statement as in the remainder of the above examples. – Cecil Curry Aug 14 '16 at 01:18
9

Given what Cecil Curry has stated, it would be very nice if @jball would revise his example to show an ideal form first so I needn't read all the fine print just to put a stinkin' comment in my reST. Also, I already assume I can put whatever I want into a comment, so all the extra symbols in the other examples only serve to complicate an otherwise simple answer ... unless those are relevant. Are they? – JFlo Feb 28 '18 at 21:42
@CecilCurry Thanks for your insight, I corrected my `ryd` documentation with that (And so we meet again!) – Anthon Jul 19 '18 at 11:30
So is line_1`..` with line_2 `This is a comment` fine? That is to say, could you delete the `_` and `:` from line_2 of your first example? It runs fine, but not sure implications. – Kermit Jan 28 '21 at 16:57
1

What about using `.. .. `? (dot dot space dot dot space) I've been using that on my .rst files... – pepoluan Mar 08 '21 at 14:11

score 27 · Answer 2 · answered Jul 30 '19 at 08:24

27

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

Example:

..
  comment goes here

answered Jul 30 '19 at 08:24

Miguel Mota

20,135
5
45
64

2

How to close the comment? – Sushivam Aug 30 '22 at 06:37
The comment closes automatically at the next non-indented line. – mhsmith Mar 14 '23 at 08:43

score 9 · Answer 3 · answered Oct 28 '19 at 18:46

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.

Dr. V · Answer 4 · 2020-07-27T15:21:01.067

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.

score 1 · Answer 5 · answered Jun 26 '22 at 00:04

The reference also gives a nice little diagram, which shows multi-line comments are easy:

Syntax Diagram

+-------+----------------------+
| ".. " | comment              |
+-------+ block                |
        |                      |
        +----------------------+

Here is an example from the reference that has been modified to show multi line comments:

.. This is a comment. At least one space before `This` needed. 
 This also gets commented. 1 space before `This also` works.
 As stated by others, comments on the same line as `..` 
 should not be used, to avoid confusion with proper markup constructs.
 And Yes, this entire paragraph is commented.

..    
    _so: is this! At least one space before `_so` needed.
    This also gets commented.
       Even more spaces also works.
    But I like to use a single tab.
..    
    [and] this! At least one space before `[and]` needed.
    This also gets commented.
..  
    this:: too! At least one space before `this` needed.
    this too.
..    
    |even| this:: ! At least one space before `|even|` needed.
    and this as well.
.. [this] however, is a citation.

score -11 · Answer 6 · answered Jan 24 '11 at 15:41

-11

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.

answered Jan 24 '11 at 15:41

yan

20,644
3
38
48

7

This answer would be better with an example. – Nathaniel M. Beaver Jul 29 '16 at 18:29
32

**This is an awful answer.** The conditionality of reStructuredText comments overly complicates matters. A pithy "RTFM" followed by a single-line quote does _not_ suffice here. What does and does not constitute a valid comment lexically depends on the content of that comment _and_ the syntax used to specify that comment. It's non-trivial, non-obvious, and tragically fragile. – Cecil Curry Aug 14 '16 at 01:09
4

@CecilCurry: Just like everything else in RST then. – mhsmith Jun 17 '18 at 12:44
@mhsmith - every language has it structures and syntax rules. RST is not immune to this immutable law. – sygibson Jun 09 '20 at 19:47

How to comment a string in restructured text?

6 Answers6