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.)
You want a line in .rst
file included on GitHub but ignored in your Sphinx documentations.
It could be achieved using inconfig
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
.
The technical post webpages of this site follow the CC BY-SA 4.0 protocol. If you need to reprint, please indicate the site URL or the original address.Any question please contact:yoyou2525@163.com.