mirror of
https://github.com/gnif/LookingGlass.git
synced 2024-09-19 08:51:33 +00:00
f6b2cec841
This new sphinx extension runs html.unescape (from the Python Standard Library) on source files before they are rendered, allowing escape sequences like ' ' for the no-break space character. I have also published this extension in my own name under a different license (the same one Sphinx uses) for others to use: https://github.com/JJRcop/sphinxcontrib-html_unescape
59 lines
2.1 KiB
Python
59 lines
2.1 KiB
Python
# Copyright 2023 The Looking Glass Authors
|
|
# https://looking-glass.io
|
|
#
|
|
# This program is free software; you can redistribute it and/or modify it
|
|
# under the terms of the GNU General Public License as published by the Free
|
|
# Software Foundation; either version 2 of the License, or (at your option)
|
|
# any later version.
|
|
#
|
|
# This program is distributed in the hope that it will be useful, but WITHOUT
|
|
# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
|
|
# more details.
|
|
#
|
|
# You should have received a copy of the GNU General Public License along
|
|
# with this program; if not, write to the Free Software Foundation, Inc., 59
|
|
# Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
|
|
|
|
# Call html.unescape on source files when building docs
|
|
#
|
|
# This converts named HTML character references: like '>' into '>',
|
|
# and numeric references: like '🔎' into '🔎'
|
|
#
|
|
# See https://docs.python.org/3/library/html.html#html.unescape
|
|
# and https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references
|
|
# for more information on available sequences
|
|
|
|
from html import unescape
|
|
|
|
# For type hints (PEP 484)
|
|
from sphinx.application import Sphinx
|
|
from sphinx.environment import BuildEnvironment
|
|
|
|
|
|
def unescape_source(app: Sphinx, docname: str, source: list) -> None:
|
|
env: BuildEnvironment = app.env
|
|
exclude: list = env.config.html_unescape_exclude
|
|
onlyinclude: list = env.config.html_unescape_onlyinclude
|
|
docpath: str = env.doc2path(docname, base=False)
|
|
if docname in exclude:
|
|
return
|
|
if docpath in exclude:
|
|
return
|
|
if len(onlyinclude) and not (docname in onlyinclude or docpath in onlyinclude):
|
|
return
|
|
source[0] = unescape(source[0])
|
|
|
|
|
|
def setup(app: Sphinx) -> dict[str, bool | str]:
|
|
app.add_config_value('html_unescape_exclude', [], 'env', [list])
|
|
app.add_config_value('html_unescape_onlyinclude', [], 'env', [list])
|
|
app.connect('source-read', unescape_source)
|
|
return {
|
|
'version': '1.0',
|
|
'env_version': '1.0',
|
|
'parallel_read_safe': True,
|
|
'parallel_write_safe': True,
|
|
}
|