Python-sphinx: ignore text in .rst file

Question

I have a README.rst on GitHub that is also incorporated into the Sphinx-generated documentation for a Python project. I would like to include a note at the top of the file that will be shown on GitHub (which simply renders the .rst) but not shown in the Sphinx-generated docs.

I know that I can include a comment in an .rst file using .. blah blah blah, but is there some way that I can include a line that is only considered a comment by Sphinx? (Or, have that line otherwise ignored by Sphinx.)

Given that both Sphinx and GitHub would be interpreting it as RST, I don't see how you could have something that was a comment in one but not the other. — jonrsharpe
Well, you can have things like .. note:: that do things in Sphinx but don't do much in normal RST. And I suppose it doesn't need to be a comment, I would just like Sphinx to not include the text in the final generated docs. — DanHickstein

and1er and1er · Accepted Answer · 2019-02-04T13:56:17

You want a line in .rst file included on GitHub but ignored in your Sphinx documentations.

It could be achieved using ifconfig directive sphinx.ext.ifconfig – Include content based on configuration this way.

In your conf.py file check that sphinx.ext.ifconfig extension is enabled

# conf.py
extensions = [
    ...
    'sphinx.ext.ifconfig',
    ...
]

and register a variable

# conf.py
# custom variables
def setup(app):
    app.add_config_value(name='show_github_hote', default=True, rebuild='env')

# uncomment in Sphinx doc to hide the note
# show_github_hote = False

then in your .rst file

.. ifconfig:: show_github_hote

    THIS NOTE IS FOR GITHUB ONLY.

    Use bigger indentation for the note.

Further text with smaller indent.

If show_github_hote var is not set the value is True by default and the note should be printed. To hide the note set show_github_hote = False in conf.py.

Python-sphinx: ignore text in .rst file

1 Answers