Python-sphinx: ignore text in .rst file

user_1078391 0
Viewed 1531

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.)

python-sphinx github python
1 Answers

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.

user_74447820
Related