CODEWITHSUNDEEP
pythonpython-3.xpython-sphinxrestructuredtext
blthayer
blthayer

Reputation: 922

Exclude reStructuredText comments in Sphinx HTML output

I'd like to add some comments into a reStructuredText document that do not show up when I build my documentation. For example, I'd like to put the following into a file:

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.

According to the Sphinx docs, "Depending on the output formatter, comments may be removed from the processed output." However, I don't see any options for that in the HTML output configuration docs.

I'm using Sphinx (sphinx-build) to build my docs. I used sphinx-quickstart to set things up, and thus build via make html.

Thanks in advance!

Upvotes: 0

Views: 1665

Answers (1)

Steve Piercy
Steve Piercy

Reputation: 15055

Your syntax is a little bit off. White space has meaning in reST. You must separate blocks with a blank line, like so:

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.

Edit

Comments are blocks, not inline. There is no inline comment syntax. However you could abuse substitutions.

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

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

You could also use a hack of specifying a CSS class via rst-class to a block that contains text that you want to comment, then use inline markup around the comment, and apply a custom style that has a CSS selector like .comment>strong that hides the comment from visual display in HTML.

#reST

.. rst-class:: comment

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

#CSS
p.comment>strong {display:none;}

Upvotes: 7

Related Questions